过滤条件

如果报告包含过滤器，且社区连接器为所有请求的字段返回未过滤的数据，则 Looker Studio 会向连接器响应应用过滤器。不过，您可以在社区连接器级别应用过滤器，这在某些情况下可以显著提高性能。过滤器信息在 getData() 请求对象中传递，连接器可以使用该信息来过滤数据，然后再将其发送回 Looker Studio。

例如，如果您连接到 SQL 数据库，则直接在 WHERE 子句中应用过滤器（下图中的 B3）可以大大减少返回到 Looker Studio 的行数。这反过来又限制了必须处理并发送到 Looker Studio 的数据量 (B5)。

注意： 应用过滤器并不是一项硬性要求，但是如果您希望通过应用过滤器获得性能提升，则建议这样做。

应用过滤器的规则

1. 要么应用全部过滤器，要么一个也不应用。请参阅不支持的过滤器
2. 请勿在响应中包含 forFilterOnly 字段。

3. 将 request.dimensionsFilters 数组中的每个条目通过 AND 运算结合到一起。

   例如，对于下面的过滤器，连接器应仅包含 country 为 USA 且 source 为 Social 的值。

   {
     "dimensionsFilters": [
       [{
         "fieldName": "country",
         "values": ["USA"],
         "type": "INCLUDE",
         "operator": "EQUALS"
       }],
       [{
         "fieldName": "source",
         "values": ["Social"],
         "type": "INCLUDE",
         "operator": "EQUALS"
       }]
     ]
   }
   

4. 将 request.dimensionsFilters 数组中的每个子数组通过 OR 运算结合到一起。

   例如，对于下面的过滤器，连接器应仅包含 country 为 USA 或 country 为 Canada 的值。

   {
     "dimensionsFilters": [
       [{
         "fieldName": "country",
         "values": ["Canada"],
         "type": "INCLUDE",
         "operator": "EQUALS"
       }, {
         "fieldName": "country",
         "values": ["USA"],
         "type": "INCLUDE",
         "operator": "EQUALS"
       }]
     ]
   }
   

注意： OR 和 AND 之间的差别微乎其微。AND 具有结构 [[1], [2]]，而 OR 具有结构 [[1, 2]]

示例

以下示例演示了从报告用户定义过滤器到社区连接器返回过滤后的数据的端到端流程。

1. 报告用户已配置两个过滤器：

   1. country 是 Canada, USA 的 IN_LIST
   2. source 是 Social, Organic 的 IN_LIST

2. 报告用户已使用 source 维度和 sessions 指标配置了图表组件

3. Looker Studio 通过以下请求对象执行 getData()：

   {
     "fields": [
       {"name": "source"},
       {"name": "sessions"},
       {"name": "country", "forFilterOnly": true}
     ],
     "dimensionsFilters": [
       [{
         "fieldName": "country",
         "values": ["Canada", "USA"],
         "type": "INCLUDE",
         "operator": "IN_LIST"
       }],
       [{
         "fieldName": "source",
         "values": ["Social", "Organic"],
         "type": "INCLUDE",
         "operator": "IN_LIST"
       }]
     ]
   }
   

4. 连接器做出响应，返回过滤后的数据。

   对于示例请求，返回 source 和 sessions，其中 country 是 "Canada" 或 "USA" 且 source 是 "Social" 或 "Organic"。由于所有过滤器都可以成功应用，因此可将 filtersApplied 设为 true。

原始数据

来源	会话数	国家/地区
Social	60	USA
Social	50	Canada
Social	40	UK
Organic	90	USA
Organic	80	Canada
Organic	70	UK
Newspaper	30	USA
Newspaper	20	Canada
Newspaper	10	UK

过滤后的数据

来源	会话数
Social	60
Social	50
Organic	90
Organic	80

getData() 响应

{
  "schema": [
    {"name": "source",   "dataType": "STRING"},
    {"name": "sessions", "dataType": "NUMBER"},
  ],
  "rows": [
    {"values": ["Social", 60]},
    {"values": ["Social", 50]},
    {"values": ["Organic", 90]},
    {"values": ["Organic", 80]}
  ],
  "filtersApplied": true
}

要点： response.rows[].values 不具有 country 对应的条目，且 filtersApplied 设为 true。

不支持的过滤器

如果连接器无法在请求中应用所有过滤器，则不应执行任何过滤。返回所有请求的字段（包括 forFilterOnly 字段）并将响应中的 filtersApplied 键设为 false。

要点：这是 getData() 的标准响应。所有现有连接器都与此项更改向后兼容。

示例：

{
  "schema": [
    {"name": "source",   "dataType": "STRING"},
    {"name": "sessions", "dataType": "NUMBER"},
    {"name": "country",  "dataType": "STRING"}
  ],
  "rows": [
    {"values": ["Social", 60, "USA"]},
    {"values": ["Social", 50, "Canada"]},
    {"values": ["Social", 40, "UK"]},
    {"values": ["Organic", 90, "USA"]},
    {"values": ["Organic", 80, "Canada"]},
    {"values": ["Organic", 70, "UK"]},
    {"values": ["Newspaper", 30, "USA"]},
    {"values": ["Newspaper", 20, "Canada"]},
    {"values": ["Newspaper", 10, "UK"]},
  ],
  "filtersApplied": false
}