data-manager-api-event-ingestion

Data Manager API 事件接入

实施工作流

前提条件

• 身份验证和库安装：如果需要设置对 Data Manager API 的访问权限，或安装客户端和实用程序库，请参阅 data-manager-api-setup 技能。

第 1 步：确定用例并阅读文档

• 确定目标账号类型：[重要] 如果无法从用户上下文中确定，请考虑在生成代码前询问要将事件接入到哪个目标。这对应于 Destination 中 operating_account 的 account_type 字段，也决定了有效的事件标识符和要求。
• 确定用户意图：
  • 实现事件接入代码：根据下表中的实施指南列，遵循适用于目标和用例的相关实施指南。这对于确保满足字段要求并正确配置目标至关重要。
  • 检查请求状态或查看错误：请参阅下文的错误处理与问题排查部分。
  • 从其他 Google API 迁移：请参阅下文的第 3 步：获取迁移指南，提取相关字段映射指南的完整内容。

目标（operating_account.account_type）	用例	实施指南
Google Ads（GOOGLE_ADS）	离线转化、潜在客户增强型转化	发送事件
Google Ads（GOOGLE_ADS）	补充 Google 代码的多来源转化	发送事件
Google Ads（GOOGLE_ADS）	门店销售转化	发送事件
Google Analytics（GOOGLE_ANALYTICS_PROPERTY）	GA4 推荐事件和自定义事件	发送事件
Google Analytics（GOOGLE_ANALYTICS_PROPERTY）	带有交易 ID 的多来源事件	发送事件
Floodlight（FLOODLIGHT_CONFIG）	Floodlight 离线转化	发送事件
Floodlight（FLOODLIGHT_CONFIG）	补充 Google 代码或 Floodlight 代码的多来源转化	发送事件

如果请求不符合任何一行，请获取事件概览，以找到正确的指南，而不要猜测。

步骤 2：检索代码示例

重要

如果要编写或更新数据导入脚本，务必检索相关代码示例以供参考：

语言	示例
Python	ingest_events.py
Java	IngestEvents.java
PHP	ingest_events.php
Node	ingest_events.ts
.NET	IngestEvents.cs

步骤 3：检索迁移指南

重要

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

Google Ads

• 线下转化、潜在客户增强型转化（从 Google Ads API 迁移）： Google Ads 线下转化迁移字段映射
• 门店销售转化（从 Google Ads API 迁移）： Google Ads 门店销售迁移字段映射

Google Analytics

• 推荐 GA4 事件和自定义 GA4 事件（从 Google Analytics Measurement Protocol 迁移）： Google Analytics Measurement Protocol 迁移字段映射

Floodlight

• Floodlight 线下转化（从 Campaign Manager 360 API 迁移）： Campaign Manager 360 线下转化迁移字段映射

第 4 步：实现

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

• 初始化客户端：实例化 Data Manager 客户端 (IngestionServiceClient)。
• 定义目标：使用 product_destination_id 和相应的账号配置构建 Destination 对象：operating_account（接收数据的目标账号）、login_account（使用 管理员账号或数据合作伙伴账号进行身份验证时使用）以及 linked_account（如果你是 数据合作伙伴，通过合作伙伴链接访问管理账号中的账号时使用）。强烈建议：参阅 配置目标和标头 指南，了解有关配置目标的更多详情。
• 准备事件数据：使用实用工具库中的辅助函数正确格式化和规范化用户标识符。
• 构建有效负载：构建请求有效负载 (IngestEventsRequest)，其中包含目标、事件记录和同意权限。
• 支持验证：支持在 IngestEventsRequest 上发送布尔选项 validate_only，以便开发者验证架构，而不实际上传数据。
• 发送请求：执行 ingest_events，并记录返回的 request_id，以便后续诊断。
• 检查数据导入警告：如果任何非必填字段未通过验证，ingest_events 的响应中还会包含 field_warnings，这是一个 FieldWarning 对象列表，详细说明 相关问题。
• 检索请求状态：使用诊断功能检查数据导入请求的状态。由于请求处理是异步的， 成功的数据导入响应（HTTP 200 OK，并返回 request_id）仅表示已收到有效负载。 若要检查记录是否处理成功、部分成功或失败，请使用 request_id 查询 client.retrieve_request_status 端点。跳过此步骤是用户常见的错误。

格式化

• 获取格式化用户数据 指南，并将其作为格式化和规范化规则的唯一依据。

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

  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
  )
  

关键注意事项

• 将 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。
• 如果 validate_only 设置为 true，不要调用诊断端点 (retrieve_request_status)。

错误处理与故障排查

检查错误载荷和摄取警告

重要

请参阅了解 API 错误， 详细了解如何理解 API 返回的错误和警告的结构。

检索请求状态（诊断）

发送 IngestEventsRequest 后至少等待 30 分钟，再使用指数退避策略定期轮询状态。

1. 使用 RetrieveRequestStatusRequest(request_id=...) 调用 client.retrieve_request_status。
2. 遍历响应中的 request_status_per_destination，检查每个目标的 request_status。
3. 如果处理已完成，且 request_status 为 SUCCESS、PARTIAL_SUCCESS 或 FAILED，请检查诊断值：
   • 事件记录数：检查 events_ingestion_status.record_count（包括成功和失败的记录）。
   • 错误详情：如果状态为 FAILED 或 PARTIAL_SUCCESS，请检查 error_info.error_counts 下每个错误的 reason 和 record_count。
   • 警告详情：检查 warning_info.warning_counts 下每条警告的 reason 和 record_count（即使目标状态为 SUCCESS 也要检查）。

API 参考

• REST API 参考
• 诊断指南