Filtres

L'API Ad Manager est compatible avec le filtrage des méthodes List. La syntaxe de la chaîne de filtre est définie de manière formelle dans la grammaire EBNF.

Pour commencer, voici quelques exemples de cas d'utilisation courants.

Exemple	Signification
orders.updateTime > "2024-01-01T00:00:00-5:00"	Liste les commandes associées à un updateTime après le 1er janvier 2024 dans le fuseau horaire standard de l'Est
lineItems.targeting.geoTargeting.targetedGeoIds:2840	Liste les éléments de campagne dont le ciblage géographique inclut les États-Unis (ID de zone géographique cible 2480).
lineItems.displayName = "*_interstitial"	Répertorie les éléments de campagne dont le nom à afficher se termine par la chaîne _interstitial.
orders.displayName = "*video*"	Répertorie les commandes dont le nom à afficher contient la chaîne video.
displayName:"video"	Répertorie les commandes dont le nom à afficher contient la chaîne video (syntaxe alternative)

Remarque :Le filtre doit être encodé au format URL pour les requêtes GET. Par exemple: Chaîne de filtre : orders.updateTime > "2024-01-01T00:00:00-5:00" encodé au format URL : orders.updateTime%20%3E%20%222024-01-01T00:00:00-5:00%22. Cette opération est gérée automatiquement par les bibliothèques clientes.

Littéraux

Une valeur littérale simple (par exemple, 42, Hugo) est une valeur à faire correspondre. Les littéraux qui apparaissent seuls sont mis en correspondance floue avec tous les champs compatibles d'une ressource. Les ressources indiquent les champs pris en compte pour la mise en correspondance dans la méthode list. Cette fonctionnalité est comparable à la recherche universelle dans l'interface utilisateur d'Ad Manager, mais elle est limitée à un seul type de ressource.

Les littéraux de chaîne contenant des espaces doivent être placés entre guillemets doubles (par exemple : "Foo bar"). Les guillemets simples ne peuvent pas être utilisés pour encapsuler des littéraux de chaîne.

Opérateurs logiques

L'API Ad Manager est compatible avec les opérateurs binaires AND et OR.

Attention :Ces opérateurs sont sensibles à la casse. Les littéraux and et or sont traités comme des littéraux.

Opérateur	Exemple	Signification
AND	a AND b	"True" si a et b sont "True".
OR	a OR b OR c	"True" si l'un des éléments a, b ou c est défini sur "True".

Remarque :Pour correspondre aux schémas de langage courants, l'opérateur OR a une priorité plus élevée que AND, contrairement à ce que l'on trouve dans la plupart des langages de programmation. L'expression a AND b OR c renvoie a AND (b OR c). Dans la mesure du possible, utilisez des parenthèses explicites pour éviter toute confusion.

Opérateurs de négation

L'API Ad Manager fournit les opérateurs unaires NOT et -. Ces deux éléments peuvent être utilisés de manière interchangeable.

Opérateur	Exemple	Signification
NOT	NOT a	"True" si a n'est pas "true".
-	-a	"True" si a n'est pas "true".

Opérateurs de comparaison

L'API Ad Manager accepte les opérateurs de comparaison binaires =, !=, <, >, <= et >= pour les champs de chaîne, numérique, code temporel et durée.

Opérateur	Exemple	Signification
=	a = true	"True" si a est vrai.
!=	a != 42	"True", sauf si a est égal à 42.
<	a < 42	"True" si a est une valeur numérique inférieure à 42.
>	a > "foo"	"True" si a est ordonné lexicalement après "foo".
<=	a <= "foo"	"True" si a est "foo" ou lexicalement avant.
>=	a >= 42	"True" si a est une valeur numérique de 42 ou plus.

Remarque :Contrairement à la plupart des langages de programmation, les noms de champ doivent apparaître à gauche d'un opérateur de comparaison. Le côté droit n'accepte que les littéraux et les opérateurs logiques.

Étant donné que les filtres sont acceptés en tant que chaînes de requête, une conversion de type a lieu pour traduire la chaîne en valeur fortement typée appropriée:

• Les chaînes doivent être placées entre guillemets doubles. Exemple : "Foo bar"
• Les énumérations s'attendent à la représentation sous forme de chaîne de l'énumération (sensible à la casse).
• Les valeurs booléennes requièrent des valeurs littérales true et false.
• Les nombres s'attendent aux représentations standards des entiers ou des valeurs à virgule flottante. Pour les nombres à virgule flottante, les exposants sont acceptés. Exemple : 2.997e9
• Les durées nécessitent une représentation numérique suivie d'un suffixe s (pour les secondes). Exemples: "20s", "1.2s".
• Les horodatages s'attendent à une chaîne au format RFC-3339. Exemple : "2012-04-21T11:30:00-04:00". Les décalages UTC sont acceptés.

Attention :Les identifiants true, false et null n'ont une signification intrinsèque que lorsqu'ils sont utilisés dans le contexte d'une référence de champ typée.

Caractères génériques

Lorsque vous comparez des chaînes pour déterminer si elles sont égales, l'API Ad Manager accepte les caractères génériques à l'aide du caractère *.

Exemple	Signification
a = "*.foo"	"True" si a se termine par ".foo".

Opérateur de parcours

L'API Ad Manager est compatible avec l'opérateur ., qui indique la traversée d'un message, d'une carte ou d'une struct.

Exemple	Signification
a.b = true	"True" si a comporte un champ b booléen défini sur "true".
a.b > 42	"True" si a possède un champ b numérique supérieur à 42.
a.b.c = "foo"	"True" si a.b possède un champ c de chaîne "foo".

La traversée est écrite à l'aide des noms de champ de la ressource. Les services individuels peuvent spécifier un sous-ensemble de champs compatibles avec la traversée.

Important :L'opérateur . ne peut pas être utilisé pour parcourir un champ ou une liste répétés, sauf pour une utilisation spécifique avec l'opérateur :.

A un opérateur

L'API Ad Manager accepte l'opérateur :, qui signifie "contient". Il peut être utilisé avec des collections (champs ou cartes répétés), des messages et des chaînes, et se comporte légèrement différemment dans chaque cas.

Requête de champs de chaîne pour vérifier si la chaîne contient une sous-chaîne correspondante:

Exemple	Signification
r.displayName:"_250x250"	"True" si le champ de chaîne r.displayName contient la sous-chaîne _250x250.

Requête de champs répétés pour voir si la structure répétée contient un élément correspondant:

Exemple	Signification
r:42	"True" si r contient 42.
r.foo:42	"True" si r contient un élément e tel que e.foo = 42.

Important :Les filtres ne peuvent pas interroger un élément spécifique dans un champ répété pour une valeur. Par exemple, e.0.foo = 42 et e[0].foo = 42 ne sont pas des filtres valides.

Les cartes, les structs et les messages peuvent interroger la présence d'un champ dans la carte ou d'une valeur spécifique:

Exemple	Signification
m:foo	"True" si m contient la clé "foo".
m.foo:*	"True" si m contient la clé "foo".
m.foo:42	"True" si m.foo est égal à 42.

Lors de la traversée des messages, un champ n'est considéré comme présent que s'il a une valeur autre que la valeur par défaut.

Limites

Les services individuels peuvent spécifier une structure ou des limites supplémentaires pour les requêtes de filtre en plus de ce qui est défini ici.

Commande

La plupart des ressources acceptent l'ordre sur les méthodes List. Consultez la documentation de la méthode List pour connaître le comportement précis de la ressource et les champs compatibles avec l'ordre.

La syntaxe des champs orderBy est une liste de noms de champs séparés par une virgule. Exemple : "foo,bar".

L'ordre de tri par défaut est croissant. Pour spécifier l'ordre décroissant pour un champ, ajoutez un suffixe " desc". Exemple : "foo desc, bar".

Les espaces vides sont ignorés. Les valeurs "foo, bar desc", " foo , bar desc " et "foo,bar desc" sont toutes équivalentes.

Les sous-champs sont spécifiés avec l'opérateur de parcours. Par exemple: foo.bar ou address.street.