google-analytics-admin-api-basics

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Getting Started with Google Analytics Admin API

Google Analytics Admin API 入门指南

The Google Analytics Admin API provides programmatic access to Google Analytics account and property configuration. It lets you automate account management, manage data streams, configure custom dimensions, and handle product integrations.

Google Analytics Admin API提供了对Google Analytics账户和属性配置的程序化访问权限。它允许你自动化账户管理、管理数据流、配置自定义维度以及处理产品集成。

Enabling the API via Cloud CLI

通过Cloud CLI启用API

Before making API calls, ensure the Google Analytics Admin API is enabled in your Google Cloud project.

gcloud

is not found, prompt the user to install the Google Cloud CLI before running these commands.

Enable the API: Use the Cloud CLI (
```
gcloud
```
) to enable
```
analyticsadmin.googleapis.com
```
.
bash
```
gcloud services enable analyticsadmin.googleapis.com --quiet
```
Why: Enabling the API ensures your Cloud project has the necessary quota and permissions allocated for managing Google Analytics configurations.

Verify API Enablement:

bash

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

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

如果未找到

gcloud

，请提示用户先安装Google Cloud CLI，再运行以下命令。

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

验证API启用状态：

bash

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

Authentication

身份验证

To authenticate your API requests, you must generate Application Default Credentials (ADC) and give your account the necessary scopes. Run the following command in your terminal:

bash

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

Why: This configures ADC in your local environment with the required Cloud Platform and Google Analytics read-only scopes, allowing the client library to automatically authenticate your requests.

[!NOTE] Configuration Changes: Methods changing the Google Analytics account/property configuration will need the
https://www.googleapis.com/auth/analytics.edit
scope.

要对API请求进行身份验证，你必须生成应用默认凭据（ADC）并为你的账户分配必要的权限范围。在终端中运行以下命令：

bash

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 Use Cases

Admin API 使用场景

You can use the Google Analytics Admin API to:

Run Data Access reports (see https://developers.google.com/analytics/devguides/config/admin/v1/access-api.md.txt for more info)
Create Account summaries
Manage accounts
Provision new accounts
Search account change history events
Manage and create properties
Manage property data retention settings
Manage conversion events
Manage custom dimensions and metrics
Manage data streams and configure measurement protocol secrets
Manage Firebase links
Manage Google Ads links
Manage key events

你可以使用Google Analytics Admin API来：

运行数据访问报告（更多信息请参见https://developers.google.com/analytics/devguides/config/admin/v1/access-api.md.txt）
创建账户摘要
管理账户
创建新账户
搜索账户变更历史事件
管理和创建属性
管理属性数据保留设置
管理转化事件
管理自定义维度和指标
管理数据流并配置Measurement Protocol密钥
管理Firebase链接
管理Google Ads链接
管理关键事件

v1alpha-Only Use Cases

仅v1alpha版本支持的使用场景

The following capabilities are currently available only in the

v1alpha

version of the Admin API:

Manage account and property access bindings
Create and manage rollup properties
Create and manage subproperties
Acknowledge user data collection
Change property attribution, data retention, Google signals, reporting identity, and User Provided Data settings
Manage AdSense links
Manage BigQuery links
Manage audiences
Manage channel groups
Manage calculated metrics
Manage DisplayVideo360Advertiser links
Manage expanded data sets
Manage reporting data annotations
Manage SearchAds360 links
Manage event create rules for a data stream
Manage SKAdNetwork conversion value schema of an iOS stream
Submit a request for user deletion for a Google Analytics property.

以下功能目前仅在Admin API的

v1alpha

版本中可用：

管理账户和属性访问绑定
创建和管理汇总属性
创建和管理子属性
确认用户数据收集
修改属性归因、数据保留、Google信号、报告身份和用户提供数据设置
管理AdSense链接
管理BigQuery链接
管理受众群体
管理渠道组
管理计算指标
管理DisplayVideo360Advertiser链接
管理扩展数据集
管理报告数据注释
管理SearchAds360链接
管理数据流的事件创建规则
管理iOS流的SKAdNetwork转化值架构
提交Google Analytics属性的用户删除请求

Calling the Admin API

调用Admin API

To interact with the Admin API, use the official Google Analytics Admin client library. Note that

v1beta

is the most stable version of the Admin API. For the latest features, consider using

v1alpha

[!IMPORTANT] Mandatory Agent Directive: When the user selects or requires a specific programming language, read the corresponding client library setup reference guide in
references/
listed below.

要与Admin API交互，请使用官方Google Analytics Admin客户端库。请注意，

v1beta

是Admin API最稳定的版本。如需最新功能，可以考虑使用

v1alpha

版本。

[!IMPORTANT] Agent强制指令：当用户选择或需要特定编程语言时，请阅读下方
references/
中对应的客户端库设置参考指南。

Supported Client Libraries

支持的客户端库

Python

If you need to install or set up the Google Analytics Admin API client library for Python, read the setup guide:

Python Installation Reference (Package:
google-analytics-admin
)

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

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

Java

If you need to install or set up the Google Analytics Admin API client library for Java, read the setup guide:

Java Installation Reference (Artifact:
com.google.cloud:google-cloud-analytics-admin
)

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

Java安装参考（构件：

com.google.cloud:google-cloud-analytics-admin

）

PHP

If you need to install or set up the Google Analytics Admin API client library for PHP, read the setup guide:

PHP Installation Reference (Package:
google/analytics-admin
)

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

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

Node.js

If you need to install or set up the Google Analytics Admin API client library for Node.js, read the setup guide:

Node.js Installation Reference (Package:
@google-analytics/admin
)

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

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

Go

If you need to install or set up the Google Analytics Admin API client library for Go, read the setup guide:

Go Installation Reference (Package:
cloud.google.com/go/analytics/admin/apiv1beta
)

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

Go安装参考（包：

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

）

.NET

If you need to install or set up the Google Analytics Admin API client library for .NET / C#, read the setup guide:

.NET Installation Reference (Package:
Google.Analytics.Admin.V1Beta
)

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

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

Ruby

If you need to install or set up the Google Analytics Admin API client library for Ruby, read the setup guide:

Ruby Installation Reference (Gem:
google-analytics-admin-v1alpha
)

[!NOTE] Additional Resources: For further examples of calling the Admin API with Java, PHP, Node.js, .NET, Python, and REST, as well as hints on authentication with a service account, refer to the official Admin API Quickstart. For complete API reference documentation for both
v1alpha
and
v1beta
, see the Admin API Reference.

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

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

[!NOTE] 额外资源：如需使用Java、PHP、Node.js、.NET、Python和REST调用Admin API的更多示例，以及使用服务账户进行身份验证的提示，请参考官方Admin API快速入门。如需
v1alpha
和
v1beta
版本的完整API参考文档，请查看Admin API参考。

Python Quick Start

Python快速入门

Install the Client Library:
bash
```
pip install google-analytics-admin
```
If
```
pip
```
is not available, prompt the user to install
```
pip
```
before installing the client library.

List Accounts and Properties: Below is a complete example demonstrating how to call the Admin API to list all available accounts and their child properties for the current user using

list_account_summaries()

python

from google.analytics.admin import AnalyticsAdminServiceClient

def sample_list_account_summaries():
    # Initialize the client.
    # Assumes Application Default Credentials (ADC) are configured in your environment.
    client = AnalyticsAdminServiceClient()

    # list_account_summaries returns a summary of all accounts accessible to the
    # user and their child properties.
    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()

安装客户端库：
bash
```
pip install google-analytics-admin
```
如果未找到
```
pip
```
，请提示用户先安装
```
pip
```
，再安装客户端库。

列出账户和属性：以下是一个完整示例，展示如何调用Admin API，使用

list_account_summaries()

列出当前用户可访问的所有账户及其子属性。

python

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()