Langage de requête Google Ads

Terminologie clé

Ressource
 : entité dans Google Ads, comme campaign ou ad_group.
Segment
Dimension utilisée pour regrouper des données, comme 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 qui est jointe de manière implicite à la ressource principale dans la clause FROM, ce qui vous permet de sélectionner ses attributs en même temps que ceux de la ressource principale.

Interroger pour obtenir 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 informations 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 les attributs de ressources

Voici un exemple de requête de base pour les attributs de la ressource de campagne qui montre 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 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 sur les campagnes, 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 filtre les campagnes dont l'état est PAUSED et qui ont généré plus de 1 000 impressions, tout en les triant par ID de campagne. Chaque GoogleAdsRow obtenu comporterait un champ metrics renseigné avec les métriques sélectionnées.

Pour obtenir la liste des métriques pouvant faire l'objet de requêtes, 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 les requêtes de métriques, cette requête ne filtre que les campagnes dont l'état est PAUSED et qui ont généré plus de 1 000 impressions. Toutefois, cette requête segmente les données par date. Chaque GoogleAdsRow résultant représente un tuple composé 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 pouvant faire l'objet de requêtes, consultez la documentation sur Segments.

Dans une requête pour 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 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 sur les campagnes, 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 temps de réponse et les délais d'expiration.
  • Utilisez LIMIT lors du développement et des tests pour éviter de traiter de grands ensembles de résultats.
  • Appliquez des filtres dans la clause WHERE pour minimiser 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.
  • 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 des mutations en fonction des résultats de requête

Lorsque vous interrogez une ressource donnée, vous pouvez immédiatement considérer les résultats renvoyés comme des 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 PAUSED dont les impressions sont supérieures à 1 000.
  2. Obtenez l'objet Campaign à partir du champ campaign de chaque GoogleAdsRow dans la réponse.
  3. Modifiez l'état de chaque campagne de PAUSED à ENABLED.
  4. Appelez CampaignService.MutateCampaigns avec les campagnes modifiées et un FieldMask correspondant 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. Les développeurs peuvent valider ou créer des requêtes de manière programmatique, car les données sont disponibles dans l'API et fournissent les métadonnées nécessaires. 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).

Pour obtenir la liste des champs pouvant faire l'objet de requêtes, consultez la documentation sur GoogleAdsField.

Différences spécifiques aux versions

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

  • Ressources sur les 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, fidélisation des clients et fidélisation) sont interrogés à partir des ressources unifiées goal et campaign_goal_config, en remplacement de 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, aux côtés de goal et campaign_goal_config pour les objectifs de fidélisation des clients).
  • Métriques sur les vues des composants d'extension d'URL finale : dans la version 25 et les 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.
  • 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 shopping_product).
  • Ressources, segments et métriques spécifiques à une version :
    • v25 et versions ultérieures : inclut les ressources de mesure de l'impact (telles que 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 version 24 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), segments.ad_sub_network_type sur campaign_budget et segments.click_type sur ad_group_asset, campaign_asset et customer_asset (qui ne sont sélectionnables que dans la version 23).
  • Code d'erreur lié à la période d'analyse granulaire : 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 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.

Suivant
Grammaire des requêtes