调用Google Cloud Postmaster API返回空数组的问题排查

云原生阿岚

2026-8-28

问题描述

已完成服务账号配置，编写了PHP脚本用于获取访问令牌并调用Gmail Postmaster Tools接口拉取域名列表，代码如下：

<?php

require_once 'JWT_1.php';
require_once 'JWT_KEY_1.php';

use Firebase\JWT\JWT;
use Firebase\JWT\Key;

$privateKey = <<<EOD
-----BEGIN PRIVATE KEY-----
someKey
-----END PRIVATE KEY-----
EOD;

$publicKey = <<<EOD
-----BEGIN PUBLIC KEY-----
someKey
-----END PUBLIC KEY-----
EOD;

$payload = array(
  "iss" => "myName@name.iam.gserviceaccount.com",
  "scope" => "https://www.googleapis.com/auth/postmaster.readonly",
  "aud" => "https://oauth2.googleapis.com/token",
  "exp" => (time() + 600),
  "iat" => time()
);

$jwt = JWT::encode($payload, $privateKey, 'RS256');

$urlToken = 'https://oauth2.googleapis.com/token';
$url = 'https://gmailpostmastertools.googleapis.com/v1/domains';

$payloadToken = array(
  "grant_type" => "urn:ietf:params:oauth:grant-type:jwt-bearer",
  "assertion" => $jwt
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $urlToken);
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payloadToken);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
$tokenAnswer = json_decode(curl_exec($ch), true);
$token = $tokenAnswer['access_token'];
curl_close($ch);

$ch = curl_init();
$headers = array(
  'Authorization: Bearer ' . $token,
  'Accept: application/json'
);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_ENCODING , "");
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
echo curl_exec($ch);

脚本调用接口时返回空数组，但同接口在API测试工具中可正常返回域名列表，常见原因如下：

服务账号未获得Postmaster域名授权：Gmail Postmaster Tools的域名数据归属验证域名的个人/Workspace用户，不属于GCP项目或服务账号本身。必须在Postmaster Tools后台将对应服务账号的邮箱添加为目标域名的授权用户（至少只读权限），服务账号才能拉取到域名数据。API测试工具调用正常，基本都是因为测试时使用的是已获得授权的个人用户凭据，而非服务账号凭据。
cURL请求Token的参数格式错误：代码中向OAuth2 Token接口传参时直接传入PHP数组，cURL会默认将请求编码为multipart/form-data格式，但OAuth2接口要求参数必须为application/x-www-form-urlencoded格式。该问题会导致返回的访问令牌权限范围异常，最终接口返回空结果。修复方式为将POSTFIELDS配置改为curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($payloadToken));。
Workspace场景下未配置域委派：如果服务账号属于Google Workspace组织，且未直接给服务账号授予Postmaster域名权限，需要先在GCP控制台给服务账号开启全域权限委派，同时在生成JWT的payload中增加sub字段，填写组织内已拥有Postmaster域名访问权限的用户邮箱，模拟该用户身份调用接口。
API未启用或权限配置不全：确认服务账号所属GCP项目已启用Gmail Postmaster Tools API，同时服务账号本身没有被组织策略限制调用该API。部分权限缺失场景不会直接返回403错误，会返回空数据集。
JWT签名异常：确认使用的Firebase JWT库版本兼容当前写法，私钥格式正确无转义问题，避免生成的JWT携带的身份信息无效，导致令牌权限不足。

排查优先级：先打印Token接口和业务接口的完整响应（包含响应头、错误字段）确认是否有隐藏报错，再修正cURL参数格式，之后核对Postmaster后台的服务账号授权状态，最后检查域委派和API启用配置。

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