Filtrer les réponses de la liste

La plupart des services du Réseau Display et L'API Video 360 fournit 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 filter. Utilisez ce paramètre pour optimiser votre utilisation de l'API en n'utilisant pour récupérer ce dont vous avez besoin.

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

Structure des filtres

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

Les restrictions se présentent sous la forme {field} {operator} {value}. Exemple :

entityStatus="ENTITY_STATUS_ACTIVE"

La chaîne de filtre ne peut pas dépasser 500 caractères. Si votre 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 des requêtes LIST distinctes.
  • Supprimez une partie de la logique de la chaîne de filtre et utilisez-la pour filtrer le récupéré les ressources 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 à l'aide d'une bibliothèque cliente.

Pour en savoir plus sur le formatage, consultez la section Logique entre les restrictions. vos requêtes.

Champs acceptant le filtrage

Les champs filtrables de chaque méthode LIST sont répertoriés dans le fichier filter de la méthode. description du paramètre. Dans la plupart des cas, vous pouvez filtrer sur un sous-ensemble les champs standards. Dans de rares cas, vous pouvez utiliser des champs supplémentaires uniquement pour le filtrage.

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

Opérateurs comparables
EQUALS (=) La valeur du champ "Ressource" est égale à la valeur donnée.

Exemple : entityStatus="ENTITY_STATUS_ACTIVE"
LESS THAN OR EQUAL TO (<=) La valeur du champ "Ressource" est inférieure ou égale à la valeur donnée. Souvent utilisés lorsque vous comparez une date ou une date/heure.

Exemple : updateTime<="2023-04-01T12:00:00Z"
GREATER THAN OR EQUAL TO (>=) La valeur du champ de ressource est supérieure ou égale à la valeur donnée. Souvent utilisés lorsque vous comparez 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 "resource" est une chaîne, il vérifie si la valeur donnée est une sous-chaîne existante. Si le "resource" est un tableau, il vérifie si le tableau contient les valeurs .

Exemple : lineItemIds:"1234"

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

Certains champs filtrables, tels que ceux pour les dates et les heures, nécessitent l'attribut comparable pour suivre un format spécifique. Le format est spécifié à côté de le champ de la description du paramètre filter.

Logique entre les restrictions

Vous pouvez combiner plusieurs restrictions pour affiner ou étendre la réponse à partir de votre LIST.

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

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

  • AND doit être utilisé entre des restrictions, ou des groupes de restrictions, qui qui filtrent différents champs ou qui filtrent le même champ différemment. Voici Voici quelques exemples: <ph type="x-smartling-placeholder">
      </ph>
    • 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 . Voici un exemple: <ph type="x-smartling-placeholder">
      </ph>
    • (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. Utiliser plusieurs Requêtes LIST avec des valeurs de filtre différentes à la place. Par exemple, utilisez la méthode 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 un 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")