data-manager-api-event-ingestion

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Data Manager API Event 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, Floodlight, Google Analytics) 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
```
, and also determines valid event identifiers and requirements.
Read Documentation: [CRITICAL] You MUST follow the the Send events guide to understand implementation steps, user/event identifier requirements, and how to configure the destination object.

确定目标账户类型：[关键] 如果用户未明确说明，请先停止操作并向用户确认数据要发送到哪里（例如Google Ads、Floodlight、Google Analytics），再生成任何代码。请勿默认假设是Google Ads。这对应
```
Destination
```
中
```
operating_account
```
的
```
account_type
```
字段，同时也决定了有效的事件标识符和要求。
阅读文档：[关键] 必须遵循发送事件指南，了解实现步骤、用户/事件标识符要求以及如何配置目标对象。

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 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_events.py`
Java	`IngestEvents.java`
PHP	`ingest_events.php`
Node	`ingest_events.ts`
.NET	`IngestEvents.cs`

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

语言	示例
Python	`ingest_events.py`
Java	`IngestEvents.java`
PHP	`ingest_events.php`
Node	`ingest_events.ts`
.NET	`IngestEvents.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.

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

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.
Prepare Event Data: Use the utility library helpers to format and normalize user identifiers correctly.
Construct Payload: Build the request payload (
```
IngestEventsRequest
```
) containing the destinations, event records, and consent permissions.
Send Request: Execute
```
ingest_events
```
and record the returned request ID for logging/troubleshooting.

使用以下检查点实现导入逻辑：

初始化客户端：实例化Data Manager客户端（
```
IngestionServiceClient
```
）。
定义目标对象：使用
```
product_destination_id
```
和适当的账户配置构建
```
Destination
```
对象：
```
operating_account
```
（接收数据的目标账户）、
```
login_account
```
（如果使用管理员账户或数据合作伙伴账户进行认证），以及
```
linked_account
```
（如果是数据合作伙伴，通过与管理员账户的合作伙伴链接访问该账户）。强烈建议：参阅配置目标与请求头指南，了解更多关于配置目标对象的细节。
准备事件数据：使用工具库助手正确格式化和标准化用户标识符。
构建请求负载：构建包含目标对象、事件记录和同意权限的请求负载（
```
IngestEventsRequest
```
）。
发送请求：执行
```
ingest_events
```
并记录返回的请求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

关键注意事项

Format
```
product_destination_id
```
as a numeric string. It is NOT a resource name path.
Format
```
event_timestamp
```
strictly in RFC 3339 format. Use the SDK's typed timestamp object instead of a raw string where available.
Nest click identifiers (
```
gclid
```
,
```
gbraid
```
,
```
wbraid
```
) inside the
```
ad_identifiers
```
block, not directly on the base event payload.

The enum values for

ConsentStatus

are

CONSENT_GRANTED

and

CONSENT_DENIED

. Do not use the values

GRANTED

and

DENIED

Note that
```
consent
```
can be set globally on the
```
IngestEventsRequest
```
or on individual
```
Event
```
s.

Verify that

UserIdentifier

uses

email_address

and

phone_number

. Do NOT use the Google Ads API fields

hashed_email

and

hashed_phone_number

Ensure the currency field on the event is named
```
currency
```
, not
```
currency_code
```
.

将
```
product_destination_id
```
格式化为数字字符串。它不是资源名称路径。
严格按照RFC 3339格式格式化
```
event_timestamp
```
。如果SDK提供类型化的时间戳对象，请使用该对象而非原始字符串。
将点击标识符（
```
gclid
```
、
```
gbraid
```
、
```
wbraid
```
）嵌套在
```
ad_identifiers
```
块内，而非直接放在基础事件负载中。

ConsentStatus

的枚举值为

CONSENT_GRANTED

和

CONSENT_DENIED

。请勿使用

GRANTED

和

DENIED

。

注意
```
consent
```
可以在
```
IngestEventsRequest
```
全局设置，也可以在单个
```
Event
```
上设置。

验证

UserIdentifier

使用

email_address

和

phone_number

字段。请勿使用Google Ads API的

hashed_email

和

hashed_phone_number

字段。

确保事件中的货币字段名为
```
currency
```
，而非
```
currency_code
```
。

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.

REST API Reference: https://developers.google.com/data-manager/api/reference/rest/v1/events/ingest

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

REST API参考： https://developers.google.com/data-manager/api/reference/rest/v1/events/ingest

data-manager-api-event-ingestion

Original

Translation

Data Manager API Event Ingestion

Data Manager API 事件导入

Core Directives

核心指令

Sequential Implementation Workflow

分步实现流程

Step 1: Identify Use Case & Read Documentation

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

Step 2: Setup Auth

步骤2：设置认证

Step 3: Install Client Library and Utilities

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

Install Utility Library

安装工具库

Python

Python

Java

Java

Node

Node

PHP

PHP

.NET

.NET

Step 4: Retrieve Code Sample

步骤4：获取代码示例

Step 5: Retrieve migration guides

步骤5：获取迁移指南

Google Ads

Google Ads

Google Analytics

Google Analytics

Campaign Manager 360 (CM360)

Campaign Manager 360 (CM360)

Step 6: Implementation

步骤6：实现

Formatting

格式化

Critical Gotchas

关键注意事项

Error Handling & Troubleshooting

错误处理与故障排查

Inspecting Error Payloads

检查错误负载

API Reference

API参考