如何通过GA4报告API获取自定义事件统计数据？

核心问题：误用了UA的API客户端 #

你当前的Ruby代码基于Universal Analytics（UA）的Reporting API v4编写，但GA4需要使用Google Analytics Data API v1，两者的请求结构、参数命名逻辑完全不同，这是导致错误的主要原因。

修正步骤 #

1. 切换到GA4 Data API客户端 #

确保你的Ruby项目使用GA4对应的API依赖，在Gemfile中更新：

gem 'google-api-client', '~> 0.53' # 需支持Analytics Data API

执行bundle install完成依赖更新。

2. 修正指标与维度命名规则 #

GA4采用蛇形命名法（snake_case），事件参数的维度格式为event_params.[参数名]：

• 事件计数指标：event_count（替代UA的ga:hits）
• 自定义事件参数维度：event_params.artist（需与前端发送的参数键大小写完全匹配，你的代码中是小写artist）

3. 正确的GA4 API请求代码示例 #

require 'google/apis/analyticsdata_v1beta'
require 'googleauth'

# 初始化GA4 Data API客户端
AnalyticsData = Google::Apis::AnalyticsdataV1beta
client = AnalyticsData::AnalyticsDataService.new
client.authorization = Google::Auth::ServiceAccountCredentials.make_creds(
  json_key_io: File.open('path/to/your/ua-credential.json'), # UA凭证可复用，需确保服务账号有权访问GA4属性
  scope: ['https://www.googleapis.com/auth/analytics.readonly']
)

# 配置基础参数
property_id = 'properties/XXXXXX' # 替换为你的GA4属性ID，格式为properties/数字
last_days = 30
NUM_ARTISTS = 10 # 替换为你的目标数量

# 构建请求组件
metric = AnalyticsData::Metric.new(name: 'event_count')
dimension = AnalyticsData::Dimension.new(name: 'event_params.artist')
order_by = AnalyticsData::OrderBy.new(
  desc: true,
  metric: AnalyticsData::MetricOrderBy.new(metric_name: 'event_count')
)
date_range = AnalyticsData::DateRange.new(
  start_date: "#{last_days + 1}daysAgo",
  end_date: 'today'
)

# 生成并发送报告请求
request = AnalyticsData::RunReportRequest.new(
  property: property_id,
  metrics: [metric],
  dimensions: [dimension],
  order_bys: [order_by],
  date_ranges: [date_range],
  limit: NUM_ARTISTS + 1
)

response = client.run_report(request)

# 处理响应示例
response.rows.each do |row|
  artist_name = row.dimension_values.first.value
  event_count = row.metric_values.first.value
  puts "#{artist_name}: #{event_count}"
end

4. 关键注意事项 #

• 属性ID格式：GA4属性ID必须以properties/为前缀，可在GA4后台「管理>属性设置」中获取。
• 参数大小写匹配：event_params.artist中的artist需与前端gtag发送的参数键完全一致，若GA4后台显示为大写Artist，大概率是UI自动格式化，实际参数名以代码为准。
• 权限配置：确保服务账号已被添加到GA4属性的「查看者」或更高权限角色（GA4后台「管理>访问权限>账号权限」中设置）。

验证查询 #

使用GA4查询工具时，需修正参数：

• Metrics: event_count
• Dimensions: event_params.artist
• Order by: event_count desc
  即可正确获取各艺术家的事件统计数据，而非(not set)。

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