Apps Script OAuth2库权限范围丢失致403错误及自动解决情况

编辑：问题已解决，次日自动恢复正常。运行相同代码后可正常调用，推测因服务账号较新，后台配置任务未完成；日志仍显示无权限范围，但调用正常，疑为Apps Script日志同步延迟。

原问题场景 #

我尝试通过OAuth2库，使用GCP服务账号从电子表格查询Gemini，参考Google Workspace可安装触发器指南中的示例编写代码：

function test() {
  const service = OAuth2.createService(<ServiceName>)
      .setTokenUrl('https://accounts.google.com/o/oauth2/token')
      .setPrivateKey(<serviceAccountPrivateKey>)
      .setClientId(<serviceAccountAddress>)
      .setPropertyStore(PropertiesService.getUserProperties())
      .setScope([
        "https://www.googleapis.com/auth/spreadsheets.currentonly",
        "https://www.googleapis.com/auth/script.external_request",
        "https://www.googleapis.com/auth/cloud-platform"
      ]);

  console.log('access: ', service.hasAccess(), 'scopes: ', service.scope);

  if (!service.hasAccess()) {
    console.error('Authentication error: ', service.getLastError());
    return;
  }


  const options = {
    method: "post",
    contentType: 'application/json',   
    headers: {
     Authorization: `Bearer ${service.getAccessToken()}`,
    },
    payload: JSON.stringify({...})
  };

  let response = UrlFetchApp.fetch(<url>, options);
  ...
}

运行时日志显示access: true scopes: undefined，且返回如下错误：

Exception: Request failed for <url> returned code 403. Truncated server response: {
  "error": {
    "code": 403,
    "message": "Request had insufficient authentication scopes.",
    "status": "PERMISSION_DENIED",
    "details":... (use muteHttpExceptions option to examine full response)

已尝试的操作：

• 复制OAuth2库中的setScopes函数验证输入，确认可生成空格分隔的权限范围列表
• 尝试传入空格分隔字符串替代数组，仍显示undefined

分析与建议 #

1. 服务账号后台同步延迟：新创建的GCP服务账号常存在后台权限配置延迟，即使代码配置正确，也需要等待Google完成全链路的权限同步，无需修改代码，等待一段时间后重试即可。
2. Apps Script日志延迟：日志中service.scope显示undefined但实际调用正常，说明日志输出存在同步延迟，不要仅凭即时日志判断权限配置是否生效。
3. GCP端IAM权限检查：确保服务账号在GCP控制台中已被授予目标API（如Gemini API）的对应权限，代码中声明的OAuth2 scope仅为客户端层面的请求，GCP端的IAM配置才是最终权限控制。
4. 令牌实际权限验证：可调用Google令牌信息接口，传入获取到的access_token，查看令牌实际包含的权限范围，确认是否携带了所需的scope。
5. OAuth2库版本与方法检查：确认使用的OAuth2库为最新稳定版，部分旧版本可能存在setScope/setScopes方法名差异，导致scope设置不生效。

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