为什么 Analytics Data API V1 Beta 不符合 REST 规范？

Question

我正在将 GTM 和 GA4 添加到一些网站应用程序中，这些应用程序需要生成每个广告客户的广告点击率的详细统计信息。这在标准 GA 报告中看起来不可行，因此我使用 PHP Analytics Data API V1 Beta 的实施。由于使用 PHP 的 V1 报告的示例很少（例如 analyticsdata/quickstart.php），我正在翻译来自 REST API 的其他 classes 和操作数' s JSON .

<?php
namespace Google\Analytics\Data\V1beta;
require 'vendor/autoload.php';

$property_id = '<redacted>';

putenv('GOOGLE_APPLICATION_CREDENTIALS=Keyfile.json');

$client = new BetaAnalyticsDataClient();

// Make an API call.
$response = $client->runReport([
    'property' => 'properties/' . $property_id,
    
    'dateRanges' => [
        new DateRange([
            'start_date' => '2021-04-01',
            'end_date' => 'today',
        ]
        ),
    ],
    'dimensions' => [new Dimension(
        [
           'name' => 'customEvent:link_classes'
        ]
    ),
    ],
        
     'dimensionFilter'=>[new FilterExpression(
           [
           'filter'=>[new Filter(
           [
          'field_name' => 'customEvent:Classes',
          'string_filter' => [new Filter\StringFilter(
          [
          'match_type'=> '1',
          'value'=> 'AdvertA',
          'case_sensitive'=> false 
          ])]])]])],
    
    'metrics' => [new Metric(
        [
            'name' => 'eventCount',
        ]
    )
    ]
]);
etc

Quickstart 示例可以运行，但在添加 dimensionFilter 时会遇到无穷无尽的麻烦。例如，match_type 应该是几个字符串（EXACT、CONTAINS 等）之一的枚举。 match_type 的 JSON 定义仅显示字符串（枚举 'members'）而不显示任何关联值（通常是整数）。 GA4 迁移指南有一个示例

 "matchType": "BEGINS_WITH"

PHP 没有“枚举”，但等效于 select 一个字符串并将其分配给 match_type（见上文）。错误：StringFilter 失败，除非给它一个整数操作数，大概是枚举匹配字符串中所需匹配的序号（第一个是 0 还是 1？）。我对 JSON 模式的理解是 'enum' 列表只是将结果限制为唯一操作数之一，并可选择检查操作数类型。（相比之下，Python 枚举函数 returns 包含一个对列表的对象，其中操作数的序号位于操作数之前）。

自定义尺寸 似乎不符合 API 的 JSON。在 Analytics 中，我指定了一个自定义维度，维度名称为类，用户 Property/Parameter 为 link_classes**。但是...在 API 中，维度名称必须是 customEvent:link_classes 而不是 customEvent:Classes。否则它会以“Field customEvent:Classes is not a valid dimension”而失败在过滤器表达式中的过滤器中定义 field_name 时也会发生这种情况。那么 API 维度名称不是 Analytics 维度名称的名称，而是 Analytics 描述性名称的 Property/Parameter 吗？在一个地方，我读到后者：“自定义维度在 API 报告请求中由维度的 参数名称 和范围 指定。 “但在其他地方暗示 Name 是维度名称，例如/devguides/reporting/data/v1/advanced: "维度": [{ "名称": "customUser:last_level" }]

最后，即使与开发人员实现的一致，dimensionFilter 也落在了“Expect Google\Analytics\Data\V1beta\Filter\StringFilter”

它是 Beta 代码，但不会与 REST 规范有明显的偏差，所以也许我错误地阅读了规范。还有其他人有这个问题吗？

** GTM 有一个“点击 - 仅链接”触发器，其中“点击 URL”“包含”广告商的 URL。 API 维度过滤器中的类自定义维度具有广告点击链接的 class 值。

Answer 1

为了回答你问题的第一部分，我相信在 PHP 中使用枚举的正确方法是：

'match_type' => Filter\StringFilter\MatchType::BEGINS_WITH

关于第二个问题。根据 the API schema documentation，自定义维度的名称构造为 customEvent:parameter_name（对于事件范围的维度）和 customUser:parameter_name（对于用户范围的维度）。正如您正确指出的那样，parameter_name 不是描述性名称，而是事件参数名称。在您的示例中，您似乎正在使用用户范围的维度，因此 API 中的维度名称应为 customUser:link_classes.

这是一个看起来运行不错的完整示例：

require 'vendor/autoload.php';

use Google\Analytics\Data\V1beta\BetaAnalyticsDataClient;
use Google\Analytics\Data\V1beta\DateRange;
use Google\Analytics\Data\V1beta\Dimension;
use Google\Analytics\Data\V1beta\FilterExpression;
use Google\Analytics\Data\V1beta\Filter;
use Google\Analytics\Data\V1beta\Metric;

/**
 * TODO(developer): Replace this variable with your Google Analytics 4
 *   property ID before running the sample.
 */
$property_id = 'YOUR-GA4-PROPERTY-ID';


$client = new BetaAnalyticsDataClient();

// Make an API call.
$response = $client->runReport([
    'property' => 'properties/' . $property_id,
    'dateRanges' => [
        new DateRange([
            'start_date' => '2020-03-31',
            'end_date' => 'today',
        ]),
    ],
    'dimensions' => [new Dimension(
        [
            'name' => 'customUser:link_classes'
        ]),
    ],

    'dimensionFilter' => new FilterExpression(
        [
            'filter' => new Filter(
                [
                    'field_name' => 'customUser:link_classes',
                    'string_filter' => new Filter\StringFilter(
                        [
                            'match_type' => Filter\StringFilter\MatchType::BEGINS_WITH,
                            'value' => 'AdvertA',
                            'case_sensitive' => false
                        ]
                    )
                ])

        ]),

    'metrics' => [new Metric(
        [
            'name' => 'eventCount',
        ]
    )
    ]
]);

Answer 2

非常感谢 Ilya 的最有用、最及时和最正确的回复。三分：

1. 使用

'match_type' => Filter\StringFilter\MatchType::BEGINS_WITH

而不是：

'match_type' => ‘BEGINS_WITH’

修复了“Uncaught Exception: Expect integer.在 /vendor/google/protobuf/src/Google/Protobuf/Internal/GPBUtil.php” 作为 MatchType::BEGINS_WITH (etc) 常量 returns 来自 class MatchType.

的整数（在本例中为 2）

2. 如果在自定义维度文档中使用维度名称的地方添加提示，则可以防止错误，例如 /devguides/reporting/data/v1/advanced: "维度": [{ "名称": "自定义用户:last_level" }] 强调该名称不是为 Analytics 定义的维度名称，而是关联的用户 Property/Parameter 名称。或者 GA 的自定义维度 'form' 中的名称标题应该修改。

3. 最后，dimensionFilter 落在

 ‘Expect Google\Analytics\Data\V1beta\Filter\StringFilter’

错误消息是由于我在实例化 FilterExpression、Filter 和 StringFilter 时的愚蠢行为，就好像它们是数组元素一样，例如

'string_filter' => [new Filter\StringFilter(

而不是

'string_filter' => new Filter\StringFilter(

不幸的是，当不小心遵循示例报告代码时很容易犯错误，其中 dateRanges、维度等正确定义数组（因为它们可以采用多个日期范围和维度），例如

   'dimensions' => [new Dimension (

为什么 Analytics Data API V1 Beta 不符合 REST 规范？

Why does Analytics Data API V1 Beta not conform to the REST spec?

google-analytics

google-analytics-api

google-analytics-filters