使用服务账号认证GA4 Analytics Data API遇到问题

已完成的配置步骤 #

• 在GCP项目中启用Google Analytics Data API
• 在GCP控制台的Analytics Data API凭据页面创建服务账号
• 创建并下载服务账号的JSON密钥文件
• 设置GOOGLE_APPLICATION_CREDENTIALS环境变量指向该JSON文件路径
• 将服务账号添加为目标GA4属性所属Analytics账号的管理员

Python脚本执行错误 #

运行使用BetaAnalyticsDataClient的脚本时，所有端点调用均返回超时错误：

response = client.run_report(request)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/blah/newenv/lib/python3.11/site-packages/google/analytics/data_v1beta/services/beta_analytics_data/client.py", line 518, in run_report
  response = rpc(
             ^^^^
File "/blah/newenv/lib/python3.11/site-packages/google/api_core/gapic_v1/method.py", line 113, in __call__
  return wrapped_func(*args, **kwargs)
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/blah/newenv/lib/python3.11/site-packages/google/api_core/timeout.py", line 120, in func_with_timeout
  return func(*args, **kwargs)
         ^^^^^^^^^^^^^^^^^^^^^
File "/blah/newenv/lib/python3.11/site-packages/google/api_core/grpc_helpers.py", line 74, in error_remapped_callable
  raise exceptions.from_grpc_error(exc) from exc
google.api_core.exceptions.DeadlineExceeded: 504 Deadline Exceeded

注：调用全局内部属性的示例脚本、通过BetaAnalyticsDataClient.from_service_account_file()初始化客户端，均出现相同超时问题。

额外测试及结果 #

1. 激活服务账号：

gcloud auth activate-service-account --key-file the-service-account-json-key.json

2. 获取访问令牌：

gcloud auth application-default print-access-token

3. 执行curl请求：

curl -X GET \                                     
  -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
  -H "Content-Type: application/json; charset=utf-8" \
  https://analyticsdata.googleapis.com/v1beta/properties/0/metadata

返回403权限错误：

{
  "error": {
    "code": 403,
    "message": "Request had insufficient authentication scopes.",
    "status": "PERMISSION_DENIED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "ACCESS_TOKEN_SCOPE_INSUFFICIENT",
        "domain": "googleapis.com",
        "metadata": {
          "method": "google.analytics.data.v1beta.BetaAnalyticsData.GetMetadata",
          "service": "analyticsdata.googleapis.com"
        }
      }
    ]
  }
}

已给服务账号管理员权限，还需配置什么才能正常工作？

1. 修复权限范围不足问题 #

ACCESS_TOKEN_SCOPE_INSUFFICIENT是核心问题，需确保令牌包含正确的API访问范围：

• 使用gcloud获取令牌时指定范围：

gcloud auth application-default set-quota-project YOUR_GCP_PROJECT_ID
gcloud auth application-default login --scopes=https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform

• 或在Python代码中显式声明范围：

from google.oauth2 import service_account
from google.analytics.data_v1beta import BetaAnalyticsDataClient

SCOPES = ["https://www.googleapis.com/auth/analytics.readonly"]
credentials = service_account.Credentials.from_service_account_file(
    "your-service-account-key.json", scopes=SCOPES
)
client = BetaAnalyticsDataClient(credentials=credentials)

2. 排查超时问题 #

超时多由网络或客户端配置导致：

• 测试网络连通性：执行ping analyticsdata.googleapis.com或telnet analyticsdata.googleapis.com 443确认能访问API服务
• 增加客户端超时时间：

request = # 你的请求对象
response = client.run_report(request, timeout=30) # 设置30秒超时

• 切换到REST传输（规避gRPC网络限制）：

client = BetaAnalyticsDataClient(credentials=credentials, transport="rest")

3. 验证服务账号权限配置 #

• 将服务账号直接添加到GA4属性的权限列表（而非仅Analytics账号）：
  登录GA4后台 → 管理 → 属性访问管理 → 添加用户 → 输入服务账号邮箱，分配查看者及以上权限
• 等待权限生效（Google权限同步需5-10分钟）

4. 确认GCP项目关联 #

确保启用Analytics Data API的GCP项目，与服务账号所属GCP项目为同一项目；跨项目调用需额外配置跨项目API权限。

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