Le paramètre de chaîne de requête filters
limite les données renvoyées dans un rapport de l'API AdSense Management. Lorsque vous utilisez le paramètre filters
, vous fournissez une dimension à filtrer, suivie de l'expression de filtre.
Les requêtes filtrées limitent les lignes incluses dans le résultat. Chaque ligne du résultat est testée par rapport au filtre: si le filtre correspond, la ligne est conservée. Si ce n'est pas le cas, elle est supprimée.
- Encodage d'URL: les bibliothèques clientes encodent automatiquement les opérateurs de filtrage. Toutefois, si vous envoyez des requêtes directement au protocole, vous devez encoder explicitement les opérateurs de filtrage, comme indiqué dans le tableau ci-dessous.
- Priorité de filtrage: le filtrage se produit avant que les dimensions soient agrégées, afin que les métriques renvoyées représentent le total des dimensions pertinentes.
Syntaxe du filtre
Un filtre unique utilise la forme suivante:
name operator expression
Dans cette syntaxe:
- name : nom de l'attribut à filtrer.
Par exemple,
AD_CLIENT_ID
filtre les données en fonction de l'identifiant du client publicitaire. - operator : définit le type de correspondance de filtre à utiliser.
- expression : indique les valeurs incluses dans les résultats.
Toutes les dimensions qui s'appliquent aux métriques faisant l'objet d'un rapport peuvent être utilisées comme filtres, à l'exception des dimensions liées à la date (DATE
, WEEK
et MONTH
). Pour filtrer par date, spécifiez plutôt la plage de dates du rapport.
Opérateurs de filtrage
Il existe deux opérateurs de filtrage. Les opérateurs doivent être encodés au format URL pour pouvoir être inclus dans les chaînes de requête d'URL.
Opérateur | Description | Format d'URL encodé | Exemple |
---|---|---|---|
== |
Correspondance exacte | %3D%3D |
Regroupe les métriques dont le nom de pays est Canada : filters=COUNTRY_NAME%3D%3DCanada |
=@ |
Contient une sous-chaîne | %3D@ |
Regroupe les métriques dont le nom de pays contient United (correspond par exemple aux États-Unis et au Royaume-Uni) :
filters=COUNTRY_NAME%3D@United |
Expressions de filtrage
Voici quelques règles importantes concernant les expressions de filtre:
- Caractères réservés aux URL : les caractères tels que
&
doivent être encodés pour les URL comme d'habitude. Les bibliothèques clientes s'en chargent pour vous. Vous n'avez donc à vous soucier de cet encodage que si vous effectuez des appels directs au protocole. - Caractères réservés : lorsqu'elles apparaissent dans une expression, la virgule et la barre oblique inverse doivent être précédées d'une barre oblique inverse.
- barre oblique inverse
\\
- virgule
\,
- barre oblique inverse
Remarque : Veillez à échapper les barres obliques inverses avant les virgules afin d'éviter un double échappement.
Combiner des filtres
Les filtres peuvent être combinés à l'aide des logiques booléennes OR
et AND
.
Logique OR
La logique OR
est définie à l'aide d'une virgule (,
) à l'intérieur de l'expression de filtre.
Exemple:(chacune doit être encodée au format URL)
Le code pays est (US OU UK):
COUNTRY_CODE==US,COUNTRY_CODE==UK
Logique AND
La logique AND
est obtenue en fournissant plusieurs paramètres de filtre, ce qui se traduit par la fourniture d'un tableau de filtres dans les bibliothèques clientes.
Exemple :
Le code pays est US ET le code produit est AFC:
filters=COUNTRY_CODE%3D%3DUS&filters=PRODUCT_CODE%3D%3DAFC
Combiner les logiques AND et OR
Il est possible de combiner les logiques ET et OU en une seule expression.
Remarque : Chaque filtre est évalué individuellement avant de combiner tous les filtres dans une expression logique AND.
Exemple :
Le code pays est (US OR UK) ET le code produit est AFC:
filters=COUNTRY_CODE%3D%3DUS,COUNTRY_CODE%3D%3DUK&filters=PRODUCT_CODE%3D%3DAFC