如何通过Curl请求从Google People API获取用户自定义联系组？PHP请求仅返回系统联系组的排查求助

安全阿岳

2026-4-28

排查Google People API联系组返回不一致的问题

我之前对接Google People API时也碰到过类似的情况，开发者工具里能拿到完整结果，但自己的代码只返回部分数据，给你几个关键的排查点：

遗漏API Key参数：你从开发者工具复制的Curl请求里，URL末尾带了?key=[YOUR_API_KEY]，但你的PHP代码里的URL完全没加这个参数！虽然Bearer Token已经做了身份验证，但API Key是请求的必要参数之一，缺失它可能导致API返回的资源范围被限制，尤其是部分系统联系组的获取依赖这个参数。
请求参数默认值差异：Google People API默认会分页返回结果，而且默认的groupFields可能只返回基础字段，导致看起来像是少了数据。你可以尝试在PHP的请求URL里补充参数，比如：
```
$url = "https://people.googleapis.com/v1/contactGroups?key=[YOUR_API_KEY]&pageSize=200&groupFields=metadata,name,groupType,memberCount,formattedName";
curl_setopt($ch, CURLOPT_URL, $url);
```
这里的pageSize设大一点避免分页，groupFields指定需要的字段，确保和开发者工具的请求参数一致。
权限Scope不匹配：检查你获取access_token时请求的权限范围，是否和开发者工具里使用的一致。比如如果开发者工具用了https://www.googleapis.com/auth/contacts（读写权限），而你的PHP代码只用了https://www.googleapis.com/auth/contacts.readonly，或者缺少针对Workspace账户的https://www.googleapis.com/auth/directory.readonly，都会导致返回的联系组不全。
Curl压缩配置缺失：开发者工具里的--compressed参数表示请求gzip压缩的响应，你的PHP代码里没有开启这个配置，虽然大部分情况下不影响内容，但少数场景下API会因为编码处理返回不同的结果。可以加上这行代码匹配工具配置：
```
curl_setopt($ch, CURLOPT_ENCODING, 'gzip');
```

修正后的完整PHP代码示例：

$access_token = "你的access_token";
$api_key = "你的API_KEY";

$ch = curl_init();
$url = "https://people.googleapis.com/v1/contactGroups?key={$api_key}&pageSize=200&groupFields=metadata,name,groupType,memberCount,formattedName";
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_ENCODING, 'gzip'); // 开启压缩
$headers = ["Authorization: Bearer {$access_token}", "Accept: application/json"];
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$data = curl_exec($ch);
$result = json_decode($data, true);
var_dump($result);
die();

你可以先补全API Key参数试试，这大概率是最直接的问题。如果还是不行，再依次检查其他几个点。

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