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

Question

我正在将 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

Quickstart 示例可以运行，但在添加 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 维度名称不是 Analytics 维度名称的名称，而是 Analytics 描述性名称的属性/参数吗？在一个地方，我读到后者:“自定义维度在 API 报告请求中由维度的参数名称和范围指定。”但在其他地方暗示 Name 是维度名称，例如/devguides/报告/数据/v1/高级:"维度": [{ "name": "customUser:last_level"}]

最后，即使与开发人员实现的内容一致，dimensionFilter 也会被“Expect Google\Analytics\Data\V1beta\Filter\StringFilter”取代

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

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

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',
        ]
    )
    ]
]);