求助：使用API从Google Analytics 4拉取自定义事件数据至Google Sheets失败

1. 确认自定义事件的收集状态 #

• 登录GA4后台，进入事件列表，确认目标自定义事件标记为「已收集」，且最近有数据产生（新创建的事件通常需要24-48小时同步到API）
• 检查事件命名规范：事件名称不能含空格、特殊字符（仅允许下划线），参数值需为字符串或数值类型

2. 修正API请求的维度与筛选配置 #

• 请求必须指定eventName维度，并通过筛选条件锁定自定义事件，以下是Google Apps Script中的示例代码片段：

  const requestPayload = {
    dateRanges: [{startDate: '7daysAgo', endDate: 'today'}],
    dimensions: [{name: 'eventName'}],
    metrics: [{name: 'eventCount'}],
    dimensionFilter: {
      filter: {
        fieldName: 'eventName',
        stringFilter: {matchType: 'EXACT', value: '你的自定义事件名称'}
      }
    }
  };
  

• 注意：自定义事件是通过eventName维度筛选的，不能当作指标直接请求

3. 验证权限与API配额 #

• 确认脚本使用的OAuth令牌已授予analytics.readonly权限，且关联的GA4媒体资源ID正确
• 在Google Cloud Console的API库中检查GA4 API配额，配额耗尽会导致部分数据无法拉取

4. 排查事件触发逻辑 #

• 检查前端触发代码是否正确，示例：

  gtag('event', '自定义事件名称', {
    '自定义参数1': '参数值1',
    '自定义参数2': 123
  });
  

• 用GA4实时报告验证事件是否正常触发，若实时报告无数据，说明事件本身未被收集，与API无关

5. 检查Sheets脚本的处理逻辑 #

• 确认脚本在解析API返回数据时，没有过滤掉自定义事件的条目
• 若使用第三方插件（如GA4 Sheets Add-on），重新配置插件的事件筛选规则，确保自定义事件被包含在内

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