此页面由 Cloud Translation API 翻译。

高级用例

本文档介绍了 Google Analytics（分析）Data API v1 的几项高级功能。有关该 API 的详细参考，请参阅 API 参考。

列出自定义定义并创建报告

Data API 可以针对已注册的自定义维度和自定义指标创建报告。Metadata API 方法可用于列出媒体资源已注册自定义定义的 API 名称。这些 API 名称可以在向 runReport 方法发出的报告请求中使用这些 API 名称。

以下各部分显示了每种自定义设置的示例。在这些示例中，请将 GA4_PROPERTY_ID 替换为您的媒体资源 ID。

事件级范围的自定义维度

第 1 步：使用媒体资源 ID 查询 Metadata API 方法。

GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata

第 2 步：从响应中找到您想要创建报告的事件级范围的自定义维度。如果维度不存在，您需要注册维度。

"dimensions": [
...
    {
      "apiName": "customEvent:achievement_id",
      "uiName": "Achievement ID",
      "description": "An event scoped custom dimension for your Analytics property."
    },
...
],

第 3 步：在报告请求中添加自定义维度。以下是对 runReport 方法的示例请求。

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
  "dimensions": [{ "name": "customEvent:achievement_id" }],
  "metrics": [{ "name": "eventCount" }]
}

用户级范围的自定义维度

第 1 步：使用媒体资源 ID 查询 Metadata API 方法。

GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata

第 2 步：从响应中找到您想要创建报告的用户级范围的自定义维度。如果维度不存在，您需要注册维度。

"dimensions": [
...
    {
      "apiName": "customUser:last_level",
      "uiName": "Last level",
      "description": "A user property for your Analytics property."
    },
...
],

第 3 步：在报告请求中添加自定义维度。以下是对 runReport 方法的示例请求。

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "entity": { "propertyId": "GA4_PROPERTY_ID" },
  "dateRanges": [{ "startDate": "7daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "customUser:last_level" }],
  "metrics": [{ "name": "activeUsers" }]
}

事件级范围的自定义指标

第 1 步：使用媒体资源 ID 查询 Metadata API 方法。

GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata

第 2 步：从响应中找到您想要为其创建报告的事件级范围的自定义指标。如果该指标不存在，您需要注册该指标。

"metrics": [
...
    {
      "apiName": "customEvent:credits_spent",
      "uiName": "Credits Spent",
      "description": "An event scoped custom metric for your Analytics property.",
      "type": "TYPE_STANDARD"
    },
...
],

第 3 步：在报告请求中添加自定义指标。以下是对 runReport 方法的示例请求。

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "customEvent:credits_spent" }]
}

一种关键事件的关键事件率指标

第 1 步：使用媒体资源 ID 查询 Metadata API 方法。

GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata

第 2 步：根据响应找到您想要为其创建报告的关键事件率指标。如果按键事件不存在，您需要设置按键事件。

"metrics": [
...
    {
      "apiName": "sessionKeyEventRate:add_to_cart",
      "uiName": "Session key event rate for add_to_cart",
      "description": "The percentage of sessions in which a specific key event was triggered",
    },
...
],

第 3 步：在报告请求中添加关键事件率指标。以下是对 runReport 方法的示例请求。

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "sessionKeyEventRate:add_to_cart" }]
}

事件级范围的自定义指标平均值

第 1 步：使用媒体资源 ID 查询 Metadata API 方法。

GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata

第 2 步：根据响应找到您想要为其创建报告的事件级范围的自定义指标平均值。如果该指标不存在，您需要注册该指标。

"metrics": [
...
    {
      "apiName": "averageCustomEvent:credits_spent",
      "uiName": "Average Credits Spent",
      "description": "The average of an event scoped custom metric for your Analytics property.",
      "type": "TYPE_STANDARD"
    },
...
],

第 3 步：在报告请求中添加自定义指标平均值。以下是对 runReport 方法的示例请求。

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "2020-11-01", "endDate": "2020-11-10" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "averageCustomEvent:credits_spent" }]
}

同类群组报告示例

同类群组报告会为同类群组创建用户留存率时间序列。如需查看每个 API 字段的详细文档，请参阅 CohortSpec 的 REST 参考文档。

创建同类群组报告

以下是一个同类群组报告示例，其中：

同类群组是指 firstSessionDate 为 2020-12-01 的用户；这由 cohorts 对象配置。报告响应中的维度和指标将仅基于同类群组的用户。
同类群组报告将显示三列；这由维度和指标对象配置。
- 维度 cohort 是同类群组的名称。
- 维度 cohortNthDay 是指自 2020-12-01以来的天数。
- “cohortActiveUsers”指标是指仍活跃的用户数。
cohortsRange 对象指定报告应包含此同类群组从 2020-12-01 至 2020-12-06 的事件数据。
- 使用 DAILY 粒度时，建议使用维度 cohortNthDay 以确保一致性。

同类群组的报告请求为：

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "dimensions": [{ "name": "cohort" }, { "name": "cohortNthDay" }],
  "metrics": [{ "name": "cohortActiveUsers" }],
  "cohortSpec": {
    "cohorts": [
      {
        "dimension": "firstSessionDate",
        "dateRange": { "startDate": "2020-12-01", "endDate": "2020-12-01" }
      }
    ],
    "cohortsRange": {
      "endOffset": 5,
      "granularity": "DAILY"
    }
  },
}

对于此请求，报告响应示例如下：

{
  "dimensionHeaders": [
    { "name": "cohort" }, { "name": "cohortNthDay" }
  ],
  "metricHeaders": [
    { "name": "cohortActiveUsers", "type": "TYPE_INTEGER" }
  ],
  "rows": [
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0000" }],
      "metricValues": [{ "value": "293" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0001" }],
      "metricValues": [{ "value": "143" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0002" }],
      "metricValues": [{ "value": "123" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0003" }],
      "metricValues": [{ "value": "92" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0005" }],
      "metricValues": [{ "value": "86" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0004" }],
      "metricValues": [{ "value": "83" }]
    }
  ],
  "metadata": {},
  "rowCount": 6
}

该报告响应中给出了此同类群组报告的图表。此报告中的一个数据洞见是，此同类群组的活跃用户数量下降最明显发生在第一天和第二天之间。

直观呈现同类群组用户随时间变化的情况

多个同类群组和用户留存率

用户获取和用户留存是拓展网站或应用业务的途径。同类群组报告侧重于用户留存率。在此示例中，报告显示该媒体资源在两周内将其 4 天的用户留存率提高了 10%。

为了创建此报告，我们指定了三个同类群组：第一个同类群组的 firstSessionDate 为 2020-11-02，第二个的 firstSessionDate 为 2020-11-09，第三个的 firstSessionDate 为 2020-11-16。由于这三天您媒体资源上的用户数各不相同，因此我们会比较同类群组的用户留存率比例指标 cohortActiveUsers/cohortTotalUsers，而不是直接使用 cohortActiveUsers 指标。

针对这些同类群组的报告请求为：

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "dimensions": [{ "name": "cohort" },{ "name": "cohortNthDay" }],
  "metrics": [
    {
      "name": "cohortRetentionFraction",
      "expression": "cohortActiveUsers/cohortTotalUsers"
    }
  ],
  "cohortSpec": {
    "cohorts": [
      {
        "dimension": "firstSessionDate",
        "dateRange": { "startDate": "2020-11-02", "endDate": "2020-11-02" }
      },
      {
        "dimension": "firstSessionDate",
        "dateRange": { "startDate": "2020-11-09", "endDate": "2020-11-09" }
      },
      {
        "dimension": "firstSessionDate",
        "dateRange": { "startDate": "2020-11-16", "endDate": "2020-11-16" }
      }
    ],
    "cohortsRange": {
      "endOffset": 4,
      "granularity": "DAILY"
    }
  },
}

对于此请求，报告响应示例如下：

{
  "dimensionHeaders": [{ "name": "cohort" },{ "name": "cohortNthDay" }],
  "metricHeaders": [{
      "name": "cohortRetentionFraction",
      "type": "TYPE_FLOAT"
    }
  ],
  "rows": [
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0000" }],
      "metricValues": [{ "value": "1" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0000" }],
      "metricValues": [{ "value": "1" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0000" }],
      "metricValues": [{ "value": "1" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0001" }],
      "metricValues": [{ "value": "0.308" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0001" }],
      "metricValues": [{ "value": "0.272" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0002" }],
      "metricValues": [{ "value": "0.257" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0001" }],
      "metricValues": [{ "value": "0.248" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0003" }],
      "metricValues": [{ "value": "0.235" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0004" }],
      "metricValues": [{ "value": "0.211" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0002" }],
      "metricValues": [{ "value": "0.198" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0002" }],
      "metricValues": [{ "value": "0.172" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0003" }],
      "metricValues": [{ "value": "0.167" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0004" }],
      "metricValues": [{ "value": "0.155" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0003" }],
      "metricValues": [{ "value": "0.141" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0004" }],
      "metricValues": [{ "value": "0.118" }]
    }
  ],
  "metadata": {},
  "rowCount": 15
}

该报告响应中给出了此同类群组报告的图表。这份报告发现，在两周内，4 天的用户留存率增加了 10%。“firstSessionDate”为 2020-11-16 的后期同类群组超过了“firstSessionDate”为“2020-11-02”的上一个同类群组的保留期限。

多个同类群组留存率的图表

每周同类群组以及将同类群组与其他 API 功能结合使用

要消除用户行为的每日差异，请使用每周同类群组。在每周的同类群组报告中，所有在同一周内具有 firstSessionDate 的用户构成同类群组。一周从星期日开始，到星期六结束。此外，此报告还对同类群组进行了细分，以比较在俄罗斯有活动的用户与在墨西哥有活动的用户。此切片使用 country 维度和 dimensionFilter，以仅考虑这两个国家。

针对这些同类群组的报告请求为：

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "dimensions": [
    { "name": "cohort" },
    { "name": "cohortNthWeek" },
    { "name": "country" }
  ],
  "metrics": [{ "name": "cohortActiveUsers" }],
  "dimensionFilter": {
    "filter": {
      "fieldName": "country",
      "inListFilter": {
        "values": [ "Russia", "Mexico" ]
      }
    }
  },
  "cohortSpec": {
    "cohorts": [
      {
        "dimension": "firstSessionDate",
        "dateRange": {
          "startDate": "2020-10-04",
          "endDate": "2020-10-10"
        }
      }
    ],
    "cohortsRange": {
      "endOffset": 5,
      "granularity": "WEEKLY"
    }
  },
}

对于此请求，报告响应示例如下：

{
  "dimensionHeaders": [
    { "name": "cohort" },
    { "name": "cohortNthWeek" },
    { "name": "country" }
  ],
  "metricHeaders": [
    { "name": "cohortActiveUsers", "type": "TYPE_INTEGER" }
  ],
  "rows": [
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0000" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "105" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0000" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "98" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0001" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "35" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0002" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "24" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0001" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "23" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0004" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "17" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0003" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "15" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0005" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "15" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0002" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "3" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0003" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "1" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0004" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "1" }]
    }
  ],
  "metadata": {},
  "rowCount": 11
}

下面显示了这份“同类群组”报告的图表。根据此报告，与在俄罗斯有活动的用户相比，此媒体资源在留住有活动的用户方面表现更好。

国家/地区比较同类群组图表

比较

借助比较项，您可以对照评估数据的不同子集。您可以通过在报告定义中指定 comparisons 字段来定义对比项。Data API 的比较功能与 Google Analytics（分析）前端中的比较功能类似。

如需查看每个 API 字段的详细文档，请参阅用于比较的 REST 参考文档。

创建对比项

您可以为要比较的每个数据集创建单独的比较项。例如，若要比较应用和网站数据，您可以针对 Android 和 iOS 数据创建一个对比项，针对网站数据创建另一个对比项。

下面是一个示例报告，其中定义了两种对比项，并返回按国家/地区细分的活跃用户数。

第一个名为“应用流量”的比较使用 inListFilter 将 platform 维度与值“iOS”和“Android”进行匹配。名为“网络流量”的第二个比较项使用 stringFilter 将 platform 维度与“网站”进行匹配。

  POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
  {
    "comparisons": [
      {
        "name": "App traffic",
        "dimensionFilter": {
          "filter": {
            "fieldName": "platform",
            "inListFilter": {
              "values": [
                "iOS",
                "Android"
              ]
            }
          }
        }
      },
      {
        "name": "Web traffic",
        "dimensionFilter": {
          "filter": {
            "fieldName": "platform",
            "stringFilter": {
              "matchType": "EXACT",
              "value": "web"
            }
          }
        }
      }
    ],
    "dateRanges": [
      {
        "startDate": "2024-05-01",
        "endDate": "2024-05-15"
      }
    ],
    "dimensions": [
      {
        "name": "country"
      }
    ],
    "metrics": [
      {
        "name": "activeUsers"
      }
    ]
  }

对于使用比较功能的所有请求，comparison 字段会自动添加到生成的报告中。此字段包含请求中提供的比较项的名称。

以下是包含比较项的响应的示例代码段：

{
  "dimensionHeaders": [
    {
      "name": "comparison"
    },
    {
      "name": "country"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  "rows": [
    {
      "dimensionValues": [
        {
          "value": "Web traffic"
        },
        {
          "value": "United States"
        }
      ],
      "metricValues": [
        {
          "value": "638572"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "Web traffic"
        },
        {
          "value": "Japan"
        }
      ],
      "metricValues": [
        {
          "value": "376578"
        }
      ]
    },
  {
      "dimensionValues": [
        {
          "value": "App traffic"
        },
        {
          "value": "United States"
        }
      ],
      "metricValues": [
        {
          "value": "79527"
        }
      ]
    },

    ...

  ],

...

}