Structure d'une requête

Conseil : Utilisez le Générateur de requêtes interactif pour créer et valider vos requêtes en langage de requête Google Ads.

Les requêtes sur des champs de ressource, de segment et de métrique peuvent être envoyées à la méthode GoogleAdsService Search ou SearchStream. Pour construire une requête dans le langage de requête Google Ads, utilisez la grammaire du langage. Pour obtenir une présentation générale du langage de requête Google Ads, consultez la présentation du langage de requête Google Ads. Une requête est composée d'un certain nombre de 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 appropriées. Une fois combinées en une seule requête, vous pouvez envoyer la requête à l'API Google Ads.

Point clé : GoogleAdsFieldService fournit un catalogue pour les clients du langage de requête Google Ads avec des métadonnées sur tous les champs de ressources, les champs de segments et les métriques, leurs relations les uns avec les autres et leur disponibilité dans chaque clause. Étant donné que l'ensemble des ressources, champs, segments et métriques interrogeables varie d'une version majeure de l'API à l'autre, interrogez GoogleAdsFieldService au niveau du point de terminaison de la version de l'API que vous ciblez. Pour en savoir plus, consultez la documentation sur GoogleAdsField et les différences spécifiques aux versions.

Clauses

Les sections suivantes décrivent l'objectif et la syntaxe de chaque clause du langage de requête Google Ads.

SELECT

La clause SELECT spécifie un ensemble de champs à récupérer dans la requête. SELECT accepte une liste de champs de ressources, de champs de segments et de métriques séparés par une virgule, et renvoie les valeurs dans la réponse. La clause SELECT est obligatoire dans une requête.

L'exemple de requête suivant 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 ressources principaux
  • campaign.id
  • campaign.name
• Champs de ressources attribués
  • bidding_strategy.id
  • bidding_strategy.name
• Champs de segment
  • segments.device
  • segments.date
• Métriques
  • metrics.impressions
  • metrics.clicks

Remarque : Certains champs ne peuvent pas être sélectionnés dans la clause SELECT en raison des restrictions suivantes :

• Interrogation de champs qui ne sont pas sélectionnables. L'attribut de métadonnées selectable de ces champs est marqué comme false.
• Sélectionner des attributs de champs répétés. L'attribut de métadonnées is_repeated de ces champs est marqué comme true.
• Sélection de 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, et seul un sous-ensemble de l'ensemble des métriques et des segments est disponible pour la ressource dans la clause FROM.
• Sélection de segments ou de métriques incompatibles entre eux. Pour en savoir plus, consultez Segmentation.

Vous trouverez des informations sur les conditions précédentes dans notre documentation de référence ou sur GoogleAdsFieldService.

FROM

La clause FROM spécifie la ressource principale à renvoyer. La ressource de la clause FROM définit les champs pouvant ê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 une requête adressée à la méthode GoogleAdsService Search ou SearchStream. Toutefois, la clause FROM 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, les champs des ressources attribuées peuvent également être disponibles. Ces ressources sont implicitement jointes à la ressource dans la clause FROM. Il vous suffit donc d'ajouter leurs attributs à la clause SELECT pour renvoyer leurs valeurs. Toutes les ressources ne sont pas associées à des ressources. Dans l'exemple suivant, vous pouvez demander l'ID du groupe d'annonces et l'ID de la campagne à partir des 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 est 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 ressources attribuées lorsqu'au moins un champ est sélectionné. Par exemple, campaign.resource_name est inclus dans la réponse à la requête suivante :

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Important : Si la ressource de la clause FROM liste une autre ressource en tant que segment, la sélection d'un attribut de cette ressource agit comme un segment.

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, spécifiez une ou plusieurs conditions séparées par AND. Les conditions suivent généralement le modèle field_name Operator value (ou utilisent BETWEEN value AND value, IS NULL ou IS NOT NULL). La clause WHERE est facultative dans une requête.

L'exemple suivant utilise 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. Cet exemple demande 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 également figurer dans la clause SELECT, à l'exception des segments de date suivants, appelés segments de date principaux :

• segments.date
• segments.week
• segments.month
• segments.quarter
• segments.year

Dans la requête suivante, segments.date est sélectionné. Comme ce segment est un segment de date principal, vous devez fournir une plage de dates finie dans la clause WHERE composée de segments de date principaux :

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 précédente 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.

Pour en savoir plus sur le filtrage par date, consultez Plages de dates.

Important : Le séparateur AND ne peut être utilisé qu'entre des conditions d'opérateur (WHERE segments.device != 'DESKTOP' AND segments.device != 'MOBILE'), et non au sein d'une même condition d'opérateur (WHERE segments.device != 'DESKTOP' AND 'MOBILE', par exemple).

Lorsque vous filtrez, tenez compte de la sensibilité à la casse de votre 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 sont renvoyés. Cela vous permet d'organiser les données par ordre croissant ou décroissant en fonction d'un nom de champ. Chaque ordre est spécifié sous la forme d'un field_name suivi de ASC ou DESC. Si ni ASC ni DESC n'est spécifié, l'ordre par défaut est ASC. La clause ORDER BY est facultative dans une requête.

La requête suivante classe les campagnes renvoyées par nombre de clics, du plus élevé au plus faible :

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 s'effectue dans l'ordre spécifié dans la requête. Par exemple, dans cette requête sélectionnant les données d'un groupe d'annonces, les résultats sont triés par ordre croissant selon le nom de la campagne, puis par ordre décroissant selon le nombre d'impressions, puis par ordre décroissant selon le 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. Cela est utile si vous n'avez besoin que d'un sous-ensemble de résultats.

Par exemple, LIMIT peut 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

Important : LIMIT vous permet de tronquer les résultats. Pour récupérer des ensembles de résultats volumineux sans les tronquer, utilisez GoogleAdsService.SearchStream pour diffuser des lignes ou paginer avec GoogleAdsService.Search.

PARAMETERS

La clause PARAMETERS vous permet de spécifier des métaparamètres pour la requête. Ces paramètres peuvent avoir un impact sur les types de lignes renvoyés.

Les métaparamètres suivants sont acceptés :

include_drafts

Définissez include_drafts sur true pour renvoyer les entités brouillons. La valeur par défaut est false.

Par exemple, la requête suivante récupère les campagnes brouillons ainsi que 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 omettre le nom de ressource de chaque type de ressource dans la réponse, sauf s'il est explicitement demandé dans la clause SELECT. La valeur par défaut est false.

Remarque : Si vous prévoyez d'utiliser l'un des objets renvoyés pour des opérations de mise à jour ou de suppression, nous vous recommandons de définir cette option sur false, car les ressources sans nom de ressource ne peuvent pas être utilisées dans les opérations de mutation. Si vous définissez cette option sur true, veillez à demander explicitement les noms de la ressource principale et de toutes les ressources attribuées que vous récupérez à l'aide de la requête.

Requête	Ressources renvoyées
SELECT campaign.name, customer.id FROM campaign	campaign.resource_name customer.resource_name La valeur par défaut de omit_unselected_resource_names est false. Tous les champs resource_name sont donc renvoyés.
SELECT campaign.name, customer.id FROM campaign PARAMETERS omit_unselected_resource_names = true	Aucun omit_unselected_resource_names est spécifié en tant que true, et ni campaign.resource_name ni customer.resource_name ne font partie de la clause SELECT.
SELECT campaign.name, campaign.resource_name FROM campaign PARAMETERS omit_unselected_resource_names = true	campaign.resource_name omit_unselected_resource_names est spécifié en tant que true, et campaign.resource_name est demandé dans la clause SELECT.

Règles supplémentaires concernant la langue

En plus des exemples pour chaque clause, le langage de requête Google Ads accepte les comportements suivants :

• Le champ de ressource principal n'est pas obligatoire dans la clause SELECT d'une requête. Par exemple, vous pouvez utiliser un ou plusieurs champs de ressource principaux pour filtrer les données sans les sélectionner :

  SELECT campaign.id
  FROM ad_group
  WHERE ad_group.status = 'PAUSED'
  

• Les métriques peuvent être sélectionnées exclusivement 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 aucun champ de ressource ni métrique :

  SELECT segments.device FROM campaign
  

• Le champ resource_name (campaign.resource_name, par exemple) peut être utilisé pour filtrer ou ordonner les données :

  SELECT
    campaign.id,
    campaign.name
  FROM campaign
  WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'