data-manager-api-audience-ingestion

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Data Manager API Audience Ingestion

Data Manager API 受众成员上传

Core Directives

核心指令

[IMPORTANT] When reading API documentation from developers.google.com, read the Markdown equivalent of the page by appending
```
.md.txt
```
to the URL.

[重要提示] 阅读developers.google.com上的API文档时，请在URL后追加
```
.md.txt
```
以查看对应的Markdown版本页面。

Sequential Implementation Workflow

分步实现流程

For simple informational, configuration, or setup questions, skip any irrelevant steps and answer using only the relevant guidelines or documentation provided below.

对于简单的信息查询、配置或设置类问题，请跳过无关步骤，仅使用以下相关指南或文档进行解答。

Step 1: Identify Use Case & Read Documentation

步骤1：确定使用场景并阅读文档

Determine Destination Account Type: [CRITICAL] If it's not explicitly stated, STOP and CLARIFY with the user where the data is being sent (e.g., Google Ads, Display & Video 360, etc.) BEFORE generating any code. Do NOT assume Google Ads by default. This maps to the
```
account_type
```
field of the
```
operating_account
```
in the
```
Destination
```
.
Read Documentation: [CRITICAL] You MUST follow the relevant audience upload overview for implementation steps:
- Google Ads Customer Match: Upload members to an audience
- DV360 Customer Match: Upload members to an audience

确定目标账户类型：[关键] 如果用户未明确说明，请先停止操作并与用户确认数据将发送到何处（例如Google Ads、Display & Video 360等），然后再生成任何代码。请勿默认假设是Google Ads。这对应
```
Destination
```
中
```
operating_account
```
的
```
account_type
```
字段。
阅读文档：[关键] 必须遵循相关的受众上传概述来执行实现步骤：
- Google Ads Customer Match：向受众上传成员
- DV360 Customer Match：向受众上传成员

Step 2: Setup Auth

步骤2：设置认证

Enable API (Prerequisite): Check that the user has enabled the Data Manager API in their Google Cloud project.
Generate ADC: Authenticate the local workspace using Application Default Credentials (ADC) via
```
gcloud auth application-default login
```
.
- Required Scopes: Include scopes
```
https://www.googleapis.com/auth/datamanager
```
  and
```
https://www.googleapis.com/auth/cloud-platform
```
  .
- Multi-API Scopes: If using the same credentials for other APIs, append their scopes (e.g.,
```
https://www.googleapis.com/auth/adwords
```
  ).
- Service Accounts: Ensure the Service Account has the
```
Service Usage Consumer
```
  IAM role, and the user executing
```
gcloud
```
  has the Token Creator role (
```
roles/iam.serviceAccountTokenCreator
```
  ) on that Service Account for impersonation.
Reference: Refer to Set up API access for a walkthrough of the
```
gcloud
```
CLI auth setup.

启用API（前提条件）：检查用户是否已在其Google Cloud项目中启用Data Manager API。
生成ADC：通过
```
gcloud auth application-default login
```
命令使用应用默认凭据（ADC）对本地工作区进行认证。
- 所需权限范围：需包含
```
https://www.googleapis.com/auth/datamanager
```
  和
```
https://www.googleapis.com/auth/cloud-platform
```
  权限范围。
- 多API权限范围：如果使用相同凭据访问其他API，请追加对应权限范围（例如
```
https://www.googleapis.com/auth/adwords
```
  ）。
- 服务账号：确保服务账号拥有
```
Service Usage Consumer
```
  IAM角色，且执行
```
gcloud
```
  命令的用户在该服务账号上拥有
```
Token Creator
```
  角色（
```
roles/iam.serviceAccountTokenCreator
```
  ）以进行身份模拟。
参考文档：请参阅设置API访问权限以获取
```
gcloud
```
CLI认证设置的分步指南。

Step 3: Install Client Library and Utilities

步骤3：安装客户端库及工具库

Refer to Install a client library for detailed installation instructions.

Language	Installation Instructions
Python	`pip install google-ads-datamanager`
Java	Follow the quickstart instructions to install the Maven/Gradle dependency.
Node	`npm install @google-ads/datamanager`
PHP	Install the `googleads/data-manager` component using Composer.
.NET	Install the `Google.Ads.DataManager.V1` NuGet package.

[IMPORTANT] The utility library is NOT available on public package managers (such as PyPI or Maven). Follow the below instructions to install:

Clone the repository from GitHub using the commands from the table below.
Always use the latest available version of the library. Determine the actual version identifier (
```
VERSION
```
) from the cloned repository metadata.
- Python: Find the version in
```
pyproject.toml
```
- Java: Find the version in
```
util/package.json
```
  (as the
```
version
```
  field).
- Node: Find the version in
```
composer.json
```
  (as the
```
version
```
  field).
Follow the language-specific instructions in the next section to build and install the utility dependency, replacing
```
VERSION
```
with the version identifier you found.

Language	Git Clone Command
Python	`git clone https://github.com/googleads/data-manager-python.git`
Java	`git clone https://github.com/googleads/data-manager-java.git`
Node	`git clone https://github.com/googleads/data-manager-node.git`
PHP	`git clone https://github.com/googleads/data-manager-php.git`
.NET	`git clone https://github.com/googleads/data-manager-dotnet.git`

请参阅安装客户端库获取详细安装说明。

语言	安装说明
Python	`pip install google-ads-datamanager`
Java	按照快速入门说明安装Maven/Gradle依赖。
Node	`npm install @google-ads/datamanager`
PHP	使用Composer安装 `googleads/data-manager` 组件。
.NET	安装 `Google.Ads.DataManager.V1` NuGet包。

[重要提示] 工具库无法从公共包管理器（如PyPI或Maven）获取，请按照以下说明安装：

使用下表中的命令从GitHub克隆代码仓库。
始终使用库的最新版本。从克隆仓库的元数据中确定实际版本标识符（
```
VERSION
```
）：
- Python：在
```
pyproject.toml
```
  中查找版本号
- Java：在
```
util/package.json
```
  的
```
version
```
  字段中查找版本号
- Node：在
```
composer.json
```
  的
```
version
```
  字段中查找版本号
按照下一节中的语言特定说明构建并安装工具库依赖，将
```
VERSION
```
替换为你找到的版本标识符。

语言	Git克隆命令
Python	`git clone https://github.com/googleads/data-manager-python.git`
Java	`git clone https://github.com/googleads/data-manager-java.git`
Node	`git clone https://github.com/googleads/data-manager-node.git`
PHP	`git clone https://github.com/googleads/data-manager-php.git`
.NET	`git clone https://github.com/googleads/data-manager-dotnet.git`

Install Utility Library

安装工具库

Python

Navigate to the
```
data-manager-python
```
directory and install the utility library:
shell
```
pip install .
```
Declare a dependency in your project's
```
requirements.txt
```
file (replacing
```
VERSION
```
with the identified version):
```
undefined
```

google-ads-datamanager-util=VERSION ```

进入
```
data-manager-python
```
目录并安装工具库：
shell
```
pip install .
```
在项目的
```
requirements.txt
```
文件中声明依赖（将
```
VERSION
```
替换为已确定的版本号）：
```
undefined
```

google-ads-datamanager-util=VERSION ```

Java

Navigate to the
```
data-manager-java
```
directory.
Build and publish the utility library to your local Maven repository:

shell

./gradlew data-manager-util:install

Declare a dependency on the utility library in your project (replacing

VERSION

with the identified latest version):

Gradle:

none

implementation 'com.google.api-ads:data-manager-util:VERSION'

Maven:

xml

<dependency>
   <groupId>com.google.api-ads</groupId>
   <artifactId>data-manager-util</artifactId>
   <version>VERSION</version>
</dependency>

进入
```
data-manager-java
```
目录。
构建工具库并发布到本地Maven仓库：

shell

./gradlew data-manager-util:install

在项目中声明工具库依赖（将

VERSION

替换为已确定的最新版本号）：

Gradle：

none

implementation 'com.google.api-ads:data-manager-util:VERSION'

Maven：

xml

<dependency>
   <groupId>com.google.api-ads</groupId>
   <artifactId>data-manager-util</artifactId>
   <version>VERSION</version>
</dependency>

Node

Navigate to the
```
data-manager-node
```
directory and install dependencies:

shell

npm install

Navigate to the
```
util
```
directory:

shell

cd util

Pack the utility library into a
```
.tgz
```
archive:

shell

npm pack

Declare a dependency in your Node.js project's
```
package.json
```
pointing to the path of the generated
```
.tgz
```
archive (replacing
```
VERSION
```
with the identified version):

json

{
   "dependencies": {
      "@google-ads/data-manager-util": "file:/path/to/google-ads-datamanager-util-VERSION.tgz"
   }
}

进入
```
data-manager-node
```
目录并安装依赖：

shell

npm install

shell

cd util

将工具库打包为
```
.tgz
```
归档文件：

shell

npm pack

在Node.js项目的
```
package.json
```
中声明依赖，指向生成的
```
.tgz
```
归档文件路径（将
```
VERSION
```
替换为已确定的版本号）：

json

{
   "dependencies": {
      "@google-ads/data-manager-util": "file:/path/to/google-ads-datamanager-util-VERSION.tgz"
   }
}

PHP

Navigate to the
```
data-manager-php
```
directory.
Resolve dependencies for the library:

shell

composer update --prefer-dist

Update your project's
```
composer.json
```
to declare a dependency on the utility library using a path repository:

json

 {
     "repositories": [
         {
             "type": "path",
             "url": "/path/to/cloned/data-manager-php"
         }
     ],
     "require": {
         "googleads/data-manager-util": "@dev"
     }
 }

进入
```
data-manager-php
```
目录。
解析库的依赖：

shell

composer update --prefer-dist

更新项目的
```
composer.json
```
，使用路径仓库声明工具库依赖：

json

 {
     "repositories": [
         {
             "type": "path",
             "url": "/path/to/cloned/data-manager-php"
         }
     ],
     "require": {
         "googleads/data-manager-util": "@dev"
     }
 }

.NET

In your .NET project, declare a

ProjectReference

dependency pointing to the cloned library's

.csproj

path:

xml

<ProjectReference Include="\path\to\cloned\Google.Ads.DataManager.Util\src\Google.Ads.DataManager.Util.csproj" />

在你的.NET项目中，声明

ProjectReference

依赖，指向克隆库的

.csproj

路径：

xml

<ProjectReference Include="\path\to\cloned\Google.Ads.DataManager.Util\src\Google.Ads.DataManager.Util.csproj" />

Step 4: Retrieve Code Sample

步骤4：获取代码示例

[IMPORTANT] If writing or updating an ingestion script, ALWAYS retrieve the relevant code sample to use as a reference:

Language	Sample
Python	`ingest_audience_members.py`
Java	`IngestAudienceMembers.java`
PHP	`ingest_audience_members.php`
Node	`ingest_audience_members.ts`
.NET	`IngestAudienceMembers.cs`

[重要提示] 如果编写或更新上传脚本，请务必获取相关代码示例作为参考：

语言	示例
Python	`ingest_audience_members.py`
Java	`IngestAudienceMembers.java`
PHP	`ingest_audience_members.php`
Node	`ingest_audience_members.ts`
.NET	`IngestAudienceMembers.cs`

Step 5: Retrieve migration guides

步骤5：获取迁移指南

[CRITICAL] If refactoring code to upgrade from another Google API, ALWAYS extract the full contents of the relevant field mapping guide.

[关键] 如果重构代码以从其他谷歌API升级，请务必提取相关字段映射指南的完整内容。

Google Ads

Google Ads API Customer Match: Google Ads API to Customer Match Migration Field Mappings

Google Ads API Customer Match： Google Ads API 到 Customer Match 迁移字段映射

Display & Video 360

Display & Video 360 API Customer Match: Display & Video 360 API to Customer Match Migration Field Mappings

Display & Video 360 API Customer Match： Display & Video 360 API 到 Customer Match 迁移字段映射

Step 6: Implementation

步骤6：实现

Implement the ingestion logic using the following checkpoints:

Initialize Client: Instantiate the Data Manager client (
```
IngestionServiceClient
```
).
Define Destinations: Build the
```
Destination
```
object using the
```
product_destination_id
```
and the appropriate account configurations:
```
operating_account
```
(target account receiving data),
```
login_account
```
(if authenticating using a manager account or a data partner account), and
```
linked_account
```
(if you're a data partner accessing the account via a partner link to a manager account). STRONGLY RECOMMENDED: Refer to the Configure destinations and headers guide for more details on configuring destinations.
Format User Data: Use the utility library helpers to normalize and hash user identifiers correctly.
Construct Payload: Build the request payload (
```
IngestAudienceMembersRequest
```
) containing the destinations, formatted members, and consent permissions.
Send Request: Execute
```
ingest_audience_members
```
and record the returned request ID for logging/troubleshooting.

使用以下检查点实现上传逻辑：

初始化客户端：实例化Data Manager客户端（
```
IngestionServiceClient
```
）。
定义目标：使用
```
product_destination_id
```
和适当的账户配置构建
```
Destination
```
对象：
```
operating_account
```
（接收数据的目标账户）、
```
login_account
```
（如果使用管理账户或数据合作伙伴账户进行认证），以及
```
linked_account
```
（如果是数据合作伙伴通过合作伙伴链接访问管理账户下的账户）。强烈建议：参阅配置目标和请求头指南获取更多关于配置目标的详细信息。
格式化用户数据：使用工具库的辅助函数正确标准化并哈希用户标识符。
构建请求负载：构建包含目标、格式化后的成员数据和同意权限的请求负载（
```
IngestAudienceMembersRequest
```
）。
发送请求：执行
```
ingest_audience_members
```
并记录返回的请求ID用于日志记录和故障排查。

Formatting

格式化

Fetch the Format user data guide and use that as the source of truth for formatting and normalization rules.

Use the utility library to format, hash, and encrypt user data (emails, phone numbers, addresses).

Python Example:

python

from google.ads.datamanager_util import Formatter
from google.ads.datamanager_util.format import Encoding

formatter: Formatter = Formatter()

processed_email: str = formatter.process_email_address(
    email, Encoding.HEX
)

获取格式化用户数据指南，并以此作为格式化和标准化规则的权威来源。

使用工具库格式化、哈希和加密用户数据（电子邮件、电话号码、地址）。

Python示例：

python

from google.ads.datamanager_util import Formatter
from google.ads.datamanager_util.format import Encoding

formatter: Formatter = Formatter()

processed_email: str = formatter.process_email_address(
    email, Encoding.HEX
)

Critical Gotchas

关键注意事项

Do NOT set the
```
address
```
field on
```
UserIdentifier
```
unless all required fields are present (
```
postal_code
```
,
```
family_name
```
,
```
given_name
```
,
```
region_code
```
); incomplete address fields will cause the API request to fail.
```
product_destination_id
```
must be a numeric string. It is NOT a resource name.

The enum values for

ConsentStatus

are

CONSENT_GRANTED

and

CONSENT_DENIED

. Do not use the values

GRANTED

and

DENIED

Field names on

UserIdentifier

are

email_address

and

phone_number

. Do not use the Google Ads API field names

hashed_email

and

hashed_phone_number

除非所有必填字段（
```
postal_code
```
、
```
family_name
```
、
```
given_name
```
、
```
region_code
```
）都存在，否则请勿设置
```
UserIdentifier
```
上的
```
address
```
字段；不完整的地址字段会导致API请求失败。
```
product_destination_id
```
必须是数字字符串，而非资源名称。

ConsentStatus

的枚举值为

CONSENT_GRANTED

和

CONSENT_DENIED

，请勿使用

GRANTED

和

DENIED

。

```
UserIdentifier
```
上的字段名称为
```
email_address
```
和
```
phone_number
```
，请勿使用Google Ads API的字段名称
```
hashed_email
```
和
```
hashed_phone_number
```
。

Error Handling & Troubleshooting

错误处理与故障排查

Inspecting Error Payloads

检查错误负载

[IMPORTANT] Refer to Understand API Errors for a detailed guide on how to understand the structure of errors returned by the API.

[重要提示] 请参阅理解API错误指南，详细了解API返回错误的结构。

API Reference

API参考

When implementing or debugging API integrations, use the API reference to lookup field names, types, and acceptable values. DO NOT guess values.

Send audience members guide: https://developers.google.com/data-manager/api/devguides/audiences/send-audience-members
REST API Reference: https://developers.google.com/data-manager/api/reference/rest/v1/audienceMembers/ingest

在实现或调试API集成时，请使用API参考查找字段名称、类型和可接受的值。请勿猜测值。

发送受众成员指南： https://developers.google.com/data-manager/api/devguides/audiences/send-audience-members
REST API参考： https://developers.google.com/data-manager/api/reference/rest/v1/audienceMembers/ingest