Google Analytics Admin API 入门指南：基于 gcloud 与官方客户端库自动化 GA 账号、数据流与转化事件配置

Google Analytics Admin API 入门指南：基于 gcloud 与官方客户端库自动化 GA 账号、数据流与转化事件配置

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills

导读

本文基于开源仓库 skills29/skills 中的 google-analytics-admin-api-basics 技能，系统讲解如何通过 Google Analytics Admin API 以编程方式管理 GA 账号与资源配置：包括用 Cloud CLI（gcloud）启用 API、通过 Application Default Credentials（ADC）完成认证，以及使用 Python、Java、PHP、Node.js、Go、.NET、Ruby 七种官方客户端库进行账号、数据流、自定义维度、转化事件与集成管理的实战方法。读完本文，你将掌握从"启用服务"到"第一条 Admin API 调用"的完整链路，并能针对生产环境的读写操作正确选择 OAuth 作用域与 API 版本（v1beta / v1alpha）。

一、Admin API 能做什么：程序化配置 GA 的入口

Google Analytics Admin API 为 Google Analytics 的账号与资源（Account & Property）配置提供了程序化访问能力，是构建 GA 自动化运营体系的基础。它能够自动完成账号管理、数据流（Data Stream）管理、自定义维度配置以及产品集成对接等任务。

在仓库中，该技能被归类于 analytics 目录，与 google-analytics-data-api-basics（负责报表数据读取的 Data API）形成互补：Admin API 管"配置"，Data API 管"数据"。

二、第一步：通过 Cloud CLI 启用 Admin API

在发起任何 API 调用之前，必须确保你的 Google Cloud 项目中已启用 Google Analytics Admin API 服务（服务名为analyticsadmin.googleapis.com）。

前置条件：本机需要安装 Google Cloud CLI（gcloud）。如果gcloud不存在，应先提示用户安装 Google Cloud CLI，再执行以下命令。

1. 启用 API

gcloud services enable analyticsadmin.googleapis.com --quiet

为什么需要这一步：启用该服务后，Cloud 项目才会为管理 Google Analytics 配置分配相应的配额（quota）与权限，后续的 API 请求才能被正常受理。

2. 验证 API 是否已启用

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

该命令会过滤出当前项目已启用服务中与analyticsadmin.googleapis.com匹配的记录；若在输出中能看到该服务名，说明启用成功。

提示：--quiet参数用于跳过交互式确认，适合在 CI/CD 或自动化脚本中执行。

三、认证：配置 ADC 与正确的 OAuth 作用域

认证是调用 Admin 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"

为什么需要这一步：该命令会在本地环境配置 ADC，并附带 Cloud Platform 与 Google Analytics 只读（read-only）作用域，使客户端库能够在发起请求时自动完成认证，无需在代码中硬编码密钥。

作用域选择的关键约束

[!NOTE]配置变更方法的作用域要求：任何会修改GA 账号/资源配置的方法（例如创建资源、修改数据留存设置、创建转化事件等），都需要额外授予https://www.googleapis.com/auth/analytics.edit作用域。

因此，实际使用时应根据操作类型选择作用域组合：

四、Admin API 典型使用场景

该技能明确列出的 Admin API 能力覆盖了 GA 配置管理的完整生命周期：

• 数据访问报告（Data Access reports）：运行数据访问审计报告，官方文档中称为 Access API
• 账号摘要（Account summaries）：创建并读取账号摘要
• 账号管理：管理账号、预置新账号（provision new accounts）
• 审计：检索账号变更历史事件（change history events）
• 资源管理：创建与管理资源（properties）
• 数据留存：管理资源的 data retention 设置
• 转化管理：管理转化事件（conversion events）与关键事件（key events）
• 维度与指标：管理自定义维度（custom dimensions）与自定义指标（custom metrics）
• 数据流：管理数据流（data streams）并配置 Measurement Protocol secrets
• 集成管理：管理 Firebase 链接与 Google Ads 链接

v1alpha 专属能力（仅更高版本可用）

以下能力目前仅在 Admin API 的v1alpha版本中提供，使用前需确认你所引用的客户端库版本支持：

• 管理账号与资源的访问绑定（access bindings）
• 创建和管理汇总资源（rollup properties）
• 创建和管理子资源（subproperties）
• 确认用户数据收集（acknowledge user data collection）
• 变更资源的归因（attribution）、数据留存、Google signals、报表身份（reporting identity）以及 User Provided Data 设置
• 管理 AdSense 链接
• 管理 BigQuery 链接
• 管理受众群体（audiences）
• 管理渠道分组（channel groups）
• 管理计算指标（calculated metrics）
• 管理 DisplayVideo360Advertiser 链接
• 管理扩展数据集（expanded data sets）
• 管理报表数据注释（reporting data annotations）
• 管理 SearchAds360 链接
• 为数据流管理事件创建规则（event create rules）
• 管理 iOS 数据流的 SKAdNetwork 转化值 schema
• 为 GA 资源提交用户删除请求（user deletion request）

版本选型建议：v1beta是 Admin API 最稳定的版本，适合生产环境；v1alpha提供最新特性但可能包含不稳定的 API 变更。追求稳定选 v1beta，追求新功能可评估 v1alpha。

五、调用 Admin API：官方客户端库一览

与 Admin API 交互应使用官方 Google Analytics Admin 客户端库。仓库为 7 种语言提供了独立的安装与快速开始参考文档，均放在技能的 references 目录下：

[!IMPORTANT]Agent 使用指令：当用户选定或要求特定编程语言时，应读取对应的客户端库安装参考指南（即上表中的文档），再给出安装与使用建议。

Python：在虚拟环境中安装

参考 python.md，前置要求为Python 3.8+、pip以及配置好的 ADC。

python3 -m venv .venv source .venv/bin/activate pip install google-analytics-admin

将单个包安装在虚拟环境中，可避免与系统标准库发生版本冲突。若pip不可用，应先提示用户安装 Python 与pip。

Node.js：npm 安装

参考 nodejs.md，前置要求为Node.js v14.x 以上（推荐 v16+）、npm或yarn。

npm install @google-analytics/admin

该包会一并拉取官方的 gRPC 与 REST 客户端绑定。

Java：Maven / Gradle 依赖

参考 java.md，前置要求为JDK 8+（推荐 11+）、Maven 或 Gradle。

Maven（pom.xml的<dependencies>内）：

<dependency> <groupId>com.google.cloud</groupId> <artifactId>google-cloud-analytics-admin</artifactId> <version>LATEST_LIBRARY_VERSION</version> </dependency>

Gradle（build.gradle的dependencies块）：

implementation 'com.google.cloud:google-cloud-analytics-admin:LATEST_LIBRARY_VERSION'

使用 Maven 可自动解析传递依赖（如 Netty、gRPC、Google Auth Library）。务必把LATEST_LIBRARY_VERSION替换为 Maven Central 上的最新稳定版本。

Go：go get 安装

参考 go.md，前置要求为Go 1.19+、启用 Go modules。

go get cloud.google.com/go/analytics/admin/apiv1beta

该命令会把 Admin API 客户端包及其 gRPC 传输依赖写入go.mod。

.NET：NuGet 安装

参考 dotnet.md，前置要求为.NET Core 3.1 / .NET Standard 2.0 / .NET 6.0+。

.NET CLI 方式：

dotnet add package Google.Analytics.Admin.V1Beta

Visual Studio 包管理器控制台方式：

Install-Package Google.Analytics.Admin.V1Beta

该 NuGet 包包含强类型 protobuf 模型与 gRPC 服务客户端。

PHP：Composer 安装

参考 php.md，前置要求为PHP 8.0+、Composer。

composer require google/analytics-admin

Composer 会安装客户端库、autoloader 以及认证相关依赖。

Ruby：RubyGems / Bundler 安装

参考 ruby.md，前置要求为Ruby 3.0+、RubyGems / Bundler。

gem install google-analytics-admin-v1alpha

或加入Gemfile后执行bundle install：

gem "google-analytics-admin-v1alpha"

注意：Ruby 的官方 gem 当前指向v1alpha版本，使用前请确认与你的 API 版本需求一致。

六、Python 快速开始：列出账号与资源

主文档提供了完整的 Python 快速开始示例，其核心方法是list_account_summaries()——它会返回当前用户可访问的所有账号及其子资源的摘要信息，是验证 Admin API 连通性与权限配置是否正确的"Hello World"。

1. 安装客户端库

pip install google-analytics-admin

2. 列出账号与资源

from google.analytics.admin import AnalyticsAdminServiceClient def sample_list_account_summaries(): # 初始化客户端。 # 假设环境中已配置 Application Default Credentials (ADC)。 client = AnalyticsAdminServiceClient() # list_account_summaries 返回当前用户可访问的所有账号摘要及其子资源。 account_summaries = client.list_account_summaries() print("Available Google Analytics Accounts and Properties:") for summary in account_summaries: print(f"Account: {summary.display_name} ({summary.account})") for property_summary in summary.property_summaries: print(f" Property: {property_summary.display_name} ({property_summary.property})") if __name__ == "__main__": sample_list_account_summaries()

该示例展示的调用模式可推广到其他管理方法：初始化客户端（自动通过 ADC 认证）→ 调用list_account_summaries()→ 遍历账号与子资源摘要。其中：

• summary.account是账号的资源名（形如accounts/123456）；
• summary.property_summaries是该账号下的资源摘要列表，每个资源可通过property_summaries迭代访问。

其他语言的等价调用

仓库各语言参考文档均提供了基于ListAccountSummaries的等价快速开始，便于对照学习：

• Java（java.md）：使用try-with-resources自动关闭 gRPC 通道，client.listAccountSummaries().iterateAll()迭代账号摘要：

import com.google.analytics.admin.v1beta.AnalyticsAdminServiceClient; import com.google.analytics.admin.v1beta.AccountSummary; public class AdminApiDemo { public static void main(String[] args) throws Exception { // 初始化客户端，自动通过 ADC 认证。 try (AnalyticsAdminServiceClient client = AnalyticsAdminServiceClient.create()) { for (AccountSummary summary : client.listAccountSummaries().iterateAll()) { System.out.printf("Account: %s (%s)%n", summary.getDisplayName(), summary.getName()); } } } }

• Node.js（nodejs.md）：返回解构为[accountSummaries]数组：

const {AnalyticsAdminServiceClient} = require('@google-analytics/admin'); async function listAccounts() { // 初始化客户端，使用执行环境中的 ADC。 const analyticsAdminClient = new AnalyticsAdminServiceClient(); const [accountSummaries] = await analyticsAdminClient.listAccountSummaries(); console.log('Available Accounts:'); for (const account of accountSummaries) { console.log(`Account: ${account.displayName} (${account.name})`); } } listAccounts().catch(console.error);

• Go（go.md）：使用迭代器模式遍历，注意iterator.Done结束判断：

package main import ( "context" "fmt" "log" admin "cloud.google.com/go/analytics/admin/apiv1beta" "cloud.google.com/go/analytics/admin/apiv1beta/adminpb" "google.golang.org/api/iterator" ) func main() { ctx := context.Background() // 初始化客户端，自动通过 ADC 认证。 client, err := admin.NewAnalyticsAdminClient(ctx) if err != nil { log.Fatalf("Failed to create client: %v", err) } defer client.Close() req := &adminpb.ListAccountSummariesRequest{} it := client.ListAccountSummaries(ctx, req) for { resp, err := it.Next() if err == iterator.Done { break } if err != nil { log.Fatalf("Error iterating account summaries: %v", err) } fmt.Printf("Account: %s (%s)\n", resp.DisplayName, resp.Name) } }

• .NET（dotnet.md）：CreateAsync()初始化，await foreach迭代异步流：

using System; using System.Threading.Tasks; using Google.Analytics.Admin.V1Beta; class Program { static async Task Main() { // 初始化客户端，使用 Application Default Credentials。 AnalyticsAdminServiceClient client = await AnalyticsAdminServiceClient.CreateAsync(); // 列出账号摘要 var response = client.ListAccountSummariesAsync(new ListAccountSummariesRequest()); await foreach (AccountSummary summary in response) { Console.WriteLine($"Account: {summary.DisplayName} ({summary.Name})"); } } }

• PHP（php.md）：先引入 Composer autoloader：

require_once __DIR__ . '/vendor/autoload.php'; use Google\Analytics\Admin\V1beta\Client\AnalyticsAdminServiceClient; use Google\Analytics\Admin\V1beta\ListAccountSummariesRequest; // 初始化客户端，使用环境中的 ADC。 $client = new AnalyticsAdminServiceClient(); $request = new ListAccountSummariesRequest(); $accountSummaries = $client->listAccountSummaries($request); foreach ($accountSummaries as $summary) { printf("Account: %s (%s)\n", $summary->getDisplayName(), $summary->getName()); }

• Ruby（ruby.md）：注意命名空间为V1alpha：

require "google/analytics/admin/v1alpha" # 初始化客户端，自动通过 ADC 认证。 client = Google::Analytics::Admin::V1alpha::AnalyticsAdminService::Client.new account_summaries = client.list_account_summaries account_summaries.each do |summary| puts "Account: #{summary.display_name} (#{summary.name})" end

七、延伸阅读：从入门到生产级应用

完成账号与资源列举之后，可基于同一套认证与客户端初始化模式继续深入：

• 创建/管理数据流（Web、Android、iOS）并配置 Measurement Protocol secrets；
• 管理自定义维度、自定义指标与转化事件/关键事件；
• 管理数据留存设置与 Firebase、Google Ads 链接；
• 若需要读取报表数据，可参考配套的 google-analytics-data-api-basics 技能，它对应 Google Analytics Data API，负责查询会话、用户、转化等报表指标；
• 官方还提供了 Admin API Quickstart（Java、PHP、Node.js、.NET、Python、REST 各语言示例）以及 v1alpha / v1beta 完整 API 参考文档，可作为进阶查阅资料。

八、常见问题速查

结语

Google Analytics Admin API 是 GA 配置自动化的核心入口。通过本文的完整链路——gcloud启用服务 → ADC 认证与作用域选择 → 七种语言的官方客户端库安装 →list_account_summaries()快速开始——你可以快速搭建起账号/资源管理、数据流与转化事件配置的自动化能力。仓库中的 SKILL.md 及 references 目录下各语言指南，可作为持续查阅的一手资料。

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills