PHP使用服务账号连接Google Ads API报错求助

问题背景 #

当前使用PHP客户端通过服务账号模式连接Google Ads API，核心实现代码如下：

$oAuth2Credential = (new OAuth2TokenBuilder())
        ->withJsonKeyFilePath(self::CREDENTIALS_FILE_PATH)
        ->withScopes('https://www.googleapis.com/auth/adwords')
        ->withImpersonatedEmail(IMPERSONATED_EMAIL)
        ->build();

    $googleAdsClient = (new GoogleAdsClientBuilder())
        ->withOAuth2Credential($oAuth2Credential)
        ->withDeveloperToken(DEVELOPER_TOKEN)
        ->build();
    $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();

    $query = 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id';
    $stream =
        $googleAdsServiceClient->searchStream(CUSTOMER_ID, $query);

已完成GCP项目与服务账号创建、服务账号广告权限配置、Google Workspace侧全域委派配置，调用接口时触发权限报错，报错截图如下：

这类服务账号+全域委派模式的权限报错，90%以上都是配置细节遗漏导致，按以下优先级逐一排查即可解决：

• 校验被模拟用户的Google Ads权限
  • 填入withImpersonatedEmail的邮箱，必须是直接添加到目标广告账号（对应CUSTOMER_ID）的用户，不支持通过用户组、组织架构继承权限，基础查询操作至少需要「只读」权限，数据修改操作需要匹配对应等级的编辑/管理权限。
  • 不要把服务账号的默认邮箱直接添加到Google Ads账号中，该模式下服务账号只做凭证生成载体，实际调用身份是配置的被模拟用户，给服务账号本身加广告权限不会生效。
• 核对全域委派配置
  • 进入Google Workspace管理后台的API全域委派配置页，确认对应服务账号的客户端ID已被授权，授权scope列表必须精确匹配https://www.googleapis.com/auth/adwords，不能多写尾斜杠、不能拼错路径，漏加、错加scope都会直接触发权限拒绝。
  • 全域委派配置最长需要15分钟生效，刚配置完立刻调用必然报错，等够生效窗口后再重试。
• 校验代码传入参数的正确性
  • CUSTOMER_ID必须传入纯数字格式，不能带-分隔符，例如正确格式是1234567890而非123-456-7890；如果要查询MCC经理账号下的子账号数据，此处要传子账号的客户ID，不能传MCC本身的ID。
  • DEVELOPER_TOKEN必须和当前调用环境匹配：测试广告账号要用测试令牌，正式账号要用审核通过的正式令牌，v14及以上版本的API客户端不兼容未升级的旧版开发者令牌。
  • 确认withJsonKeyFilePath指向的JSON密钥文件是对应服务账号的有效密钥，密钥未被禁用、删除，文件本身没有格式损坏。
• 兜底校验逻辑
  • 确认GCP侧对应服务账号未被禁用，服务账号已被授予「服务账号令牌创建者」权限，否则无法生成模拟用户的访问令牌。
  • 如果是测试广告账号，确认账号已和当前使用的开发者令牌完成绑定，没有超出测试账号的调用限额。
  • 打印代码生成的OAuth2访问令牌，通过Google官方令牌校验接口确认两个核心信息：一是令牌绑定的身份为配置的被模拟邮箱，而非服务账号自身邮箱；二是令牌已包含adwords访问权限。如果返回身份是服务账号邮箱，直接判定全域委派配置未生效，回到Workspace后台重新配置即可。

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