Les méthodes list récupèrent plusieurs ressources d'un type défini. Le paramètre de requête filter vous permet de définir les critères auxquels les ressources récupérées doivent répondre.
Structure des filtres
Les valeurs du paramètre filter sont des chaînes. Ces chaînes sont composées d'un ou plusieurs critères. Les critères sont associés par des opérateurs AND ou OR.
Un critère unique se présente sous la forme {field} {operator} {value}. Exemple :
entityStatus="ENTITY_STATUS_ACTIVE"
Les chaînes de filtre sont limitées à 500 caractères. Si votre chaîne est trop longue :
- Décomposez la logique en chaînes distinctes. Effectuez un appel
listavec chaque chaîne de filtre. Combinez les résultats pour obtenir une seule liste. - Supprimez les critères de la chaîne de filtre. Utilisez les critères supprimés pour filtrer les ressources récupérées localement.
Encapsulez les valeurs d'un critère entre guillemets.
Assurez-vous que vos chaînes de filtre sont encodées pour être utilisées dans une URL lorsque vous effectuez des appels d'API directement.
Pour en savoir plus sur la structure des chaînes de filtres, consultez la section Critères de jointure.
Critères de filtrage
Chaque méthode de liste accepte certains critères de filtrage. La description des critères est disponible dans le paramètre filter de la méthode. Les critères de filtrage sont souvent un sous-ensemble des champs de la ressource récupérée.
Chaque critère est compatible avec un ou plusieurs opérateurs :
| Opérateurs comparables | |
|---|---|
EQUALS (=)
|
Le champ est égal à la valeur indiquée. Exemple : |
LESS THAN OR EQUAL TO (<=)
|
La valeur du champ est inférieure ou égale à la valeur indiquée. Souvent utilisé pour filtrer par date ou date et heure. Exemple : |
GREATER THAN OR EQUAL TO (>=)
|
Le champ est supérieur ou égal à la valeur indiquée. Souvent utilisé pour filtrer par date ou date et heure. Exemple : |
HAS (:)
|
Le champ contient la valeur indiquée. Si le champ est une chaîne, il vérifie si la valeur indiquée est une sous-chaîne. Si le champ est un tableau, il vérifie si la valeur donnée y figure. Exemple : |
Si un critère ne spécifie pas d'opérateur, il n'accepte que EQUALS (=).
Un critère indiquera s'il nécessite un format spécial.
Critères de jointure
Combinez plusieurs critères pour limiter davantage la réponse de list.
Associez les critères de jointure avec les opérateurs logiques AND et OR. Chaque méthode list spécifie celles qui sont acceptées. Certaines méthodes n'acceptent que les filtres avec un seul critère.
Tenez compte de ces limites lorsque vous utilisez plusieurs critères :
| Limites et exemples | |
|---|---|
AND doit combiner des restrictions ou des groupes de restrictions qui filtrent différents champs ou qui filtrent le même champ différemment.
|
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 combiner les restrictions individuelles qui filtrent par le même champ.
|
(entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED") AND (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" OR lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT")
|
OR ne peut pas combiner deux groupes de restrictions. Utilisez plutôt plusieurs requêtes list avec différentes valeurs de filtre.
|
Les deux chaînes de filtre suivantes doivent être utilisées dans des requêtes distinctes et ne peuvent pas être combinées à l'aide de l'opérateur OR :
|
| Les parenthèses peuvent être implicites pour regrouper les restrictions, même si elles ne sont pas incluses. |
La chaîne de filtre 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").
|