如何用 Data Manager API 上传 Customer Match 受众成员【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills把邮箱、手机号、移动设备 ID 或用户 ID 批量写入 Google Ads 或 Display Video 360DV360的 Customer Match 受众是 Data Manager API 受众摄入audience ingestion接口的典型任务。以下内容基于 Agent Skills 仓库中的>gcloud auth application-default login所需 scopes 至少包含https://www.googleapis.com/auth/datamanager和https://www.googleapis.com/auth/cloud-platform如果同一凭证还要访问其他 API追加对应 scope例如https://www.googleapis.com/auth/adwords。如果使用服务账号服务账号需要有Service Usage ConsumerIAM 角色且执行gcloud的用户要在该服务账号上拥有 Token Creator 角色roles/iam.serviceAccountTokenCreator。以 Python 为主路径安装客户端库pip install google-ads-datamanager配套的 utility library 用于规范化、哈希和加密用户标识符它不在 PyPI 等公开包管理器上发布需要克隆源仓库安装见 Python 安装参考git clone https://github.com/googleads/data-manager-python.git cd>google-ads-datamanager-util{version}可选分支Node.js 项目执行npm install google-ads/datamanager安装客户端utility library 同样需要克隆data-manager-node仓库在其util目录执行npm pack生成.tgz归档后在package.json中以file:{path_to_archive}形式引用详见 Node 安装参考。明确投放目标并配置 Destination在写任何摄入代码之前必须先确定数据要发往哪个产品Google Ads、DV360 等。skill 文档将此标为 CRITICAL不要默认假设 Google Ads。投放目标对应Destination对象中operating_account的account_type字段不同目的地可接受的数据类型不同目的地受众类型接受的数据类型Google AdsCustomer Matchcomposite_data.user_data联系方式、mobile_data设备 ID、user_id_data用户 IDDisplay Video 360Customer Matchcomposite_data.user_data联系方式、mobile_data设备 ID构建Destination时需要的字段product_destination_id目标受众标识必须是纯数字字符串不是资源名operating_account接收数据的目标账号配置login_account使用 manager 账号或 data partner 账号认证时设置linked_accountdata partner 通过 partner link 访问 manager 账号时设置。没有现成受众时先创建受众如果还没有 Customer Match 受众先创建它——创建步骤会提供后续摄入请求所需的product_destination_id。具体的创建请求结构以官方 Create a Customer Match audience 指南为准Google Ads 与 DV360 各一份链接列于 skill 文档本地文档重点提示了客户端选择与 header 的两个易错点正确的客户端是UserListServiceClient不是UserListsClientfrom google.ads import datamanager_v1 user_list_client datamanager_v1.UserListServiceClient()不要传login-customer-id或developer-token这类 Google Ads 专用 header。需要时用资源名格式的login-account/linked-accountheader文档示例如下login_account_id的取值1234567890是文档示例占位值parent_account、user_list_data需替换为你的账号父级资源名与受众对象headers [] account_type GOOGLE_ADS login_account_id 1234567890 if login_account_id: headers.append( ( login-account, faccountTypes/{account_type}/accounts/{login_account_id}, ) ) response user_list_client.create_user_list( parentparent_account, user_listuser_list_data, metadataheaders )格式化用户数据使用 utility library发送IngestAudienceMembersRequest前用 utility library 对用户标识符邮箱、手机号、地址做规范化与哈希。格式化参考给出的 Python 示例如下其中email是占位变量替换为你要上传的原始邮箱值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 )格式化的完整规则规范化、哈希、加密方式以官方 Format user data 指南为 source of truth本地文档将其指为唯一权威来源。与字段名相关的两条硬性约束UserIdentifier上的字段名是email_address和phone_number不要使用 Google Ads API 的旧字段名hashed_email、hashed_phone_numberaddress字段只在四个必填字段postal_code、family_name、given_name、region_code齐全时才设置字段不完整会导致 API 请求直接失败。构建并发送上传请求skill 文档给出的实现检查点按顺序为初始化客户端IngestionServiceClient构建Destination第 2 节格式化用户数据第 3 节构造请求体发送请求并记录返回的request_id检查响应中的field_warnings。其中与添加成员相关的三个要点请求类型添加成员使用IngestAudienceMembersRequest通过ingest_audience_members方法发送。terms_of_service必填向 Customer Match 受众上传时IngestAudienceMembersRequest必须携带terms_of_service字段表示用户已接受相关策略。encoding字段如果user_data中发送的是已哈希的用户标识符必须把请求的encoding字段设为HEX或BASE64。另外请求支持validate_only布尔选项设为true时只校验 schema、不实际落库适合正式上传前试跑一次但此时不要再调用诊断端点见第 4 节。各语言客户端库都提供了可直接参照的完整摄入样例脚本实现以它们为准Pythoningest_audience_members.py、JavaIngestAudienceMembers.java、PHPingest_audience_members.php、Nodeingest_audience_members.ts、.NETIngestAudienceMembers.cs文件名清单见 skill 文档的样例表。发送后如果响应里出现field_warningsFieldWarning对象列表说明某些非必填字段校验未通过应在正式批次中修正对应数据。边界说明本文只覆盖添加成员路径。移除指定成员与清空整个受众分别对应RemoveAudienceMembersRequest/RemoveAllAudienceMembersRequest和remove_audience_members/remove_all_audience_members方法目的地配置与诊断流程同本文但清空操作没有可用的嵌套状态字段与记录计数。验证轮询诊断接口确认成员真正入库skill 文档明确指出最常见的用户失误是跳过状态检查。摄入请求的处理是异步的HTTP 200 OK 并返回request_id只表示 payload 被接收不能说明成员已入库。要判断记录是成功、部分成功还是失败必须用request_id调用client.retrieve_request_status查询请求类型为RetrieveRequestStatusRequest(request_id...)。文档给出的轮询规则发送请求至少 30 分钟后开始按指数退避周期轮询。拿到响应后按以下顺序检查遍历响应中的request_status_per_destination检查每个目标的request_status处理完成request_status为SUCCESS、PARTIAL_SUCCESS或FAILED时检查摄入专属状态嵌套在audience_members_ingestion_status下的数据类型状态例如上传 composite data 时看composite_data_ingestion_status并查看record_count成功与失败的记录总数嵌套在数据类型状态对象内标识符计数composite data 看data_type_counts移动设备 ID 看mobile_id_countupload_match_rate_rangeuser_data与composite_data上传的匹配率区间。状态为FAILED或PARTIAL_SUCCESS时检查error_info.error_counts下每个错误的reason与record_count即使目的地状态是SUCCESS也要检查warning_info.warning_counts下每条警告的reason与record_count。注意当validate_only设为true时不要调用诊断端点retrieve_request_status。易错点与不适用场景上传前对照 skill 文档 的 Critical Gotchas除上文已并入各步骤的条目外还有一条ConsentStatus枚举值只有CONSENT_GRANTED和CONSENT_DENIED不要使用GRANTED/DENIED。以下情况不属于本文路径上传事件或转化离线转化、enhanced conversions for leads、点击转化等应走 Data Manager API 的事件摄入/v1/events/ingest端点对应仓库中的 contenteditable="false">【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考