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 CLIgcloud启用 API、通过 Application Default CredentialsADC完成认证以及使用 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 CLIgcloud。如果gcloud不存在应先提示用户安装 Google Cloud CLI再执行以下命令。1. 启用 APIgcloud services enable analyticsadmin.googleapis.com --quiet为什么需要这一步启用该服务后Cloud 项目才会为管理 Google Analytics 配置分配相应的配额quota与权限后续的 API 请求才能被正常受理。2. 验证 API 是否已启用gcloud services list --enabled --filteranalyticsadmin.googleapis.com该命令会过滤出当前项目已启用服务中与analyticsadmin.googleapis.com匹配的记录若在输出中能看到该服务名说明启用成功。提示--quiet参数用于跳过交互式确认适合在 CI/CD 或自动化脚本中执行。三、认证配置 ADC 与正确的 OAuth 作用域认证是调用 Admin API 的关键前提。你需要生成应用默认凭据Application Default Credentials, ADC并为账号授予所需的作用域scopes。在终端中执行gcloud auth application-default login --scopeshttps://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作用域。因此实际使用时应根据操作类型选择作用域组合操作类型所需作用域只读查询列出账号、资源、数据流等analytics.readonly或cloud-platform写操作创建/修改/删除配置需追加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 目录下语言包名参考文档Pythongoogle-analytics-adminpython.mdJavacom.google.cloud:google-cloud-analytics-adminjava.mdPHPgoogle/analytics-adminphp.mdNode.jsgoogle-analytics/adminnodejs.mdGocloud.google.com/go/analytics/admin/apiv1betago.md.NETGoogle.Analytics.Admin.V1Betadotnet.mdRubygoogle-analytics-admin-v1alpharuby.md[!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.jsnpm 安装参考 nodejs.md前置要求为Node.js v14.x 以上推荐 v16、npm或yarn。npm install google-analytics/admin该包会一并拉取官方的 gRPC 与 REST 客户端绑定。JavaMaven / Gradle 依赖参考 java.md前置要求为JDK 8推荐 11、Maven 或 Gradle。Mavenpom.xml的dependencies内dependency groupIdcom.google.cloud/groupId artifactIdgoogle-cloud-analytics-admin/artifactId versionLATEST_LIBRARY_VERSION/version /dependencyGradlebuild.gradle的dependencies块implementation com.google.cloud:google-cloud-analytics-admin:LATEST_LIBRARY_VERSION使用 Maven 可自动解析传递依赖如 Netty、gRPC、Google Auth Library。务必把LATEST_LIBRARY_VERSION替换为 Maven Central 上的最新稳定版本。Gogo get 安装参考 go.md前置要求为Go 1.19、启用 Go modules。go get cloud.google.com/go/analytics/admin/apiv1beta该命令会把 Admin API 客户端包及其 gRPC 传输依赖写入go.mod。.NETNuGet 安装参考 dotnet.md前置要求为.NET Core 3.1 / .NET Standard 2.0 / .NET 6.0。.NET CLI 方式dotnet add package Google.Analytics.Admin.V1BetaVisual Studio 包管理器控制台方式Install-Package Google.Analytics.Admin.V1Beta该 NuGet 包包含强类型 protobuf 模型与 gRPC 服务客户端。PHPComposer 安装参考 php.md前置要求为PHP 8.0、Composer。composer require google/analytics-adminComposer 会安装客户端库、autoloader 以及认证相关依赖。RubyRubyGems / Bundler 安装参考 ruby.md前置要求为Ruby 3.0、RubyGems / Bundler。gem install google-analytics-admin-v1alpha或加入Gemfile后执行bundle installgem google-analytics-admin-v1alpha注意Ruby 的官方 gem 当前指向v1alpha版本使用前请确认与你的 API 版本需求一致。六、Python 快速开始列出账号与资源主文档提供了完整的 Python 快速开始示例其核心方法是list_account_summaries()——它会返回当前用户可访问的所有账号及其子资源的摘要信息是验证 Admin API 连通性与权限配置是否正确的Hello World。1. 安装客户端库pip install google-analytics-admin2. 列出账号与资源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(fAccount: {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/123456summary.property_summaries是该账号下的资源摘要列表每个资源可通过property_summaries迭代访问。其他语言的等价调用仓库各语言参考文档均提供了基于ListAccountSummaries的等价快速开始便于对照学习Javajava.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.jsnodejs.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);Gogo.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) } }.NETdotnet.mdCreateAsync()初始化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})); } } }PHPphp.md先引入 Composer autoloaderrequire_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()); }Rubyruby.md注意命名空间为V1alpharequire 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 QuickstartJava、PHP、Node.js、.NET、Python、REST 各语言示例以及 v1alpha / v1beta 完整 API 参考文档可作为进阶查阅资料。八、常见问题速查问题解决方式gcloud命令不存在先安装 Google Cloud CLI再执行本文第二节的命令调用时报权限错误确认已执行gcloud auth application-default login并根据操作类型补充analytics.readonly/analytics.edit作用域写操作创建资源、转化事件失败检查 ADC 是否包含analytics.edit作用域需要的功能在 v1beta 中找不到确认该能力是否属于 v1alpha 专属清单见第四节并选用支持 v1alpha 的客户端库如 Ruby 的google-analytics-admin-v1alphagemPython 安装失败确认 Python 3.8 与pip可用建议在虚拟环境中安装以避免依赖冲突结语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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考