调用Google Document AI API遭遇403 Forbidden错误的排查求助

地域影响说明 #

用户所在地（澳大利亚）与项目部署地（美国）不会直接导致403 Forbidden错误。Google Cloud API支持全球跨地域访问，只要网络连通正常，地域差异不会影响权限验证逻辑，403错误核心原因仍为权限或配置问题。

调试与检查方向 #

1. 验证服务账号权限 #

• 确认GOOGLE_APPLICATION_CREDENTIALS指向的服务账号，是否被分配了Document AI Processor User（roles/documentai.processorUser）角色，或针对目标Processor的细粒度访问权限。
• 登录Google Cloud IAM控制台，找到该服务账号，检查已分配角色列表，确保包含Document AI相关权限（仅cloud-platform全局权限不足以访问具体Processor）。

2. 核对Processor与Endpoint匹配性 #

• 确认代码中使用的Endpoint（us-documentai.googleapis.com）对应的Processor确实创建在美国（us）区域。若Processor实际部署在其他区域（如澳大利亚australia-southeast1），需同步修改Endpoint地址（例如australia-southeast1-documentai.googleapis.com）。
• 检查Endpoint中的项目ID、地域、Processor ID是否完全正确，无拼写错误。

3. 验证访问令牌有效性 #

• 将代码日志级别改为DEBUG，查看获取到的access token内容，执行以下命令验证令牌的权限范围和所属账号：

  curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" https://www.googleapis.com/oauth2/v3/tokeninfo
  

• 在代码中添加打印语句，确认服务账号身份：

  print(credentials.service_account_email)
  

4. 检查请求Payload与网络 #

• 验证图片Base64编码的正确性：将代码中生成的image_base64解码后，确认能还原为原始图片。
• 用curl直接发起API请求，排查是否为代码逻辑问题：

  curl -X POST "https://us-documentai.googleapis.com/v1/projects/230636727467/locations/us/processors/c9f3a42f91c1760f:process" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
          "rawDocument": {
            "content": "BASE64_ENCODED_IMAGE",
            "mimeType": "image/png"
          }
        }'
  

• 排查本地网络是否有防火墙/代理拦截请求，导致API返回403。

5. 二次确认API启用状态 #

• 再次确认Document AI API在项目230636727467中已正确启用，避免误操作启用了其他项目的API。

代码优化建议 #

1. 使用官方客户端库：替换手动REST调用为Google官方google-cloud-documentai库，自动处理令牌刷新、错误校验等逻辑，减少手动出错概率：

   from google.cloud import documentai_v1 as documentai
   
   def process_image(image_path: Path, processor_name: str) -> str:
       client = documentai.DocumentProcessorServiceClient()
       with open(image_path, "rb") as image_file:
           image_content = image_file.read()
       raw_document = documentai.RawDocument(content=image_content, mime_type="image/png")
       request = documentai.ProcessRequest(name=processor_name, raw_document=raw_document)
       response = client.process_document(request=request)
       return response.document.text
   

2. 开启DEBUG日志：修改日志配置为logging.DEBUG，获取请求/响应的详细信息，便于排查问题：

   logging.basicConfig(
       filename="google_transcription.log",
       level=logging.DEBUG,
       format="%(asctime)s - %(levelname)s - %(message)s"
   )
   

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