Service Account访问Google Docs API报401错误如何解决

返回401是两个核心错误导致的：

• 你手动创建了独立的裸Guzzle Client实例发送请求，完全没有把Google Client生成的OAuth2授权凭证附加到请求头，Google API接收不到合法认证信息，直接拦截请求。
• setSubject()参数配置错误：该参数仅在使用域范围委派（Domain Wide Delegation）模拟Workspace域内用户时使用，需要填入域内真实存在的用户邮箱，不能填Service Account自身生成的邮箱地址。

<?php
require_once 'vendor/autoload.php';

$client = new Google\Client();
$client->setApplicationName('TESTING GOOGLE DOC API');
$client->setAuthConfig('hale-runner-356311-4acd25674408.json');
$client->setScopes("https://www.googleapis.com/auth/documents.readonly");
// 不需要模拟域内用户时直接删除下一行；需要模拟时填入Workspace内真实存在、对目标文档有访问权限的用户邮箱
// $client->setSubject('xxx@your-workspace-domain.com');
$client->setAccessType('offline');
// 关键：调用authorize()获取自动注入了授权逻辑的HTTP客户端，不要手动新建无认证的Guzzle实例
$httpClient = $client->authorize();

$response = $httpClient->request('GET', 'https://docs.googleapis.com/v1/documents/1G6BnSgWCEWn6a5UYeF1XjJYuXIwHxwlAmOIqHj3rtgU', [
    'verify' => false, // 仅本地调试证书问题时临时使用，生产环境请删除该配置
]);
var_dump($response->getBody()->getContents());

• 若使用Service Account访问非域委派场景的文档：不需要配置域委派、不需要填写setSubject参数，直接打开目标Google Doc的共享设置，把Service Account对应的邮箱（JSON密钥文件中client_email字段的值）添加为协作者，授予阅读权限即可。
• 若使用域范围委派访问Workspace域内用户的文档：需要在Workspace管理后台的域范围委派配置页，给当前Service Account的Client ID绑定你使用的https://www.googleapis.com/auth/documents.readonly权限 scope，且setSubject填入的用户必须对目标文档有对应访问权限。
• 确认Service Account的JSON密钥文件路径正确，PHP运行进程对该文件有读取权限，文件内容没有损坏。
• 不要手动初始化独立Guzzle实例调用Google API，$client->authorize()返回的HTTP客户端已经自动处理了token获取、过期刷新、授权头注入的全流程逻辑，不会出现认证参数漏传的问题。

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