Google Ads API上传受众用户报collection_size_error:TOO_MANY错误排查

错误触发原因 #

该错误是Google Ads API的集合长度校验类错误，触发核心原因：

• UploadUserData（用户列表数据上传）接口对单请求携带的UserDataOperation操作条目有明确硬性上限：单请求最多支持传入20个操作项。
• 现有实现直接将userList内全量用户都构建为操作项，一次性塞入同一个请求提交，当待上传用户总量超过20时，就会触发该长度校验错误。
• 补充校验规则：单个UserDataOperation内最多支持传入5个用户标识，当前代码每个操作仅传1个哈希邮箱，不会触发该规则限制。

修复方案 #

• 对构建完成的全量操作列表做分片切割，每批最多保留20个操作项，分多次发起接口请求上传，禁止单请求携带超量操作。
• 分批上传时可并行发起请求，但需注意遵守Google Ads API的每日请求配额、每分钟速率限制规则，避免触发限流错误。
• 全量上传完成后可调用受众群体查询接口，等待24-48小时查看用户匹配进度，无需同步等待每批请求返回结果再传下一批。

问题原始代码 #

Set<String> userList;  // 存储经过哈希处理的待上传用户邮箱数据

List<UserDataOperation> userDataOperations = new ArrayList<>(userList.size());

for (String user : userList) {
  UserDataOperation userDataOperationEmail = UserDataOperation.newBuilder().setCreate(
      UserData.newBuilder()
          .addUserIdentifiers(UserIdentifier.newBuilder().setHashedEmail(user).build())
          .build()).build();
  userDataOperations.add(userDataOperationEmail);
}
// 错误逻辑：直接将全量操作列表传入单个请求，未做分片

修复后代码示例 #

Set<String> userList;  // 存储经过哈希处理的待上传用户邮箱数据
List<UserDataOperation> userDataOperations = new ArrayList<>(userList.size());

for (String user : userList) {
  UserDataOperation userDataOperationEmail = UserDataOperation.newBuilder().setCreate(
      UserData.newBuilder()
          .addUserIdentifiers(UserIdentifier.newBuilder().setHashedEmail(user).build())
          .build()).build();
  userDataOperations.add(userDataOperationEmail);
}

// 按单批最大20个操作做分片
int batchMaxSize = 20;
for (int offset = 0; offset < userDataOperations.size(); offset += batchMaxSize) {
  int endIndex = Math.min(offset + batchMaxSize, userDataOperations.size());
  List<UserDataOperation> currentBatch = userDataOperations.subList(offset, endIndex);
  
  // 构建上传请求
  UploadUserDataRequest uploadRequest = UploadUserDataRequest.newBuilder()
      .setCustomerId("你的广告账户客户ID")
      .setCustomerMatchUserListMetadata(目标受众群体的元数据配置)
      .addAllOperations(currentBatch)
      .build();
  
  // 发起当前批次上传
  try (UserDataServiceClient client = UserDataServiceClient.create()) {
    UploadUserDataResponse response = client.uploadUserData(uploadRequest);
  }
}

错误参考截图 #

内容的提问来源于stack exchange，提问作者Ajit Trivedi