用 Data Manager API 管理 Google…

当需要通过 Data Manager API 向 Google Ads 或 DV360 的 Customer Match 等受众上传、删除或清空成员时，按此流程实现并排查。

适用场景

解决思路

1. 先确认目标账号类型（Google Ads、DV360 等），若不清楚就停下来向用户澄清，不要默认 Google Ads；这对应 Destination 中 operating_account 的 account_type 字段。
2. 在写代码或回答问题前，先阅读对应目标与用例的实现指南，因为每个目标的 payload 结构、同意规则和必填字段都不同：Google Ads Customer Match 支持 composite_data.user_data、mobile_data、user_id_data；DV360 Customer Match 支持 composite_data.user_data、mobile_data。
3. 若需要新建受众，先参考 Create an Audience 文档创建受众，以获取后续上传/删除请求所需的 product_destination_id。
4. 写或更新上传脚本时，始终先取对应语言的官方示例作为参考：Python ingest_audience_members.py、Java IngestAudienceMembers.java、PHP ingest_audience_members.php、Node ingest_audience_members.ts、.NET IngestAudienceMembers.cs。
5. 若从其他 Google API 迁移代码，先提取对应字段映射指南：Google Ads API Customer Match 迁移字段映射，或 DV360 API Customer Match 迁移字段映射。
6. 初始化客户端：实例化 Data Manager 的 IngestionServiceClient。
7. 构建 Destination 对象：使用 product_destination_id，并配置 operating_account（接收数据的目标账号）、login_account（用经理账号或数据合作方账号认证时）、linked_account（作为数据合作方通过合作伙伴链接访问经理账号时）；建议参考 Configure destinations and headers 指南。
8. 格式化用户数据：发送 IngestAudienceMembersRequest 或 RemoveAudienceMembersRequest 时，参考 Formatting User Data 文档，用工具库正确规范化和哈希用户标识符。
9. 按操作构建请求 payload：新增用 IngestAudienceMembersRequest，删除用 RemoveAudienceMembersRequest，清空用 RemoveAllAudienceMembersRequest。
10. 支持 validate_only 布尔选项，让开发者在不实际应用变更的情况下校验 schema。
11. 发送请求并记录返回的 request_id 以便后续诊断：新增调用 ingest_audience_members，删除调用 remove_audience_members，清空调用 remove_all_audience_members。
12. 检查摄取警告：若任何非必填字段校验失败，ingest_audience_members 的响应会包含 field_warnings（FieldWarning 对象列表）说明问题。
13. 检索请求状态：请求处理是异步的，HTTP 200 返回 request_id 只表示 payload 已收到；要用 request_id 调用 client.retrieve_request_status 查询记录是成功、部分成功还是失败，跳过这一步是常见错误。
14. 若在 user_data 中发送哈希后的用户标识符（ingest_audience_members 或 remove_audience_members），必须在 IngestAudienceMembersRequest 上把 encoding 字段设为 HEX 或 BASE64。
15. 若上传到 Customer Match 受众，IngestAudienceMembersRequest 上必须设置 terms_of_service 字段，表示用户已接受相关政策。
16. 只有在 UserIdentifier 的 address 字段所需字段（postal_code、family_name、given_name、region_code）全部存在时才设置 address，不完整的 address 会导致 API 请求失败。
17. product_destination_id 必须是数字字符串，不是资源名称。
18. ConsentStatus 的枚举值是 CONSENT_GRANTED 和 CONSENT_DENIED，不要用 GRANTED 和 DENIED。
19. UserIdentifier 的字段名是 email_address 和 phone_number，不要用 Google Ads API 的 hashed_email 和 hashed_phone_number。
20. 当 validate_only 为 true 时，不要调用诊断端点 retrieve_request_status。
21. 诊断时用指数退避轮询状态，至少在发送请求 30 分钟后开始：调用 client.retrieve_request_status(RetrieveRequestStatusRequest(request_id=...))。
22. 遍历响应中的 request_status_per_destination，检查每个目标的 request_status。
23. 若处理完成且 request_status 为 SUCCESS、PARTIAL_SUCCESS 或 FAILED，检查诊断值：摄取看 audience_members_ingestion_status 下按数据类型的状态（如 composite_data_ingestion_status）；删除单个成员看 audience_members_removal_status 下按数据类型的状态（如 composite_data_removal_status）；清空成员没有嵌套状态字段或记录数可查。
24. 若适用（摄取或删除单个成员），检查数据类型状态对象内的 record_count（含成功和失败）。
25. 若适用（摄取或删除单个成员），检查状态对象内按数据类型的计数字段（如上传/删除 composite data 用 data_type_counts，上传/删除 mobile ID 用 mobile_id_count），其他计数字段参考 Diagnostics Guide。
26. 上传 user_data 和 composite_data 时，检查状态对象内的 upload_match_rate_range。
27. 若状态为 FAILED 或 PARTIAL_SUCCESS，检查 error_info.error_counts 下每个错误的 reason 和 record_count。
28. 检查 warning_info.warning_counts 下每个警告的 reason 和 record_count，即使目标状态是 SUCCESS 也要检查。

适用边界 · 注意事项

• 不要用于上传事件或转化（应使用 data-manager-api-event-ingestion 技能）。
• 未确认目标账号类型时不要假设是 Google Ads 并直接生成代码。
• validate_only 为 true 时不要调用 retrieve_request_status 诊断端点。