GoogleAdsService
est le service unifié de récupération et de création de rapports d'objets de l'API Google Ads. Le service comporte des méthodes qui :
- Récupérez des attributs spécifiques des objets.
- Récupérez les métriques de performances pour les objets en fonction d'une plage de dates.
- Ordonnez les objets en fonction de leurs attributs.
- Utilisez des conditions pour indiquer les objets que vous souhaitez renvoyer dans la réponse.
- Limitez le nombre d'objets renvoyés.
GoogleAdsService
peut renvoyer des résultats de deux manières :
GoogleAdsService.SearchStream
renvoie toutes les lignes dans une seule réponse de flux,ce qui est plus efficace pour les ensembles de résultats volumineux (plus de 10 000 lignes). Cette approche peut être plus appropriée si votre application par lot souhaite télécharger le plus de données possible le plus rapidement possible.GoogleAdsService.Search
divise les réponses volumineuses en pages de résultats gérables. Cela peut être plus approprié si votre application interactive affiche une page de résultats à la fois.
En savoir plus sur la pagination et le streaming
Envoyer une requête
La méthode de recherche nécessite un SearchGoogleAdsRequest
, qui se compose des attributs suivants :
customer_id
query
du langage de requête Google Ads indiquant la ressource à interroger, les attributs, les segments et les métriques à récupérer, ainsi que les conditions à utiliser pour limiter les objets renvoyés- (
GoogleAdsService.Search
uniquement)page_token
facultatif permettant de récupérer le prochain lot de résultats lors de l'utilisation de la pagination.
Pour en savoir plus sur le langage de requête Google Ads, consultez le guide sur le langage de requête Google Ads.
Traiter une réponse
GoogleAdsService
renvoie une liste d'objets GoogleAdsRow
.
Chaque GoogleAdsRow
représente un objet renvoyé par une requête et se compose d'un ensemble d'attributs renseignés en fonction des champs demandés dans la clause SELECT
. Les attributs non inclus dans la clause SELECT
ne sont pas renseignés dans les objets GoogleAdsRow
de la réponse.
Par exemple, bien qu'un ad_group_criterion
comporte un attribut status
, le champ status
de l'attribut ad_group_criterion
de la ligne n'est pas renseigné dans une réponse à une requête dont la clause SELECT
n'inclut pas ad_group_criterion.status
. De même, l'attribut campaign
de la ligne n'est pas renseigné si la clause SELECT
n'inclut aucun champ de la ressource campaign
.
Chaque GoogleAdsRow
peut avoir des attributs et des métriques différents de ceux d'une autre ligne du même ensemble de résultats. Les lignes doivent donc être considérées comme des objets plutôt que comme des lignes fixes d'un tableau.
Types d'énumération UNKNOWN
Les ressources renvoyées avec un type UNKNOWN
ne sont pas entièrement compatibles avec cette version de l'API. Ces ressources peuvent avoir été créées à l'aide d'autres interfaces, comme l'interface utilisateur Google Ads. Vous pouvez sélectionner des métriques lorsqu'une ressource est de type UNKNOWN
, mais vous ne pouvez pas modifier la ressource via l'API. Par exemple, une nouvelle campagne ou annonce peut être introduite dans l'UI, mais ne pas être compatible avec la version de l'API que vous interrogez.
Voici quelques points à prendre en compte :
- Une ressource de type
UNKNOWN
peut être acceptée ultérieurement ou resterUNKNOWN
indéfiniment. - De nouveaux objets de type
UNKNOWN
peuvent apparaître à tout moment. Ces objets sont rétrocompatibles, car la valeur d'énumération est déjà disponible. Les ressources sont introduites avec ce changement, car elles sont disponibles pour vous permettre d'avoir une vue précise de votre compte. La ressourceUNKNOWN
peut apparaître en raison de nouvelles activités dans votre compte via d'autres interfaces ou lorsqu'une ressource n'est plus prise en charge. - Des métriques détaillées et interrogeables peuvent être associées aux ressources
UNKNOWN
. - Les ressources
UNKNOWN
sont généralement entièrement visibles dans l'UI Google Ads. - En général, les ressources
UNKNOWN
ne peuvent pas être modifiées.
Segmentation
La réponse contiendra un GoogleAdsRow
pour chaque combinaison des éléments suivants :
- Instance de la ressource principale spécifiée dans la clause
FROM
- Valeur de chaque champ
segment
sélectionné
Par exemple, la réponse à une requête qui sélectionne FROM campaign
et qui comporte segments.ad_network_type
et segments.date
dans la clause SELECT
contient une ligne pour chaque combinaison des éléments suivants :
campaign
segments.ad_network_type
segments.date
Les résultats sont segmentés de manière implicite par chaque instance de la ressource principale, et non par les valeurs des champs individuels sélectionnés. Par exemple,
SELECT campaign.status, metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS
génère une ligne par campagne, et non une ligne par valeur distincte du champ campaign.status
.