Filtres

L'API REST Ad Manager accepte le filtrage des méthodes List. La syntaxe de la chaîne de filtre est officiellement définie 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"	Répertorie 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 contient les États-Unis (ID de la cible géographique : 2480)
lineItems.displayName = "*_interstitial"	Liste les éléments de campagne dont le nom à afficher se termine par la chaîne _interstitial
orders.displayName = "*video*"	Liste les commandes dont le nom à afficher contient la chaîne video
displayName:"video"	Liste 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"
URL encodée: 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 apparaissant seuls correspondent à une correspondance partielle avec tous les champs compatibles d'une ressource. Les ressources indiquent les champs pouvant être mis en correspondance avec 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 entourés de guillemets doubles (exemple: "Foo bar"). Les littéraux de chaîne ne peuvent pas être utilisés pour encapsuler des littéraux de chaîne.

Opérateurs logiques

L'API REST 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 vrais.
OR	a OR b OR c	"True" si a, b ou c sont vrais.

Remarque :Pour correspondre aux modèles de discours courants, l'opérateur OR a une priorité plus élevée que AND, contrairement à la plupart des langages de programmation. L'expression a AND b OR c est évaluée comme 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 REST Ad Manager fournit les opérateurs unaires NOT et -. Ils peuvent être utilisés de manière interchangeable.

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

Opérateurs de comparaison

L'API REST Ad Manager est compatible avec les opérateurs de comparaison binaire =, !=, <, >, <= et >= pour les champs de type chaîne, numérique, horodatage et durée.

Opérateur	Exemple	Signification
=	a = true	"True" si a est "true".
!=	a != 42	Vrai, 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 trié lexiquement après "foo".
<=	a <= "foo"	"True" si a est "foo" ou lexiquement avant lui.
>=	a >= 42	"True" si a est une valeur numérique supérieure ou égale à 42.

Remarque :Contrairement à la plupart des langages de programmation, les noms de champs 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, la conversion de type a lieu pour traduire la chaîne en la valeur fortement typée appropriée:

• Les chaînes attendent des guillemets doubles. Exemple : "Foo bar"
• Les énumérations attendent la représentation de chaîne de l'énumération (sensible à la casse).
• Les valeurs booléennes sont attendues pour les valeurs littérales true et false.
• Les nombres s'attendent à des représentations entières ou à virgule flottante standards. 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 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 de 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 l'égalité, l'API REST Ad Manager accepte les caractères génériques avec le caractère *.

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

Opérateur de balayage

L'API REST Ad Manager est compatible avec l'opérateur ., qui indique le balayage dans un message, un mappage ou un struct.

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

Le balayage est écrit à l'aide des noms de champs 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 dans le cas d'une utilisation spécifique avec l'opérateur :.

Dispose d'un opérateur

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

Une requête de champs de chaîne permet de 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.

Les champs répétés effectuent une requête pour vérifier 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 d'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 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 REST d'Ad Manager permet de trier les données à l'aide des méthodes List. La syntaxe des champs orderBy consiste en une liste de noms de champs séparés par une virgule. Exemple : "foo,bar".

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

Les espaces redondants dans la syntaxe 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 à l'aide de l'opérateur de balayage. Exemples: foo.bar ou address.street.