App Script调用GA4 Data API拉取报告的多维度指标与筛选配置方法

所有示例基于Advanced AnalyticsData服务，使用前先在AppScript编辑器的「服务」菜单中添加好Google Analytics Data API即可。

一、多维度、多指标添加方法 #

dimensions和metrics参数本身就是数组结构，需要加几个字段就往数组里追加对应配置对象即可，不需要调整其他请求结构。
举个实际例子：如果你要拉取日期、国家、设备类别3个维度，活跃用户、会话数、跳出率3个指标，直接按下面的格式写：

function getGaReport() {
  // 替换成自己的GA4资源ID，格式固定为 properties/数字ID
  const propertyId = 'properties/替换成你的ID';
  const request = AnalyticsData.newRunReportRequest();

  // 多维度配置：按需要往数组里加就行
  request.dimensions = [
    AnalyticsData.newDimension().setName('date'),
    AnalyticsData.newDimension().setName('country'),
    AnalyticsData.newDimension().setName('deviceCategory')
  ];

  // 多指标配置：逻辑和维度完全一致
  request.metrics = [
    AnalyticsData.newMetric().setName('activeUsers'),
    AnalyticsData.newMetric().setName('sessions'),
    AnalyticsData.newMetric().setName('bounceRate')
  ];

  // 日期范围配置示例
  const dateRange = AnalyticsData.newDateRange();
  dateRange.setStartDate('30daysAgo');
  dateRange.setEndDate('today');
  request.dateRanges = [dateRange];

  const res = AnalyticsData.Properties.runReport(request, propertyId);
  if (!res.rows) return console.log('无匹配数据');
  
  // 解析返回结果：维度/指标值的数组顺序，和你写请求时的数组顺序完全对应
  res.rows.forEach(row => {
    const [date, country, device] = row.dimensionValues.map(i => i.value);
    const [activeUsers, sessions, bounceRate] = row.metricValues.map(i => i.value);
    console.log({date, country, device, activeUsers, sessions, bounceRate});
  })
}

新手避坑：返回结果里的dimensionValues、metricValues数组索引和请求里的配置顺序严格对应，不要搞错位。

二、筛选功能运行逻辑 #

先把核心逻辑搞懂，写筛选的时候就不会出莫名其妙的问题：

• 筛选分两类：维度筛选作用于原始维度字段，在指标聚合计算之前执行；指标筛选作用于聚合后的指标结果，在指标计算完成之后执行
• 支持逻辑嵌套：可以用「且(AND)」「或(OR)」「非(NOT)」组合任意多个筛选条件，满足复杂规则
• 混合维度+指标的组合筛选不需要拆分到不同参数里，统一放到同一个逻辑组里API会自动识别处理

三、筛选功能实现示例 #

1. 单条件维度筛选 #

比如只看国家为中国的流量：

// 构建国家=中国的筛选
const countryFilter = AnalyticsData.newFilterExpression();
const filter = AnalyticsData.newFilter();
filter.setFieldName('country');
const strFilter = AnalyticsData.newStringFilter();
strFilter.setMatchType('EXACT'); // 匹配规则：完全匹配
strFilter.setValue('China');
filter.setStringFilter(strFilter);
countryFilter.setFilter(filter);
// 挂载到请求上
request.dimensionFilter = countryFilter;

常用的字符串匹配规则还有：CONTAINS（包含指定字符串）、BEGINS_WITH（前缀匹配）、ENDS_WITH（后缀匹配）、FULL_REGEXP（正则匹配）。

2. 多条件组合筛选 #

比如要满足：来自中国 且 设备为移动端 且 分组会话数大于50，需要用AND逻辑组拼接多个条件：

// 条件1：国家=中国
const countryFilterExp = AnalyticsData.newFilterExpression();
const countryFilter = AnalyticsData.newFilter();
countryFilter.setFieldName('country');
const countryStrFilter = AnalyticsData.newStringFilter();
countryStrFilter.setMatchType('EXACT');
countryStrFilter.setValue('China');
countryFilter.setStringFilter(countryStrFilter);
countryFilterExp.setFilter(countryFilter);

// 条件2：设备=移动端
const deviceFilterExp = AnalyticsData.newFilterExpression();
const deviceFilter = AnalyticsData.newFilter();
deviceFilter.setFieldName('deviceCategory');
const deviceStrFilter = AnalyticsData.newStringFilter();
deviceStrFilter.setMatchType('EXACT');
deviceStrFilter.setValue('mobile');
deviceFilter.setStringFilter(deviceStrFilter);
deviceFilterExp.setFilter(deviceFilter);

// 条件3：会话数>50（指标筛选）
const sessionFilterExp = AnalyticsData.newFilterExpression();
const sessionFilter = AnalyticsData.newFilter();
sessionFilter.setFieldName('sessions');
const numFilter = AnalyticsData.newNumericFilter();
numFilter.setOperation('GREATER_THAN'); // 比较规则：大于
const numVal = AnalyticsData.newNumericValue();
numVal.setInt64Value(50);
numFilter.setValue(numVal);
sessionFilter.setNumericFilter(numFilter);
sessionFilterExp.setFilter(sessionFilter);

// 把三个条件合并为AND逻辑组
const andGroup = AnalyticsData.newFilterExpressionList();
andGroup.setExpressions([countryFilterExp, deviceFilterExp, sessionFilterExp]);
const rootFilter = AnalyticsData.newFilterExpression();
rootFilter.setAndGroup(andGroup);

// 挂载到请求上
request.dimensionFilter = rootFilter;

如果需要OR逻辑，把setAndGroup换成setOrGroup即可；如果需要对某个条件取反，调用对应FilterExpression的setNotExpression方法传入要取反的条件就行。

常见报错避坑：如果筛选里同时包含维度和指标条件，不要单独把指标条件挂到metricFilter参数上，直接放到同一个逻辑组里即可，否则会出现逻辑不生效或者参数类型错误。

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