google-analytics-admin-api-basics

Name: google-analytics-admin-api-basics
Author: google

Google Analytics Admin API 入门指南

Google Analytics Admin API 允许你通过程序化方式访问和配置 Google Analytics 账号与媒体资源（Property）。你可以借助该 API 实现账号管理自动化、管理数据流、配置自定义维度以及处理各类产品集成。

通过 Cloud CLI 启用 API

在发起 API 调用之前，请确保你的 Google Cloud 项目中已启用 Google Analytics Admin API。

如果系统提示找不到 gcloud，请在运行以下命令前提示用户先安装 Google Cloud CLI。

启用 API： 使用 Cloud CLI（gcloud）启用 analyticsadmin.googleapis.com。
```
gcloud services enable analyticsadmin.googleapis.com --quiet
```
说明：启用 API 可确保你的 Cloud 项目获得管理 Google Analytics 配置所需的配额与权限。

验证 API 启用状态：

gcloud services list --enabled --filter="analyticsadmin.googleapis.com"

身份验证

要为 API 请求打通身份验证，你需要生成应用默认凭据（Application Default Credentials，简称 ADC），并为账号赋予必要的权限范围（Scopes）。在终端中运行以下命令：

gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.readonly"

说明：这会在本地环境中配置具有 Cloud Platform 以及 Google Analytics 只读权限范围的 ADC，从而允许客户端库自动对你的请求进行身份验证。

[!NOTE] 配置修改说明：对于修改 Google Analytics 账号/媒体资源配置的方法，需要提供 https://www.googleapis.com/auth/analytics.edit 权限范围。

Admin API 典型应用场景

你可以使用 Google Analytics Admin API 完成以下操作：

运行数据访问报告（Data Access reports，详见 https://developers.google.com/analytics/devguides/config/admin/v1/access-api.md.txt）
创建账号摘要信息
管理账号
程序化/新建账号
检索账号变更历史事件
管理与新建媒体资源
管理媒体资源的数据留存设置
管理转化事件
管理自定义维度与指标
管理数据流及配置 Measurement Protocol 密钥
管理 Firebase 关联
管理 Google Ads 关联
管理关键事件（Key events）

仅限 v1alpha 版支持的场景

以下功能目前仅在 Admin API 的 v1alpha 版本中提供：

管理账号与媒体资源的访问权限绑定（Access bindings）
创建与管理汇总媒体资源（Rollup properties）
创建与管理子媒体资源（Subproperties）
确认用户数据收集（Acknowledge user data collection）
修改媒体资源的归因模型、数据留存、Google signals、报告身份（Reporting identity）及用户提供的数据（User Provided Data）等设置
管理 AdSense 关联
管理 BigQuery 关联
管理受众群体（Audiences）
管理渠道分组（Channel groups）
管理计算指标（Calculated metrics）
管理 DisplayVideo360Advertiser 关联
管理扩展数据集（Expanded data sets）
管理报告数据标注（Reporting data annotations）
管理 SearchAds360 关联
管理数据流的事件创建规则
管理 iOS 数据流的 SKAdNetwork 转化值架构
提交 Google Analytics 媒体资源的用户数据删除请求

调用 Admin API

要与 Admin API 进行交互，请使用 Google 官方提供的 Google Analytics Admin 客户端库。请注意，v1beta 是目前最稳定的 Admin API 版本；如果需要使用最新功能，可考虑使用 v1alpha。

[!IMPORTANT] Agent 强制指令： 当用户选择或指定某种编程语言时，请务必阅读下方 references/ 目录中对应的客户端库配置参考指南。

支持的客户端库

Python

如需安装或配置 Python 版 Google Analytics Admin API 客户端库，请阅读配置指南：

Python 安装参考 （软件包：google-analytics-admin）

Java

如需安装或配置 Java 版 Google Analytics Admin API 客户端库，请阅读配置指南：

Java 安装参考 （构件：com.google.cloud:google-cloud-analytics-admin）

PHP

如需安装或配置 PHP 版 Google Analytics Admin API 客户端库，请阅读配置指南：

PHP 安装参考 （软件包：google/analytics-admin）

Node.js

如需安装或配置 Node.js 版 Google Analytics Admin API 客户端库，请阅读配置指南：

Node.js 安装参考 （软件包：@google-analytics/admin）

Go

如需安装或配置 Go 版 Google Analytics Admin API 客户端库，请阅读配置指南：

Go 安装参考 （软件包：cloud.google.com/go/analytics/admin/apiv1beta）

.NET

如需安装或配置 .NET / C# 版 Google Analytics Admin API 客户端库，请阅读配置指南：

.NET 安装参考 （软件包：Google.Analytics.Admin.V1Beta）

Ruby

如需安装或配置 Ruby 版 Google Analytics Admin API 客户端库，请阅读配置指南：

Ruby 安装参考 （Gem：google-analytics-admin-v1alpha）

[!NOTE] 其他参考资源：如果想获取使用 Java、PHP、Node.js、.NET、Python 和 REST 调用 Admin API 的更多示例，以及服务账号（Service Account）身份验证的相关提示，请参阅官方 Admin API 快速入门指南。关于 v1alpha 与 v1beta 的完整 API 参考文档，请参阅 Admin API 参考文档。

Python 快速入门

安装客户端库：
```
pip install google-analytics-admin
```
如果系统提示找不到 pip，请在安装客户端库前先提示用户安装 pip。

列出账号与媒体资源： 以下是一个完整的示例，展示如何调用 Admin API 的 list_account_summaries() 方法，列出当前用户可访问的所有账号及其下属的媒体资源。

from google.analytics.admin import AnalyticsAdminServiceClient

def sample_list_account_summaries():
    # 初始化客户端
    # 前提：本地环境中已配置好应用默认凭据 (ADC)
    client = AnalyticsAdminServiceClient()

    # list_account_summaries 会返回当前用户有权访问的所有账号及其下属媒体资源的摘要信息
    account_summaries = client.list_account_summaries()

    print("可用的 Google Analytics 账号与媒体资源：")
    for summary in account_summaries:
        print(f"账号：{summary.display_name} ({summary.account})")
        for property_summary in summary.property_summaries:
            print(f"  媒体资源：{property_summary.display_name} ({property_summary.property})")

if __name__ == "__main__":
    sample_list_account_summaries()