Langage de requête Google Ads

Conseil : Utilisez le générateur de requêtes interactif pour créer et valider vos requêtes GAQL.

Terminologie clé

Ressource

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

Segment

Dimension utilisée pour regrouper les données, par exemple 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 implicitement jointe à la ressource principale dans la clause FROM, ce qui vous permet de sélectionner ses attributs ainsi que ceux de la ressource principale.

Interroger des informations sur les ressources ou les métadonnées

Le langage de requête Google Ads peut interroger l'API Google Ads pour obtenir 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 requête GoogleAdsFieldService 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 d'attributs de ressource

Voici un exemple de requête de base pour les attributs de la ressource "campaign" 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 trie les résultats par ID de campagne. Chaque GoogleAdsRow obtenu représente un objet campaign renseigné avec les champs sélectionnés, y compris l'resource_name de la campagne.

Pour connaître les autres champs disponibles pour les requêtes de campagne, consultez la documentation de référence sur Campaign.

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 ne filtre que les campagnes dont l'état est PAUSED et qui ont enregistré plus de 1 000 impressions, tout en les classant par ID de campagne. Chaque GoogleAdsRow résultant comporterait un champ metrics renseigné avec les métriques sélectionnées.

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

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 l'interrogation des métriques, cette requête ne filtre que 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 donc un tuple d'une campagne et du segment de date. 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 documentation sur Segments.

Interroger les attributs d'une ressource associée

Dans une requête portant sur une ressource donnée, vous pouvez 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 implicite avec des 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 campagne, mais extrait également les attributs associés de chaque campagne sélectionnée. Chaque GoogleAdsRow obtenu représente un objet campaign renseigné avec les attributs de campagne sélectionnés, ainsi que l'attribut de stratégie d'enchères sélectionné bidding_strategy.name.

Pour connaître les ressources attribuées disponibles pour les requêtes de campagne, consultez la documentation de référence sur Campaign.

Bonnes pratiques

• Sélectionnez uniquement les champs dont vous avez besoin pour éviter les temps de réponse longs et les délais d'expiration.
• Utilisez LIMIT pendant le développement et les tests pour éviter de traiter des ensembles de résultats volumineux.
• Appliquez des filtres dans la clause WHERE pour réduire le transfert de données et la taille 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.
• Sachez que certains champs, en particulier ceux impliquant de grandes quantités de données ou des calculs complexes, peuvent augmenter le coût des requêtes.

Muter 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 PAUSED qui ont enregistré plus de 1 000 impressions.
2. Récupérez l'objet Campaign à partir du champ campaign de chaque GoogleAdsRow de la réponse.
3. Remplacez l'état de chaque campagne par ENABLED au lieu de PAUSED.
4. Appelez CampaignService.MutateCampaigns avec les campagnes modifiées et un FieldMask correspondant pour les mettre à jour.

Remarque : Lorsque vous mettez à jour des ressources récupérées à partir d'une requête, spécifiez un FieldMask (ou utilisez l'utilitaire de masque de champ intégré de votre bibliothèque cliente) afin que seuls les champs modifiés soient mis à jour, ce qui évite les erreurs READ_ONLY_FIELD ou IMMUTABLE_FIELD, ou l'écrasement involontaire d'autres attributs.

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. Comme les données sont disponibles à partir de l'API et qu'elle fournit les métadonnées nécessaires pour valider ou créer une requête, les développeurs peuvent le faire de manière programmatique. Voici une requête type 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).

Point clé : Notez qu'il n'y a pas de clause FROM dans cette requête.

Pour obtenir la liste des champs interrogeables, consultez la documentation sur GoogleAdsField.

Différences selon les versions

Bien que la syntaxe, les clauses et les opérateurs du langage de requête Google Ads soient identiques dans toutes les versions de l'API Google Ads compatibles (v23, v24, v25 et v26), le catalogue des ressources, segments, métriques et comportements de reporting interrogeables diffère selon la version majeure. Interrogez GoogleAdsFieldService au niveau du point de terminaison de la version de l'API cible pour inspecter les champs et les règles de compatibilité de cette version :

• Vue des composants d'extension de l'URL finale :
  • Compatibilité avec les campagnes Shopping (v26 et versions ultérieures) : final_url_expansion_asset_view est compatible avec les campagnes Shopping (campaign.advertising_channel_type = 'SHOPPING') en plus des campagnes Performance Max et sur le Réseau de Recherche. Pour les campagnes Shopping, vous pouvez sélectionner et filtrer les champs ad_group, mais vous ne pouvez pas sélectionner les champs asset_group.
  • Métriques sélectionnables (v25 et versions ultérieures) : l'interrogation de final_url_expansion_asset_view renvoie toutes les métriques sélectionnables pour la vue. Dans la version 24 et les versions antérieures, les réponses n'incluent que metrics.conversions et metrics.conversions_value pour les campagnes Performance Max, et metrics.impressions pour les campagnes sur le Réseau de Recherche.
• Ressources d'objectifs de cycle de vie : dans la version 25 et les versions ultérieures, tous les objectifs de cycle de vie (acquisition de nouveaux clients, rétention client et fidélisation) sont interrogés à partir des ressources unifiées goal et campaign_goal_config, qui remplacent customer_lifecycle_goal et campaign_lifecycle_goal (qui étaient utilisées pour les objectifs d'acquisition de nouveaux clients dans la version 24 et les versions antérieures, ainsi que goal et campaign_goal_config pour les objectifs de rétention client).
• Rapports sur les produits Shopping pour les campagnes pour applications : dans la version 24 et les versions ultérieures, la ressource shopping_product renvoie des lignes de produits pour les campagnes pour applications en plus des campagnes Shopping, Performance Max, Demand Gen et vidéo (dans la version 23, les campagnes pour applications sont exclues des résultats de shopping_product).
• Ressources, segments et métriques spécifiques à une version :
  • v26 et versions ultérieures : inclut la ressource search_lift_keyword_bundle, campaign.lift_measurement_config, local_services_lead.campaign, segments.search_lift_keyword_bundle, segments.search_property et les métriques de search lift (telles que metrics.relative_search_lift, metrics.normalized_incremental_searches, metrics.search_lift_cost_micros et metrics.search_lift_impressions).
  • v25 et versions ultérieures : inclut les ressources de mesure du lift (comme lift_measurement_config), les segments tels que segments.ad_sub_format_type et segments.loyalty_membership, et les métriques d'engagement YouTube (metrics.youtube_likes, metrics.youtube_comments et metrics.youtube_shares). Supprime local_services_lead.contact_details.email (qui peut être sélectionné dans la v24 et les versions antérieures).
  • v24 et versions ultérieures : inclut la ressource cart_data_sales_view, segments.conversion_attribution_event_type sur shopping_performance_view, segments.mobile_device_platform et segments.ad_network_type sur performance_max_placement_view. Suppression de campaign.video_brand_safety_suitability (remplacé par customer.video_brand_safety_suitability), de segments.ad_sub_network_type sur campaign_budget, et de segments.click_type sur ad_group_asset, campaign_asset et customer_asset (qui ne sont sélectionnables que dans la v23).
• Code d'erreur de période d'analyse précise : les requêtes qui segmentent par segments.date, segments.week ou segments.hour (ou qui filtrent sur une période inférieure à un mois) au-delà de la période d'analyse de 37 mois renvoient DateRangeError.REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED dans la version 24 et les versions ultérieures (ou DateRangeError.UNKNOWN dans la version 23). Pour en savoir plus, consultez Plages de dates.

Exemples de code

Les bibliothèques clientes contiennent des exemples d'utilisation du langage de requête Google Ads dans GoogleAdsService. Le dossier basic operations contient des exemples tels que GetCampaigns, GetKeywords et SearchForGoogleAdsFields.