Filtres

L'API Ad Manager accepte le filtrage en fonction 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"	Liste 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)

Conseil :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"
Encodage en 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 (exemples: 42, Hugo) est une valeur à mettre en correspondance. Les littéraux qui apparaissent seuls présentent une correspondance partielle 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 globale 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 accepte 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'une des valeurs a, b ou c est "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 é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"	Vrai si a est "foo" ou si l'élément est lexiquement 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 des littéraux et des 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 attendent la représentation sous forme de chaîne de l'énumération (sensible à la casse).
• Les booléens attendent 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 à un champ saisi.

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 accepte 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 booléen b qui est vrai.
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. Chaque service peut spécifier un sous-ensemble de champs compatibles avec le balayage.

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 :.

Contient un opérateur

L'API Ad Manager accepte l'opérateur :, qui signifie "contient". Il est utilisable 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 des champs de chaîne pour voir 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 sur les 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 obtenir 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 défini sur 42.

Lors du balayage de messages, un champ n'est considéré comme présent que s'il possède une valeur autre que celle 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

L'API Ad Manager prend en charge l'ordre dans les méthodes List. 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 balayage. Par exemple : foo.bar ou address.street.