[null,null,["最后更新时间 (UTC)：2025-08-31。"],[[["\u003cp\u003eThe Ad Manager API allows filtering on \u003ccode\u003eList\u003c/code\u003e methods using a syntax defined in an EBNF grammar, supporting common use cases like filtering by time, targeting, and display name.\u003c/p\u003e\n"],["\u003cp\u003eFilters can utilize logical operators (AND, OR), negation operators (NOT, -), comparison operators (=, !=, <, >, <=, >=), and wildcards (*) for flexible data querying.\u003c/p\u003e\n"],["\u003cp\u003eTraversal (.), has (:), and wildcard operators enable filtering based on object properties, collection membership, and substring matching within strings.\u003c/p\u003e\n"],["\u003cp\u003eFilters are subject to limitations, including case-sensitivity for logical operators and restrictions on traversing repeated fields, and specific services may impose additional constraints.\u003c/p\u003e\n"],["\u003cp\u003eOrdering results is supported using the \u003ccode\u003eorderBy\u003c/code\u003e clause with comma-separated field names, allowing for ascending or descending order by appending " desc".\u003c/p\u003e\n"]]],["The Ad Manager API utilizes filter strings for `List` methods, supporting fuzzy matching against resource fields. Filters use comparison operators (`=`, `!=`, `\u003c`, `\u003e`, `\u003c=`, `\u003e=`), logical operators (`AND`, `OR`), and negation operators (`NOT`, `-`). String literals require double quotes, and wildcards (`*`) are supported for string matching. Traversal (`.`) and \"has\" (`:`) operators allow deeper querying, but specific element indexing in repeated fields is invalid. `orderBy` sorts results, with \"desc\" indicating descending order. URL encoding is needed for GET requests.\n"],null,["# Filters\n\nThe Ad Manager API supports filtering on `List` methods. The filter string\nsyntax is formally defined in the [EBNF\ngrammar](//google.aip.dev/assets/misc/ebnf-filtering.txt).\n\nTo get started, here are some examples of common use cases.\n\n| Example | Meaning |\n|--------------------------------------------------------|-----------------------------------------------------------------------------------------------------|\n| `orders.updateTime \u003e \"2024-01-01T00:00:00-5:00\"` | Lists orders with an `updateTime` after January 1, 2024 in the Eastern Standard Timezone |\n| `lineItems.targeting.geoTargeting.targetedGeoIds:2840` | Lists line items with a geographic targeting that contains the United States (geo target ID `2480`) |\n| `lineItems.displayName = \"*_interstitial\"` | Lists line items that have a display name that ends with the string `_interstitial` |\n| `orders.displayName = \"*video*\"` | Lists orders that have a display name that contains the string `video` |\n| `displayName:\"video\"` | Lists orders that have a display name that contains the string `video` (alternate syntax) |\n\n| **Tip:** Filter must be URL-encoded for `GET` requests. For example: Filter string: `orders.updateTime \u003e \"2024-01-01T00:00:00-5:00\"` URL encoded: `orders.updateTime%20%3E%20%222024-01-01T00:00:00-5:00%22`. This is handled automatically by client libraries.\n\n### Literals\n\nA bare literal value (examples: `42`, `Hugo`) is a value to be matched against.\nLiterals appearing alone are fuzzy matched against all of the supported fields\non a resource. Resources document which fields are considered for matching on\nthe `list` method. This feature is comparable to [universal\nsearch](//support.google.com/admanager/answer/1385724) in the Ad Manager UI but\nscoped to a single resource type.\n\nString literals containing spaces should be wrapped in double quotes (example:\n`\"Foo bar\"`). Single quotes cannot be used to wrap string literals.\n\n### Logical operators\n\nThe Ad Manager API supports the binary operators `AND` and `OR`.\n| **Caution:** These operators are **case-sensitive** . The literals `and` and `or` are treated as [Literals](#literals).\n\n| Operator | Example | Meaning |\n|----------|---------------|----------------------------------------|\n| `AND` | `a AND b` | True if `a` and `b` are true. |\n| `OR` | `a OR b OR c` | True if any of `a`, `b`, `c` are true. |\n\n| **Note:** To match common patterns of speech, the `OR` operator has higher precedence than `AND`, unlike what is found in most programming languages. The expression `a AND b OR c` evaluates as `a AND (b OR c)`. When possible, use explicit parentheses to avoid confusion.\n\n### Negation operators\n\nThe Ad Manager API provides the unary operators `NOT` and `-`. These can be used\ninterchangeably.\n\n| Operator | Example | Meaning |\n|----------|---------|--------------------------|\n| `NOT` | `NOT a` | True if `a` is not true. |\n| `-` | `-a` | True if `a` is not true. |\n\n### Comparison operators\n\nThe Ad Manager API supports the binary comparison operators `=`, `!=`, `\u003c`, `\u003e`,\n`\u003c=`, and `\u003e=` for string, numeric, timestamp, and duration fields.\n\n| Operator | Example | Meaning |\n|----------|--------------|-------------------------------------------------|\n| `=` | `a = true` | True if `a` is true. |\n| `!=` | `a != 42` | True unless `a` equals 42. |\n| `\u003c` | `a \u003c 42` | True if `a` is a numeric value less than 42. |\n| `\u003e` | `a \u003e \"foo\"` | True if `a` is lexically ordered after \"foo\". |\n| `\u003c=` | `a \u003c= \"foo\"` | True if `a` is \"foo\" or lexically before it. |\n| `\u003e=` | `a \u003e= 42` | True if `a` is a numeric value of 42 or higher. |\n\n| **Note:** Unlike in most programming languages, field names **must** appear on the left-hand side of a comparison operator; the right-hand side only accepts literals and logical operators.\n\nBecause filters are accepted as query strings, type conversion takes place to\ntranslate the string to the appropriate strongly-typed value:\n\n- Strings expect double quotes. Example: `\"Foo bar\"`.\n- Enums expect the enum's string representation (case-sensitive).\n- Booleans expect `true` and `false` literal values.\n- Numbers expect the standard integer or float representations. For floats, exponents are supported. Example: `2.997e9`.\n- Durations expect a numeric representation followed by an `s` suffix (for seconds). Examples: `\"20s\"`, `\"1.2s\"`.\n- [Timestamps](/ad-manager/api/beta/reference/rest/v1/DateTime) expect an [RFC-3339](//tools.ietf.org/html/rfc3339) formatted string. Example: `\"2012-04-21T11:30:00-04:00\"`. UTC offsets are supported.\n\n| **Caution:** The identifiers `true`, `false`, and `null` only carry intrinsic meaning when used in the context of a typed field reference.\n\n### Wildcards\n\nWhen comparing strings for equality, the Ad Manager API supports wildcards using\nthe `*` character.\n\n| Example | Meaning |\n|---------------|---------------------------------|\n| `a = \"*.foo\"` | True if `a` *ends with* \".foo\". |\n\n### Traversal operator\n\nThe Ad Manager API supports the `.` operator, which indicates traversal through\na message, map, or struct.\n\n| Example | Meaning |\n|-----------------|--------------------------------------------------------------|\n| `a.b = true` | True if `a` has a boolean `b` field that is true. |\n| `a.b \u003e 42` | True if `a` has a numeric `b` field that is greater than 42. |\n| `a.b.c = \"foo\"` | True if `a.b` has a string `c` field that is \"foo\". |\n\nTraversal is written using the field names from the resource. Individual\nservices could specify a subset of fields that are supported for traversal.\n| **Important:** The `.` operator **cannot** be used to traverse through a repeated field or list, except for specific use with the `:` operator.\n\n### Has operator\n\nThe Ad Manager API supports the `:` operator, which means \"has\". It is usable\nwith collections (repeated fields or maps), messages, and Strings and behaves\nslightly differently in each case.\n\nString fields query to see if the string contains a matching substring:\n\n| Example | Meaning |\n|----------------------------|-----------------------------------------------------------------------------|\n| `r.displayName:\"_250x250\"` | True if the String field `r.displayName` contains the substring `_250x250`. |\n\nRepeated fields query to see if the repeated structure contains a matching\nelement:\n\n| Example | Meaning |\n|------------|-------------------------------------------------------------|\n| `r:42` | True if `r` contains 42. |\n| `r.foo:42` | True if `r` contains an element `e` such that `e.foo = 42`. |\n\n| **Important:** Filters cannot query a *specific* element on a repeated field for a value. For example, `e.0.foo = 42` and `e[0].foo = 42` are **not** valid filters.\n\nMaps, structs, and messages can query either for the presence of a field in the\nmap or a specific value:\n\n| Example | Meaning |\n|------------|-------------------------------------|\n| `m:foo` | True if `m` contains the key \"foo\". |\n| `m.foo:*` | True if `m` contains the key \"foo\". |\n| `m.foo:42` | True if `m.foo` is 42. |\n\nWhen traversing messages, a field is only considered to be present if it has a\nnon-default value.\n\n### Limitations\n\nIndividual services can specify further structure or limitations for filter\nqueries in addition to what is defined here.\n\nOrder\n-----\n\nMost resources support ordering on `List` methods. Refer to the `List` method\ndocumentation for the resource's precise behavior and which fields are supported\nfor ordering.\n\nThe syntax for `orderBy` fields is a comma separated list of field names. For\nexample: `\"foo,bar\"`.\n\nThe default sorting order is ascending. To specify descending order for a field,\nappend a `\" desc\"` suffix. For example: `\"foo desc, bar\"`.\n\nRedundant space characters in the syntax are ignored. The values `\"foo, bar\ndesc\"`, `\" foo , bar desc \"`, and `\"foo,bar desc\"` are all equivalent.\n\nSubfields are specified with the [traversal operator](#traversal_operator). For\nexample: `foo.bar` or `address.street`."]]
