Les requêtes sur les champs de ressources, de segments et de métriques peuvent être envoyées aux méthodes GoogleAdsService
Search ou SearchStream. Pour créer une requête dans le langage de requête Google Ads, vous devez utiliser la grammaire du langage. Une requête est composée de plusieurs clauses:
SELECT
FROM
WHERE
ORDER BY
LIMIT
PARAMETERS
Les clauses utilisent des noms de champs, des noms de ressources, des opérateurs, des conditions et des classements pour vous aider à sélectionner les données correctes. Une fois combinée en une seule requête, une demande peut être effectuée à l'aide de l'API Google Ads.
Clauses
Vidéo: Compatibilité des champs GAQL
SELECT
La clause SELECT
spécifie un ensemble de champs à extraire dans la requête.
SELECT
utilise une liste de champs de ressources, de champs de segment et de métriques séparés par une virgule, puis renvoie les valeurs dans la réponse. La clause SELECT
est obligatoire dans une requête.
L'exemple de requête ci-dessous montre comment sélectionner des attributs pour une ressource donnée:
SELECT
campaign.id,
campaign.name
FROM campaign
Vous pouvez demander différents types de champs dans une même requête, par exemple:
SELECT
campaign.id,
campaign.name,
bidding_strategy.id,
bidding_strategy.name,
segments.device,
segments.date,
metrics.impressions,
metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
Champs de ressource
campaign.id
campaign.name
Champs de ressource
bidding_strategy.id
bidding_strategy.name
Champs de segment
segments.device
segments.date
Métriques
metrics.impressions
metrics.clicks
Certains champs peuvent ne pas être autorisés dans la clause SELECT
en raison des restrictions suivantes:
- Interrogation des champs non sélectionnables L'attribut de métadonnées
Selectable
de ces champs sera marqué commefalse
. - Sélection des attributs de champs répétés. L'attribut de métadonnées
isRepeated
de ces champs sera marqué commetrue
. - Sélectionner des champs qui ne sont pas disponibles pour la ressource donnée dans la clause
FROM
Les attributs de certaines ressources ne peuvent pas être sélectionnés ensemble. De plus, seul un sous-ensemble de toutes les métriques et de tous les segments sera disponible pour la ressource dans la clauseFROM
. - Sélectionner des segments ou des métriques non compatibles entre eux Pour en savoir plus, consultez la section Segmentation.
Vous trouverez des informations concernant les conditions ci-dessus dans notre documentation de référence ou sur la page GoogleAdsFieldService
.
FROM
La clause FROM
spécifie la ressource principale qui sera renvoyée. La ressource de la clause FROM
définit les champs qui peuvent être utilisés dans toutes les autres clauses de la requête donnée. Une seule ressource peut être spécifiée dans la clause FROM
. La clause FROM
est obligatoire dans les requêtes envoyées aux méthodes GoogleAdsService
Search ou SearchStream, mais ne doit pas être spécifiée lorsque vous utilisez GoogleAdsFieldService
.
Bien qu'une seule ressource puisse exister dans la clause FROM
pour une requête donnée, des champs des ressources attribuées peuvent également être disponibles. Ces ressources sont implicitement associées à la ressource dans la clause FROM
. Il vous suffit donc d'ajouter leurs attributs à la clause SELECT
pour renvoyer leurs valeurs. Les ressources ne sont pas toutes attribuées à des ressources. Dans l'exemple suivant, vous pouvez demander à la fois l'ID du groupe d'annonces et l'ID de la campagne aux groupes d'annonces:
SELECT
campaign.id,
ad_group.id
FROM ad_group
Le champ resource_name
de la ressource principale est toujours renvoyé.
Dans l'exemple suivant, ad_group.resource_name
sera inclus dans la réponse, même s'il n'est pas explicitement sélectionné dans la requête:
SELECT ad_group.id
FROM ad_group
Il en va de même pour les autres ressources lorsqu'au moins un champ est sélectionné.
Par exemple, campaign.resource_name
sera inclus dans la réponse à la requête suivante :
SELECT
campaign.id,
ad_group.id
FROM ad_group
WHERE
La clause WHERE
spécifie les conditions à appliquer lors du filtrage des données pour la requête. Lorsque vous utilisez la clause WHERE
, vous pouvez spécifier une ou plusieurs conditions à l'aide de AND
pour les séparer. Chaque condition doit respecter le format field_name Operator value
. La clause WHERE
est facultative dans une requête.
Voici un exemple d'utilisation de WHERE
pour renvoyer les métriques d'une période donnée:
SELECT
campaign.id,
campaign.name,
metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
Vous pouvez combiner plusieurs conditions pour filtrer les données. Dans cet exemple, la requête porte sur le nombre de clics pour toutes les campagnes ayant enregistré des impressions sur mobile au cours des 30 derniers jours.
SELECT
campaign.id,
campaign.name,
segments.device,
metrics.clicks
FROM campaign
WHERE metrics.impressions > 0
AND segments.device = MOBILE
AND segments.date DURING LAST_30_DAYS
Les segments de la clause WHERE
doivent figurer dans la clause SELECT
, les segments de date suivants, appelés segments de dates principaux, étant des exceptions:
segments.date
segments.week
segments.month
segments.quarter
segments.year
Dans la requête suivante, notez que segments.date
est sélectionné.
Comme ce segment est un segment de date principal, il nécessite de fournir une plage de dates finie composée de segments de dates principaux dans la clause WHERE
.
SELECT
campaign.id,
campaign.name,
segments.date,
metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
Tous les segments qui remplissent la condition ci-dessus sont: segments.date, segments.week, segments.month, segments.quarter et segments.year. Si l'un de ces segments est sélectionné, au moins l'un d'entre eux doit être utilisé dans la clause WHERE
.
Lors du filtrage, il est important de garder à l'esprit la sensibilité à la casse de l'opérateur. Pour en savoir plus, consultez Sensibilité à la casse.
Pour obtenir la liste complète des opérateurs, consultez la grammaire du langage.
ORDER BY
La clause ORDER BY
spécifie l'ordre dans lequel les résultats doivent être renvoyés. Cela vous permet d'organiser les données dans l'ordre croissant ou décroissant en fonction d'un nom de champ. Chaque tri est spécifié en tant que field_name
suivi de ASC
ou DESC
. Si ni ASC
, ni DESC
n'est spécifié, la valeur par défaut est ASC
. La clause ORDER BY
est facultative dans une requête.
La requête suivante trie les campagnes renvoyées par nombre de clics, du plus élevé au moins élevé:
SELECT
campaign.name,
metrics.clicks
FROM campaign
ORDER BY metrics.clicks DESC
Vous pouvez spécifier plusieurs champs dans la clause ORDER BY
à l'aide d'une liste d'éléments séparés par une virgule. Le tri aura lieu dans la même séquence que celle spécifiée dans la requête.
Par exemple, dans cette requête de sélection des données de groupes d'annonces, les résultats sont triés par ordre croissant par nom de campagne, puis par ordre décroissant du nombre d'impressions, puis par ordre décroissant du nombre de clics:
SELECT
campaign.name,
ad_group.name,
metrics.impressions,
metrics.clicks
FROM ad_group
ORDER BY
campaign.name,
metrics.impressions DESC,
metrics.clicks DESC
LIMIT
La clause LIMIT
vous permet de spécifier le nombre de résultats à renvoyer.
Ceci est utile si seul un résumé vous intéresse.
Par exemple, LIMIT
permet de limiter le nombre total de résultats pour la requête suivante:
SELECT
campaign.name,
ad_group.name,
segments.device,
metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50
PARAMÈTRES
La clause PARAMETERS
vous permet de spécifier des métaparamètres pour la requête.
Ces paramètres peuvent avoir une incidence sur les types de lignes renvoyées.
Actuellement, les métaparamètres suivants sont acceptés:
include_drafts
Définissez include_drafts
sur true
pour permettre le renvoi d'entités de brouillon.
La valeur par défaut est false
.
Par exemple, la requête suivante récupère les campagnes brouillons avec les campagnes standards:
SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true
omit_unselected_resource_names
Définissez omit_unselected_resource_names
sur true
pour éviter que le nom de ressource de chaque type de ressource présent dans la réponse ne soit renvoyé, sauf indication contraire explicite dans la clause SELECT
. La valeur par défaut est false
.
Exemples d'omettre_unselected_resource_names | |
---|---|
SELECT campaign.name, customer.id FROM campaign |
Returned resources:campaign.resource_name
omit_unselected_resource_names est défini par défaut sur false . Tous les champs resource_name sont donc renvoyés.
|
SELECT campaign.name, customer.id FROM campaign PARAMETERS omit_unselected_resource_names = true |
Returned resources: Aucun. omit_unselected_resource_names est spécifié, car true , et campaign.resource_name et customer.resource_name ne font pas partie de la clause SELECT .
|
SELECT campaign.name, campaign.resource_name FROM campaign PARAMETERS omit_unselected_resource_names = true |
Returned resource:campaign.resource_name
omit_unselected_resource_names est spécifié en tant que true et campaign.resource_name demandés dans la clause SELECT .
|
Règles supplémentaires concernant les langues
Outre les exemples pour chaque clause, le langage de requête Google Ads présente les comportements suivants:
Il n'est pas nécessaire que le champ de ressource principal se trouve dans la clause
SELECT
d'une requête. Par exemple, vous pouvez n'utiliser qu'un ou plusieurs champs de ressources principaux pour filtrer les données:SELECT campaign.id FROM ad_group WHERE ad_group.status = PAUSED
Les métriques peuvent être exclusivement sélectionnées pour une ressource donnée. Aucun autre champ de la ressource n'est requis dans la requête:
SELECT metrics.impressions, metrics.clicks, metrics.cost_micros FROM campaign
Les champs de segmentation peuvent être sélectionnés sans champ de ressource ni métrique associé:
SELECT segments.device FROM campaign
Le champ
resource_name
(campaign.resource_name
, par exemple) peut être utilisé pour filtrer ou trier les données:SELECT campaign.id, campaign.name FROM campaign WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'