过滤
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
filters 查询字符串参数会限制
AdSense Management API 报告中返回的数据。使用 filters 参数时，您需要
提供过滤依据的维度，后接过滤器表达式。
过滤查询可限制要包含在结果中的行。每行
都针对过滤器进行测试：如果过滤器匹配，该行
保留，如果不匹配，则删除该行。
- 网址编码：客户端库会自动对
过滤器运算符。不过，如果你直接向协议提出请求
您必须对过滤器运算符进行明确编码，如下表所示。
- 过滤优先级：过滤先于
确保返回的指标只代表
相关维度的数据
过滤器语法
单个过滤条件使用以下格式：
name operator expression
在这一语法中：
- name - 过滤所依据的维度的名称。
例如：
AD_CLIENT_ID 会按广告客户 ID 进行过滤。
- operator - 定义要使用的过滤器匹配的类型。
- expression - 说明要包含在结果中的值。
符合以下条件的所有维度：
所报告的指标可以用作过滤条件，
与日期相关的维度（DATE、WEEK、
和 MONTH）。要按日期过滤，请指定
日期范围。
过滤器操作符
有两种过滤器运算符。运算符必须经过网址编码，这样才能
包含在网址查询字符串中。
| 运算符 |
说明 |
网址编码格式 |
示例 |
== |
完全匹配 |
%3D%3D |
对国家/地区名称是“Canada”的指标进行汇总：
filters=COUNTRY_NAME%3D%3DCanada |
=@ |
包含子字符串 |
%3D@ |
国家/地区名称中包含“United”（此
与美国和英国匹配，例如：
filters=COUNTRY_NAME%3D@United |
过滤器表达式
过滤器表达式有一些重要的规则需要遵守：
- 网址预留字符 - 例如
& 必须按常规方式进行网址编码。客户端库
因此您只需要考虑编码问题
您将直接调用协议
- 预留字符：英文逗号和反斜杠必须
必须全部以反斜杠进行转义。
注意 ：务必在前面转义反斜杠，
以免重复转义。
合并过滤器
过滤条件可以使用 OR 和 AND 布尔值进行合并
逻辑。
OR 逻辑
OR 逻辑通过在,
过滤条件表达式。
示例：（均须经过网址编码）
国家/地区代码是 (US OR UK)：
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
后续步骤
如未另行说明，那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可，并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情，请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC)：2025-07-26。
[null,null,["最后更新时间 (UTC)：2025-07-26。"],[[["\u003cp\u003eThe \u003ccode\u003efilters\u003c/code\u003e query string parameter limits the data returned in an AdSense Management API report, allowing you to filter by dimension using operators and expressions.\u003c/p\u003e\n"],["\u003cp\u003eFiltering happens before aggregation, ensuring metrics reflect only the relevant dimensions.\u003c/p\u003e\n"],["\u003cp\u003eFilter expressions use operators like \u003ccode\u003e==\u003c/code\u003e for exact match and \u003ccode\u003e=@\u003c/code\u003e for substring match, requiring URL encoding for direct protocol calls.\u003c/p\u003e\n"],["\u003cp\u003eFilters can be combined using comma (\u003ccode\u003e,\u003c/code\u003e) for \u003ccode\u003eOR\u003c/code\u003e logic within a single filter parameter and multiple filter parameters for \u003ccode\u003eAND\u003c/code\u003e logic.\u003c/p\u003e\n"],["\u003cp\u003eDate filtering is done by specifying the date range for the report instead of using date-related dimensions in the \u003ccode\u003efilters\u003c/code\u003e parameter.\u003c/p\u003e\n"]]],["The `filters` parameter in the AdSense Management API refines report data by specifying dimensions and filter expressions. Filtering happens before aggregation, ensuring metrics represent only relevant dimensions. Filters use the syntax `name operator expression`, with `==` for exact matches and `=@` for substring containment. Multiple filters can be combined using `OR` (commas within a filter) and `AND` (multiple filter parameters), allowing complex logic. Date-related dimensions cannot be used, but escaping rules must be followed.\n"],null,["# Filtering\n\nThe `filters` query string parameter restricts the data returned\nin an AdSense Management API report. When you use the `filters` parameter, you\nsupply a dimension you want to filter on, followed by the filter expression.\n\nFiltered queries restrict the rows that get included in the result. Each row\nin the result is tested against the filter: if the filter matches, the row is\nretained and if it doesn't match, the row is dropped.\n\n- **URL Encoding**: The client libraries automatically encode the filter operators. However, if you make requests directly to the protocol, you must explicitly encode filter operators as indicated in the table below.\n- **Filtering priority** : Filtering occurs *before* any dimensions are aggregated, so that the returned metrics represent the total for only the relevant dimensions.\n\nFilter Syntax\n-------------\n\nA single filter uses the form: \n\n```\nname operator expression\n```\n\nIn this syntax:\n\n- *name* --- the name of the dimension on which to filter. For example: `AD_CLIENT_ID` will filter on the ad client ID.\n- *operator* --- defines the type of filter match to use.\n- *expression* --- states the values included in the results.\n\nAll [dimensions](/adsense/management/metrics-dimensions) that\napply to the metrics being reported on can be used as filters, with the\nexception of the date-related dimensions (`DATE`, `WEEK`,\nand `MONTH`). To filter by date, [specify the\ndate range for the report](/adsense/management/reporting/date_ranges) instead.\n\nFilter Operators\n----------------\n\nThere are two filter operators. The operators must be URL encoded in order to\nbe included in URL query strings.\n\n\u003cbr /\u003e\n\n| Operator | Description | URL Encoded Form | Example |\n|----------|--------------------|------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `==` | Exact match | `%3D%3D` | Aggregate metrics where the country name is *Canada* : `filters=COUNTRY_NAME%3D%3DCanada` |\n| `=@` | Contains substring | `%3D@` | Aggregate metrics where the country name contains *United* , this matches United States and United Kingdom for example: `filters=COUNTRY_NAME%3D@United` |\n\n\u003cbr /\u003e\n\nFilter Expressions\n------------------\n\nThere are a couple of important rules for filter expressions:\n\n- **URL-reserved characters** --- Characters such as `&` must be url-encoded in the usual way. Client libraries take care of this for you, so you only have to worry about this encoding if you are making direct calls to the protocol.\n- **Reserved characters** --- The comma and backslash must be backslash escaped when they appear in an expression.\n - backslash `\\\\`\n - comma `\\,`\n\n**Note:**Make sure you escape backslashes before\ncommas, in order to avoid double escaping.\n\nCombining Filters\n-----------------\n\nFilters can be combined using `OR` and `AND` boolean\nlogic.\n\n### OR logic\n\n`OR` logic is defined using a comma (`,`) inside the\nfilter expression. \n**Example:** *(each must be URL encoded)*\n\n\nCountry code is either (US OR UK): \n\n`COUNTRY_CODE==US,COUNTRY_CODE==UK`\n\n### AND logic\n\n`AND` logic is achieved by providing multiple filter parameters,\nwhich translates into providing an array of filters in the client libraries. \n**Example:**\n\nCountry code is US AND product code is AFC: \n\n`filters=COUNTRY_CODE%3D%3DUS&filters=PRODUCT_CODE%3D%3DAFC`\n\n### Combining AND and OR logic\n\nIt's possible to combine AND and OR logic into a single expression.\n\n**Note:**Each filter is evaluated individually\nbefore all filters are combined into an AND logical expression. \n**Example:**\n\nCountry code is (US OR UK) AND product code is AFC: \n\n`filters=COUNTRY_CODE%3D%3DUS,COUNTRY_CODE%3D%3DUK&filters=PRODUCT_CODE%3D%3DAFC`\n\nNext steps\n----------\n\n- [Choosing the Right Dimension](/adsense/management/reporting/right_dimension)\n- [Running Large Reports](/adsense/management/reporting/large_reports)\n- [List of Metrics and Dimensions](/adsense/management/metrics-dimensions)"]]
