Structure d'une requête

Les requêtes sur des champs de ressource, de segment et de métrique 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 la rédiger à l'aide de sa grammaire. Une requête se compose de plusieurs clauses :

• SELECT
• FROM
• WHERE
• ORDER BY
• LIMIT
• PARAMETERS

Les clauses utilisent des noms de champ, des noms de ressources, des opérateurs, des conditions et des tris pour vous aider à sélectionner les données appropriées. Une fois ces éléments combinés en une seule requête, celle-ci peut être exécutée à l'aide de l'API Google Ads.

Clauses

ondemand_video 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 métriques, de champs de segment et de champs de ressource séparés par une virgule, renvoyant 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 ressources

  • campaign.id
  • campaign.name

• Champs de ressources

  • bidding_strategy.id
  • bidding_strategy.name

• Champs de segment

  • segments.device
  • segments.date

• Métriques

  • metrics.impressions
  • metrics.clicks

Certains champs ne sont pas autorisés dans la clause SELECT en raison des restrictions suivantes :

• Requêtes sur des champs qui ne peuvent pas être sélectionnés. L'attribut de métadonnées Selectable de ces champs sera marqué comme false.
• Sélectionner les attributs des champs répétés. L'attribut de métadonnées isRepeated de ces champs sera marqué comme true.
• 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 clause FROM.
• Vous avez sélectionné des segments ou des métriques qui ne sont pas compatibles entre eux. Pour en savoir plus, consultez la section sur la segmentation.

Vous trouverez des informations sur les conditions ci-dessus dans notre documentation de référence ou sur 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 par toutes les autres clauses d'une 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 aux méthodes Search ou SearchStream de GoogleAdsService. 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, des champs provenant des ressources attribuées peuvent également être disponibles. Ces ressources sont jointes de manière implicite à la ressource dans la clause FROM. Vous n'avez donc qu'à ajouter leurs attributs à la clause SELECT pour renvoyer leurs valeurs. Toutes les ressources ne comportent pas de ressources attribuées. Dans l'exemple suivant, vous pouvez demander à la fois 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 sera inclus dans la réponse, même s'il n'a pas été 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, une ou plusieurs conditions peuvent être spécifiées en utilisant AND comme séparateur. 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 afficher des 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 généré 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, à 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, notez que segments.date est sélectionné. Comme il s'agit d'un segment de date principal, il nécessite une plage de dates finie composée de segments de date principaux dans la clause WHERE.

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Voici tous les segments qui remplissent la condition ci-dessus : 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'eux doit être utilisé dans la clause WHERE.

Lors du filtrage, vous devez savoir que votre opérateur est sensible à la casse. 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 affichés. Cela vous permet d'organiser les données par 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 vous ne spécifiez pas ASC ni DESC, le tri utilise ASC par défaut. 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 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 la même séquence que celle spécifiée dans la requête. Par exemple, dans cette requête sélectionnant des données de groupe d'annonces, les résultats sont triés par ordre croissant de nom de campagne, puis par nombre décroissant d'impressions, puis par nombre décroissant 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 permet de spécifier le nombre de résultats à afficher. Elle est utile si vous ne souhaitez obtenir qu'un récapitulatif.

Par exemple, LIMIT peut être utilisé pour 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éta-paramètres pour la requête. Ces paramètres peuvent avoir un impact sur les types de lignes renvoyés.

Les méta-paramètres suivants sont acceptés :

include_drafts

Définissez include_drafts sur true pour autoriser le renvoi des 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 empêcher le renvoi du 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.

SELECT
  campaign.name,
  customer.id
FROM campaign

SELECT
  campaign.name,
  customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true

SELECT
  campaign.name,
  campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true

Règles supplémentaires concernant la langue

En plus des exemples pour chaque clause, le langage de requête Google Ads présente les comportements suivants qui peuvent être utilisés :

• Il n'est pas nécessaire que le champ de ressource principal figure dans la clause SELECT d'une requête. Par exemple, vous pouvez choisir de 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 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 associés :

  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'