Google Postmaster API：如何正确传递startDate参数？

我用以下代码从Google Postmaster账号获取流量统计，不添加日期参数时运行正常，但加入startDate参数后无法工作：

$url = 'https://gmailpostmastertools.googleapis.com/v1/domains/'.$this_domain.'/trafficStats/?pageSize=9999&startDate=20221001&endDate=20221030';

$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);

$google_postmaster_api_json = curl_exec($ch);

$google_postmaster_api = json_decode($google_postmaster_api_json, true);
echo "<pre>";
var_dump($google_postmaster_api);
echo "</pre>";

添加日期参数后，API返回错误：

Invalid JSON payload received. Unknown name "startDate": Cannot bind query parameter. 'startDate' is a message type. Parameters can only be bound to primitive types.
Invalid JSON payload received. Unknown name "endDate": Cannot bind query parameter. 'endDate' is a message type. Parameters can only be bound to primitive types.

我尝试用POST请求传递JSON格式的日期范围，结果返回NULL：

$json_request = '{
  "dateRanges": [{ "startDate": "2022-10-01", "endDate": "2022-10-15" }],
}';

$ch = curl_init();
$headers = array(
  'Authorization: Bearer ' . $token,
  'Accept: application/json'
);
curl_setopt($ch, CURLOPT_POSTFIELDS, $json_request);
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, 'POST');
curl_setopt($ch,CURLOPT_POST,1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_ENCODING , "");
curl_setopt($ch, CURLOPT_TIMEOUT, 30);

$google_postmaster_api_json = curl_exec($ch);

问题原因与解决方案 #

1. 错误原因

API的startDate和endDate是消息结构体类型，不是字符串/数字这类原始类型，因此不能直接用startDate=20221001的形式传递参数。同时，trafficStats接口仅支持GET请求，POST请求会被拒绝，导致返回NULL。

2. 正确传递方式

将日期拆分为year、month、day三个子参数，作为GET查询参数传递，格式如下：

• startDate.year=YYYY
• startDate.month=MM
• startDate.day=DD
• endDate.year=YYYY
• endDate.month=MM
• endDate.day=DD

3. 修正后的代码

// 构造正确的URL，拆分日期参数
$url = 'https://gmailpostmastertools.googleapis.com/v1/domains/'.$this_domain.'/trafficStats/?pageSize=9999'
    . '&startDate.year=2022&startDate.month=10&startDate.day=1'
    . '&endDate.year=2022&endDate.month=10&endDate.day=30';

$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'); // 保持GET请求
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_ENCODING , "");
curl_setopt($ch, CURLOPT_TIMEOUT, 30);

$google_postmaster_api_json = curl_exec($ch);

$google_postmaster_api = json_decode($google_postmaster_api_json, true);
echo "<pre>";
var_dump($google_postmaster_api);
echo "</pre>";

这个方式符合API的参数绑定规则，能够正确获取指定日期范围的流量统计数据。

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