Langage de requête Google Ads

Le langage de requête Google Ads permet d'interroger l'API Google Ads

Les 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.
Les métadonnées sur les champs et ressources disponibles dans
GoogleAdsFieldService

Ce service fournit un catalogue de champs interrogeables avec des détails sur leur compatibilité et leur type.

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

Interroger les attributs d'une ressource

Vous trouverez ci-dessous une requête de base pour les attributs de la ressource "campaign". Elle 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 trie par ID de campagne. Chaque GoogleAdsRow obtenu représenterait un objet campaign contenant les champs sélectionnés (y compris le resource_name de la campagne concernée).

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

Interroger des métriques

En plus des attributs sélectionnés pour une ressource donnée, vous pouvez également interroger des 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 triant par ID de campagne. Chaque GoogleAdsRow obtenu comporterait un champ metrics contenant les métriques sélectionnées.

Pour obtenir la liste des métriques pouvant être interrogées, consultez la documentation de Metrics.

Interroger des segments

En plus des attributs sélectionnés pour une ressource donnée, vous pouvez également interroger des 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. Cela conduit à chaque GoogleAdsRow résultant représentant le tuple d'une campagne et la date Segment. Il est important de noter que la segmentation divise les métriques sélectionnées, en les regroupant par segment dans la clause SELECT.

Pour obtenir la liste des segments pouvant être interrogés, consultez la documentation de Segments.

Dans une requête pour une ressource donnée, vous pouvez peut-être effectuer une jointure avec d'autres ressources associées, le cas échéant. Ces ressources associées sont appelées "ressources attribuées". Vous pouvez effectuer une jointure implicite avec les ressources attribuées 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 elle extrait également les attributs associés de chaque campagne sélectionnée. Chaque GoogleAdsRow obtenu représente un objet campaign contenant les attributs de campagne sélectionnés, ainsi que l'attribut bidding_strategy.name de la stratégie d'enchères sélectionné.

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

Modification en fonction des résultats de la requête

Lorsque vous interrogez une ressource donnée, vous pouvez immédiatement prendre ces résultats renvoyés en tant qu'objets, les modifier et les renvoyer à la méthode mutate du service de cette ressource. Voici un exemple de workflow:

  1. Exécutez une requête pour toutes les campagnes qui sont actuellement à l'état PAUSED et dont le nombre d'impressions est supérieur à 1 000.
  2. Récupérez l'objet Campaign à partir du champ campaign de chaque GoogleAdsRow de la réponse.
  3. Faites passer l'état de chaque campagne de PAUSED à ENABLED.
  4. Appelez CampaignService.MutateCampaigns avec les campagnes modifiées pour les mettre à jour.

Métadonnées des champs

Les requêtes envoyées à GoogleAdsFieldService sont destinées à récupérer des métadonnées de champ. Ces informations peuvent servir à 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, cela permet aux développeurs de le faire de manière automatisée. Voici une requête classique 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).

Pour obtenir la liste des champs pouvant être interrogés, consultez la documentation de GoogleAdsField.

Exemples de code

Les bibliothèques clientes contiennent des exemples d'utilisation du langage de requête Google Ads dans GoogleAdsService. Le dossier opérations de base contient des exemples tels que GetCampaigns, GetKeywords et SearchForGoogleAdsFields. Le dossier reporting contient un exemple GetKeywordStats.

Suivant
Grammaire des requêtes