Langage de requête Google Ads

Terminologie clé

Ressource

Entité dans Google Ads, telle que campaign ou ad_group.

Segment

Dimension utilisée pour regrouper des données, telle que segments.date ou segments.device. Lorsque des segments sont inclus dans la clause SELECT avec des métriques, les métriques sont divisées par segment.

Métrique

Mesure des performances, telle que metrics.impressions ou metrics.clicks.

Ressource attribuée

Ressource jointe implicitement à la ressource principale dans la clause FROM, ce qui vous permet de sélectionner ses attributs ainsi que les attributs de la ressource principale.

Requête pour des informations sur une ressource ou des métadonnées

Le langage de requête Google Ads peut interroger l'API Google Ads pour les types d'informations suivants :

• Ressources et leurs attributs, segments et métriques associés à l'aide de GoogleAdsService Search ou SearchStream: le résultat d'une requête GoogleAdsService est une liste d'instances GoogleAdsRow, chaque GoogleAdsRow représentant une ressource.

  Si des attributs ou des métriques sont demandés, la ligne inclut également ces champs. Si des segments sont demandés, la réponse affiche également une ligne supplémentaire pour chaque tuple segment-ressource.

• Métadonnées sur les champs et ressources disponibles dans GoogleAdsFieldService: Ce service fournit un catalogue de champs interrogeables avec des informations spécifiques sur leur compatibilité et leur type.

  Le résultat d'une GoogleAdsFieldService requête est une liste d'instances GoogleAdsField, chaque GoogleAdsField contenant des détails sur le champ demandé.

Pour en savoir plus sur la structure des requêtes, consultez Structure des requêtes et Grammaire du langage de requête Google Ads.

Requête pour des attributs de ressource

Voici un exemple de requête de base pour les attributs de la ressource de campagne qui illustre comment renvoyer l'ID, le nom et l'état de la campagne :

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign
ORDER BY campaign.id

Cette requête est triée par ID de campagne. Chaque GoogleAdsRow résultant représente un objet campaign rempli avec les champs sélectionnés, y compris le resource_name de la campagne.

Pour savoir quels autres champs sont disponibles pour les requêtes de campagne, consultez la Campaign documentation de référence.

Requête pour des métriques

En plus des attributs sélectionnés pour une ressource donnée, vous pouvez également interroger les métriques associées :

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
ORDER BY campaign.id

Cette requête filtre uniquement les campagnes dont l'état est PAUSED et qui ont enregistré plus de 1 000 impressions, tout en les triant par ID de campagne. Chaque GoogleAdsRow résultant comporte un champ metrics rempli avec les métriques sélectionnées.

Pour obtenir la liste des métriques interrogeables, consultez la Metrics documentation.

Requête pour des segments

En plus des attributs sélectionnés pour une ressource donnée, vous pouvez également interroger les segments associés :

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions,
  segments.date,
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
  AND segments.date during LAST_30_DAYS
ORDER BY campaign.id

Comme pour les requêtes de métriques, cette requête filtre uniquement les campagnes dont l'état est PAUSED et qui ont enregistré plus de 1 000 impressions. Toutefois, cette requête segmente les données par date. Chaque GoogleAdsRow résultant représente un tuple d'une campagne et de la date Segment. La segmentation divise les métriques sélectionnées, en les regroupant par segment dans la clause SELECT.

Pour obtenir la liste des segments interrogeables, consultez la Segments documentation.

Requête pour les attributs d'une ressource associée

Dans une requête pour une ressource donnée, vous pouvez peut-être effectuer une jointure avec d'autres ressources associées, si elles sont disponibles. Ces ressources associées sont appelées "ressources attribuées". Vous pouvez effectuer une jointure avec des ressources attribuées de manière implicite en sélectionnant un attribut dans votre requête.

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  bidding_strategy.name
FROM campaign
ORDER BY campaign.id

Cette requête sélectionne non seulement les attributs de la campagne, mais extrait également les attributs associés de chaque campagne sélectionnée. Chaque GoogleAdsRow résultant représente un objet campaign rempli avec les attributs de campagne sélectionnés, ainsi que l'attribut de stratégie d'enchères sélectionné bidding_strategy.name.

Pour savoir quelles ressources attribuées sont disponibles pour les requêtes de campagne, consultez la documentation de référence sur Campaign.

Bonnes pratiques

• Ne sélectionnez que les champs dont vous avez besoin pour éviter les longs délais de réponse et les délais d'attente.
• Utilisez LIMIT lors du développement et des tests pour éviter de traiter des ensembles de résultats volumineux.
• Appliquez des filtres dans la clause WHERE pour réduire la taille du transfert de données et de la réponse.
• Utilisez GoogleAdsFieldService pour vérifier la compatibilité des champs et les types de données avant de créer des requêtes complexes.
• N'oubliez pas que certains champs, en particulier ceux qui impliquent de grandes quantités de données ou des calculs complexes, peuvent augmenter le coût des requêtes.

Effectuer une mutation en fonction des résultats de la requête

Lorsque vous interrogez une ressource donnée, vous pouvez immédiatement prendre les résultats renvoyés en tant qu'objets, les modifier et les renvoyer à la méthode de mutation dans le service de cette ressource. Voici un exemple de workflow : 1. Exécutez une requête pour toutes les campagnes actuellement PAUSED et dont les impressions sont supérieures à 1 000. 1. Obtenez l'objet Campaign à partir du champ campaign de chaque GoogleAdsRow dans la réponse. 1. Modifiez l'état de chaque campagne de PAUSED à ENABLED. 1. Appelez CampaignService.MutateCampaigns avec les campagnes modifiées pour les mettre à jour.

Métadonnées du champ

Les requêtes envoyées à GoogleAdsFieldService sont destinées à récupérer les métadonnées des champs. Ces informations peuvent être utilisées pour comprendre comment les champs peuvent être utilisés ensemble dans une requête. Étant donné que les données sont disponibles à partir de l'API et qu'elles fournissent les métadonnées nécessaires pour valider ou créer une requête, les développeurs peuvent le faire par programmation. Voici une requête typique pour les métadonnées :

SELECT
  name,
  category,
  selectable,
  filterable,
  sortable,
  selectable_with,
  data_type,
  is_repeated
WHERE name = "<INSERT_RESOURCE_OR_FIELD>"

Vous pouvez remplacer <INSERT_RESOURCE_OR_FIELD> dans cette requête par une ressource (telle que customer ou campaign) ou un champ (tel que campaign.id, metrics.impressions, ou ad_group.id).