Filtrer les réponses de la liste

La plupart des services de l'API Display & Video 360 fournissent une méthode LIST pour la récupération groupée des ressources. Ces méthodes LIST acceptent généralement le filtrage des résultats via un paramètre de requête filter. Utilisez ce paramètre pour optimiser votre utilisation de l'API en récupérant uniquement ce dont vous avez besoin.

Ce guide explique comment utiliser efficacement le paramètre filter.

Structure du filtre

Une valeur de paramètre filter est une chaîne composée d'une ou de plusieurs restrictions pouvant être combinées avec des opérateurs AND ou OR et regroupées à l'aide de parenthèses.

Les restrictions sont au format {field} {operator} {value}. Exemple :

entityStatus="ENTITY_STATUS_ACTIVE"

La chaîne de filtre ne doit pas dépasser 500 caractères. Si la chaîne de filtre dépasse 500 caractères, effectuez l'une des opérations suivantes:

• Divisez la logique en plusieurs chaînes de filtre et récupérez les ressources à l'aide de requêtes LIST distinctes.
• Supprimez une partie de la logique de la chaîne de filtre et utilisez-la pour filtrer les ressources récupérées localement.

Placez les valeurs de restriction entre guillemets pour vous assurer que la logique est correctement appliquée.

Encodez en URL vos chaînes de filtre si vous effectuez des appels LIST directement sans utiliser de bibliothèque cliente.

Pour en savoir plus sur la mise en forme de vos requêtes, consultez la section Logique entre les restrictions.

Champs acceptant le filtrage

Les champs filtrables de chaque méthode LIST sont listés dans la description du paramètre filter de la méthode. Dans la plupart des cas, vous pouvez filtrer sur un sous-ensemble des champs standards d'une ressource. Dans de rares cas, il existe des champs supplémentaires que vous ne pouvez utiliser que pour le filtrage.

Chaque champ de la description du paramètre accepte au moins l'un des opérateurs comparables suivants:

Opérateurs comparables
EQUALS (=)	La valeur du champ de la ressource est égale à la valeur donnée. Exemple : entityStatus="ENTITY_STATUS_ACTIVE"
LESS THAN OR EQUAL TO (<=)	La valeur du champ de ressource est inférieure ou égale à la valeur donnée. Souvent utilisé pour comparer une date ou une date/heure. Exemple : updateTime<="2023-04-01T12:00:00Z"
GREATER THAN OR EQUAL TO (>=)	La valeur du champ de la ressource est supérieure ou égale à la valeur donnée. Souvent utilisé pour comparer une date ou une date/heure. Exemple : updateTime>="2023-03-01T12:00:00Z"
HAS (:)	La valeur du champ de ressource contient la valeur donnée. Si le champ de ressource est une chaîne, le système vérifie si la valeur donnée est une sous-chaîne existante. Si le champ de ressource est un tableau, il vérifiera si le tableau contient la valeur donnée. Exemple : lineItemIds:"1234"

Si aucun opérateur n'est spécifié pour le champ dans la description du paramètre, vous ne pouvez utiliser que l'opérateur EQUALS (=). Certains champs acceptent plusieurs opérateurs.

Certains champs filtrables, tels que ceux de dates et d'heures, nécessitent que la valeur comparable suive un format spécifique. Le format est spécifié à côté du champ dans la description du paramètre filter.

Logique entre les restrictions

Vous pouvez combiner plusieurs restrictions pour affiner ou étendre la réponse de votre requête LIST.

Vous pouvez généralement combiner plusieurs restrictions avec les opérateurs logiques AND et OR. Chaque méthode LIST spécifie les opérateurs compatibles. Certaines méthodes n'acceptent qu'une seule restriction dans le paramètre filter.

Tenez compte des restrictions suivantes lorsque vous créez des chaînes de filtre avec les opérateurs logiques AND ou OR:

Remarque :Les exemples suivants sont écrits à l'aide des restrictions de paramètres filter de la méthode advertisers.lineItems.list.

• AND doit être utilisé entre des restrictions ou des groupes de restrictions qui filtrent différents champs ou qui filtrent le même champ différemment. Voici quelques exemples :
  • updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE"
  • updateTime>="2023-03-01T12:00:00Z" AND updateTime<="2023-04-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED")
• OR doit être utilisé entre les restrictions individuelles qui filtrent selon le même champ. Exemple :
  • (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED") AND (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" OR lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT")

• Vous ne pouvez pas utiliser OR pour combiner deux groupes de restrictions. Utilisez plutôt plusieurs requêtes LIST avec des valeurs de filtre différentes. Par exemple, utilisez les requêtes LIST distinctes suivantes:

  • (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123")
  • (lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")

  N'utilisez pas l'opérateur OR pour les combiner:

  (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123") OR (lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")

• Les parenthèses peuvent être implicites si vous ne les utilisez pas pour regrouper des restrictions dans une chaîne de filtre. Par exemple, la chaîne de filtre suivante:

  updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT"

  est interprétée comme :

  updateTime>="2023-03-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT")