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

【问题标题】：Why does Analytics Data API V1 Beta not conform to the REST spec?为什么 Analytics Data API V1 Beta 不符合 REST 规范？
【发布时间】：2021-05-17 20:25:39
【问题描述】：

我正在将 GTM 和 GA4 添加到一些需要生成有关每个广告客户的广告点击率的详细统计信息的网站应用程序中。这对于标准 GA 报告来说看起来是不可行的，所以我使用 Analytics Data API V1 Beta 的 PHP 实现。由于使用 PHP 进行 V1 报告的示例（例如 analyticsdata/quickstart.php）很少，我正在从 REST API 的 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

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

 "matchType": "BEGINS_WITH"

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

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

最后，即使与开发人员实现的一致，dimensionFilter 也因“Expect Google\Analytics\Data\V1beta\Filter\StringFilter”而失败

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

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

【问题讨论】：

这是您正在使用的 beta api 和 alpha 库。您是否尝试过报告错误？
感谢 DaimTo。我错误地认为相关的 PHP 类库是 Beta 版，并且不知道“API”特定代码和后台类库之间的区别。我相信我的自定义维度问题只是松弛的文档，但 match_type 问题是一个错误。向开发团队报告错误的最佳流程是什么（或者只是谷歌分析社区？）
我已将您的问题发送给 Google 的一位开发人员。看看我们是否无法清理您的一些文档问题。不过我不能保证他会直接回答你的问题。

标签： google-analytics google-analytics-api google-analytics-filters

【解决方案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',
        ]
    )
    ]
]);

【讨论】：

【解决方案2】：

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

1. 使用

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

代替：

'match_type' => ‘BEGINS_WITH’

修复了“未捕获的异常：期望整数。在 /vendor/google/protobuf/src/Google/Protobuf/Internal/GPBUtil.php”作为 MatchType::BEGINS_WITH (etc) 常量返回一个来自 MatchType 类的整数（在本例中为 2）。

2. 如果将提醒添加到自定义维度文档中使用维度名称的位置（例如 /devguides/reporting/data/v1/advanced: "dimensions": [{ "name": "customUser:last_level" }] 强调该名称不是为 Analytics 定义的维度名称，而是关联的用户属性/参数名称。或者也许应该修改 GA 的自定义维度“表单”中的名称标题。

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 (

【讨论】：