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'instancesGoogleAdsRow
, chaqueGoogleAdsRow
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'instancesGoogleAdsField
, chaqueGoogleAdsField
contenant des informations sur le champ demandé.
Requête pour les attributs de ressources
Voici un exemple de requête de base pour les attributs de la ressource "Campaign" (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 est triée par ID de campagne. Chaque GoogleAdsRow
obtenu représente un objet campaign
renseigné 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 uniquement les campagnes dont l'état est PAUSED
et qui ont généré plus de 1 000 impressions. Elle les trie ensuite par ID de campagne. Chaque GoogleAdsRow
obtenu aurait 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 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
obtenu représente un tuple composé d'une campagne et d'une 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 pouvant faire l'objet de requêtes, consultez la documentation sur Segments
.
Interroger les attributs d'une ressource associée
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 Campaign
.
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 actuellement PAUSED
et dont le nombre d'impressions est supérieur à 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 en le faisant passer 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. 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 typique pour les métadonnées :
SELECT
name,
category,
selectable,
filterable,
sortable,
selectable_with,
data_type,
is_repeated
WHERE name = "<INSERT_RESOURCE_OR_FIELD>"
Dans cette requête, vous pouvez remplacer <INSERT_RESOURCE_OR_FIELD>
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 d'une requête, consultez la documentation sur GoogleAdsField
.
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
.