data-manager-api-audience-ingestion

Data Manager API 受众数据导入

实施工作流

前提条件

• 身份验证与库安装：如果需要设置对 Data Manager API 的访问权限，或安装客户端和实用工具库，请参阅 data-manager-api-setup 技能。
• 创建受众（如有需要）：如果用户没有现有受众或需要创建新受众，请参阅创建受众。此步骤会提供导入或移除请求所需的 product_destination_id。

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

• 确定目标账号类型：[CRITICAL] 如果不清楚数据将发送到哪里（例如 Google Ads、Display & Video 360 等），请停止并先向用户确认，再生成任何代码。不要默认使用 Google Ads。此类型对应于 Destination 中 operating_account 的 account_type 字段。
• 阅读实施指南：阅读与你的目标平台和用例相关的指南。请在回答问题或编写代码之前完成此操作，因为每个目标平台都有独特的负载结构、同意规则和必填字段。

目标平台	受众类型	接受的数据类型	上传指南	全部移除/全部替换指南
Google Ads	Customer Match	composite_data.user_data（联系信息）、mobile_data（设备 ID）、user_id_data（用户 ID）	上传数据	全部移除/全部替换
Display & Video 360（DV360）	Customer Match	composite_data.user_data（联系信息）、mobile_data（设备 ID）	上传数据	全部移除/全部替换

步骤 2：获取代码示例

重要

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

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

步骤 3：获取迁移指南

重要

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

Google Ads

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

Display & Video 360

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

第 4 步：实现

使用以下检查点实现数据摄取逻辑：

• 初始化客户端：实例化 Data Manager 客户端 （IngestionServiceClient）。
• 定义目标位置：使用 product_destination_id 和相应的账号配置构建 Destination 对象： operating_account（接收数据的目标账号）、login_account（使用管理账号或数据合作伙伴账号进行身份验证时填写）以及 linked_account（数据合作伙伴通过合作伙伴链接访问管理账号时填写）。强烈建议：参阅 配置目标位置和标头 指南，了解配置目标位置的更多详情。
• 格式化用户数据：如果要发送 IngestAudienceMembersRequest 或 RemoveAudienceMembersRequest，请参阅 格式化用户 数据，使用实用程序库正确规范化并哈希用户标识符。
• 构建载荷：根据操作构建相应的请求载荷：
  • 添加：IngestAudienceMembersRequest
  • 移除：RemoveAudienceMembersRequest
  • 全部移除：RemoveAllAudienceMembersRequest
• 支持验证：支持在载荷中发送 validate_only 布尔选项，以便开发者验证架构，而不实际应用更改。
• 发送请求：执行相应的方法，并记录返回的 request_id，以便后续诊断：
  • 添加：ingest_audience_members
  • 移除：remove_audience_members
  • 全部移除：remove_all_audience_members
• 检查数据摄取警告：如果任何非必填字段未通过验证，ingest_audience_members 的响应还会包含 field_warnings，这是一个 FieldWarning 对象列表，用于详细说明问题。
• 检索请求状态：使用诊断功能检查数据摄取请求的状态。由于请求处理是异步的，成功响应（HTTP 200 OK 并返回 request_id）仅表示已收到载荷。若要检查记录是否处理成功、部分成功或处理失败，请使用 request_id 查询 client.retrieve_request_status。跳过此步骤是用户常犯的错误。

关键注意事项

• 如果在 user_data 中为 ingest_audience_members 或 remove_audience_members 发送经过哈希处理的用户标识符，必须将 IngestAudienceMembersRequest 中的 encoding 字段设为 HEX 或 BASE64。
• 如果要上传到 Customer Match 受众群体，IngestAudienceMembersRequest 中必须包含 terms_of_service 字段，以表明用户已接受相关政策。
• 仅当所有必填字段（postal_code、family_name、given_name、region_code）都存在时，才在 UserIdentifier 上设置 address 字段；不完整的 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。
• 如果 validate_only 设为 true，请勿调用诊断端点（retrieve_request_status）。

错误处理与故障排查

检查错误载荷和数据摄取警告

重要

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

检索请求状态（诊断）

定期使用指数退避轮询状态，首次轮询至少应在发送请求 30 分钟后进行。

1. 使用 RetrieveRequestStatusRequest(request_id=...) 调用 client.retrieve_request_status。
2. 遍历响应中的 request_status_per_destination，检查每个目标的 request_status。
3. 如果处理已完成，且 request_status 为 SUCCESS、PARTIAL_SUCCESS 或 FAILED，请检查诊断值：
   • 受众状态：检查与请求对应的状态：
     • 导入：检查 audience_members_ingestion_status 中嵌套的数据类型专属状态（例如 composite_data_ingestion_status）。
     • 移除单个成员：检查 audience_members_removal_status 中嵌套的数据类型专属状态（例如 composite_data_removal_status）。
     • 移除所有成员：此类请求没有可供检查的嵌套状态字段或记录数。
     • 记录数：如适用（导入或移除单个成员），请检查 record_count（嵌套在数据类型专属状态对象中），其中包含成功和失败的记录。
     • 标识符计数：如适用（导入或移除单个成员），请检查状态对象中嵌套的数据类型专属计数字段（例如，上传或移除复合数据时使用 data_type_counts，上传或移除移动 ID 时使用 mobile_id_count）。其他计数字段请参阅诊断指南。
     • 匹配率范围：对于 user_data 和 composite_data 的上传，请检查状态对象中嵌套的 upload_match_rate_range。
   • 错误详情：如果状态为 FAILED 或 PARTIAL_SUCCESS，请检查 error_info.error_counts 下每个错误的 reason 和 record_count。
   • 警告详情：请检查 warning_info.warning_counts 下每个警告的 reason 和 record_count（即使目标状态为 SUCCESS）。

API 参考

• 发送受众成员指南
• REST API 参考：导入
• REST API 参考：移除
• REST API 参考：移除所有成员