Management API - 自定义维度和指标开发者指南

本文档介绍了如何使用 Management API 为获得授权的用户管理 Google Analytics(分析)自定义维度和指标。

简介

您可以使用 Management API 中的自定义维度和指标来为 Google Analytics(分析)媒体资源创建、获取、列出、更新和修补自定义维度和指标。要详细了解自定义维度和指标的工作原理,请参阅自定义维度和指标功能参考

Management API 中对自定义维度和指标管理自动化提供支持的两项资源是:

  1. 自定义维度资源,代表 Google Analytics(分析)中某个自定义维度的所有可用媒体资源和配置。
  2. 自定义指标资源,代表 Google Analytics(分析)中某个自定义指标的所有可用媒体资源和配置。

前提条件

所有 Google Analytics(分析)API 的访问方法都基本相同。在开始使用 Management API 之前,您应该:

  • 阅读客户端库页面,查看与该 API 配合使用的编程语言客户端库的完整列表。
  • 阅读参考指南,熟悉该 API 的界面,并了解如何在没有客户端库的情况下访问数据。

每个客户端库提供单个 Analytics 服务对象来访问所有的 Management API 数据。要创建服务对象,请执行以下操作:

  1. Google Developers Console 中注册您的应用。
  2. 授予访问 Google Analytics(分析)数据的权限。
  3. 创建一个 Analytics 服务对象。

如果您未能完成上述步骤,请停止操作,并阅读 Google Analytics(分析)API 入门教程。该指南将为您详细介绍构建 Google Analytics(分析)API 应用的最初几个步骤。完成这些步骤后,您将了解如何访问 Google Analytics(分析)API 以执行实际任务。

范围变更和数据不一致

有关详情,请参阅自定义维度和指标功能参考中的实现注意事项部分。

使用情形

通过 Management API 中的自定义维度和指标可以自动执行以下任务。

列出媒体资源的自定义维度和指标

要列出媒体资源的所有自定义维度或指标,请按以下步骤操作:

  1. 使用 Management API 或 Account Explorer 提取帐户 ID 和媒体资源 ID。
  2. 执行自定义维度或自定义指标资源的 list 方法。

参阅 API 参考,详细了解自定义维度自定义指标资源的 list 方法。

为媒体资源创建新的自定义维度和指标

要为媒体资源创建新的自定义维度或指标,请执行以下操作:

  1. 使用 Management API 或帐户浏览器提取帐户 ID 和媒体资源 ID。
  2. 对于自定义维度和指标,您必须提供 namescope;对于自定义指标,您还必须选择指标 type
  3. 执行自定义维度或自定义指标资源的 insert 方法。

参阅 API 参考,详细了解自定义维度自定义指标资源的 insert 方法。

更新媒体资源现有的自定义维度和指标

通过更新自定义维度或指标的名称、范围或类型,您还可能重新界定自定义维度或指标的用途。不过,我们建议您在执行此操作前先查看维度和指标变更的影响。

要更新媒体资源现有的自定义维度和指标,请按以下步骤操作:

  1. 使用 Management API 或帐户浏览器提取帐户 ID 和媒体资源 ID。
  2. 对于自定义维度和指标,您必须提供 namescope;对于自定义指标,您还必须设置指标 type
  3. 执行自定义维度或自定义指标资源的 update 方法。

忽略自定义数据源/数据集关联

如果您尝试使用 Management API 更新自定义数据源/数据集所用的自定义维度或指标,那么此操作不会成功,而且会返回错误。此行为意在防止维度或指标范围的意外变更,避免出现数据不一致的情况。要替换此行为并忽略任何警告,您可以在执行更新操作时将 ignoreCustomDataSourceLinks 参数设置为 true

代码示例

获得授权的用户可以通过自定义维度和自定义指标资源列出、获取、更新、修补和插入自定义维度和指标。要使用上述任何一种方法,您需要先按照前提条件部分的说明创建一个 Analytics 服务对象。

如需了解说明自定义维度和指标资源使用方法的代码示例,请访问以下方法参考:

管理自定义维度

  • list - 列出用户有权访问的自定义维度。
  • get - 获取用户有权访问的自定义维度。
  • insert - 创建新的自定义维度。
  • patch - 修补现有自定义维度。
  • update - 更新现有自定义维度。

管理自定义指标

  • list - 列出用户有权访问的自定义指标。
  • get - 获取用户有权访问的自定义指标。
  • insert - 创建新的自定义指标。
  • patch - 修补现有自定义指标。
  • update - 更新现有自定义指标。