filters
查询字符串参数会限制 AdSense Management API 报告中返回的数据。使用 filters
参数时,您需要提供要过滤的维度,然后提供过滤表达式。
过滤的查询会限制要包含在结果中的行。结果中的每一行都针对过滤器进行测试:如果过滤器匹配,该行会被保留;如果不匹配,该行会被丢弃。
- 网址编码:客户端库会自动对过滤器运算符进行编码。但是,如果您直接向协议发出请求,则必须按下表所示对过滤器运算符进行明确编码。
- 过滤优先级:过滤操作发生在对任何维度进行汇总之前,确保返回的指标仅代表相关维度的总和。
过滤条件语法
单个过滤条件使用以下格式:
name operator expression
在这一语法中:
- name - 过滤所依据的维度的名称。例如:
AD_CLIENT_ID
会按广告客户 ID 进行过滤。 - 运算符 - 定义要使用的过滤器匹配的类型。
- expression - 说明要包含在结果中的值。
除了与日期相关的维度(DATE
、WEEK
和 MONTH
)之外,所有适用于所报告指标的维度都可以用作过滤条件。如需按日期进行过滤,请改为指定报告的日期范围。
过滤条件运算符
有两种过滤器运算符。运算符必须采用网址编码,才能包含在网址查询字符串中。
运营商 | 说明 | 网址编码格式 | 示例 |
---|---|---|---|
== |
完全匹配 | %3D%3D |
国家/地区名称为“加拿大”时的汇总指标:
filters=COUNTRY_NAME%3D%3DCanada |
=@ |
包含子字符串 | %3D@ |
国家/地区名称包含“United”(例如,“United States”和“United Kingdom”都是匹配情况)时的汇总指标:
filters=COUNTRY_NAME%3D@United |
过滤条件表达式
下面是过滤条件表达式要遵守的一些重要规则:
- 网址预留字符 -
&
等字符必须以常规方式进行网址编码。客户端库会替您完成这项工作,因此,只有在直接调用协议时,您才需要考虑此编码问题。 - 预留字符 - 如果逗号和反斜杠出现在表达式中,必须用反斜杠进行转义。
- 反斜杠
\\
- 英文逗号
\,
- 反斜杠
注意 :请确保将转义反斜杠加在逗号前面,以避免重复转义。
合并过滤条件
过滤器可以使用 OR
和 AND
布尔值逻辑进行组合。
OR 逻辑
OR
逻辑通过在过滤器表达式中使用英文逗号 (,
) 进行定义。
示例:(均须经过网址编码)
国家/地区代码为(美国或英国):
COUNTRY_CODE==US,COUNTRY_CODE==UK
AND 逻辑
AND
逻辑通过提供多个过滤器参数(会转换为在客户端库中提供过滤器数组)实现。
示例:
国家/地区代码是 US AND 产品代码是 AFC:
filters=COUNTRY_CODE%3D%3DUS&filters=PRODUCT_CODE%3D%3DAFC
组合 AND 和 OR 逻辑
您可以将 AND 和 OR 逻辑合并为一个表达式。
注意 :系统会对每个过滤器进行单独评估,然后才会将所有过滤器合并到一个 AND 逻辑表达式中。
示例:
国家/地区代码是 (US OR UK) AND 商品代码是 AFC:
filters=COUNTRY_CODE%3D%3DUS,COUNTRY_CODE%3D%3DUK&filters=PRODUCT_CODE%3D%3DAFC