Récupération des objets

Objectif :Comprendre comment récupérer des objets et des statistiques de performances à l'aide de GoogleAdsService Pour découvrir les concepts liés à la création de rapports, consultez les guides sur les rapports.

GoogleAdsService est le service unifié de récupération d'objets et de création de rapports de l'API Google Ads. Le service comporte des méthodes qui:

• Récupérez des attributs spécifiques d'objets.
• Récupérez les métriques de performances des 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.

Le GoogleAdsService peut renvoyer des résultats de deux manières:

• GoogleAdsService.SearchStream renvoie toutes les lignes dans une seule réponse en flux continu,ce qui est plus efficace pour les ensembles de résultats volumineux (plus de 10 000 lignes). Cela peut être plus approprié si votre application par lot souhaite télécharger un maximum de données 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 la diffusion en streaming

Envoyer une requête

La méthode de recherche nécessite un objet SearchGoogleAdsRequest, composé des attributs suivants:

• Une chaîne (customer_id)
• Un query du langage de requête Google Ads qui indique la ressource à interroger, les attributs, les segments et les métriques à récupérer, et les conditions à utiliser pour limiter les objets renvoyés.
• (GoogleAdsService.Search uniquement) page_size pour indiquer le nombre d'objets à renvoyer dans une seule réponse lorsque vous utilisez la pagination.
• (GoogleAdsService.Search uniquement) page_token facultatif pour récupérer le lot de résultats suivant lorsque vous utilisez la pagination.

Pour plus d'informations sur le langage de requête Google Ads, consultez le guide consacré au 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 consiste en un ensemble d'attributs renseignés en fonction des champs demandés dans la clause SELECT. Les attributs qui ne sont pas inclus dans la clause SELECT ne sont pas renseignés sur les objets GoogleAdsRow dans la réponse.

Par exemple, bien qu'un attribut ad_group_criterion ait 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 où 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 d'une autre ligne dans le 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'une table.

Types d'énumérations UNKNOWN

Les ressources renvoyées avec un type UNKNOWN ne sont pas entièrement compatibles avec cette version d'API. Ces ressources peuvent avoir été créées via d'autres interfaces, comme l'UI Google Ads. Vous pouvez sélectionner des métriques lorsqu'une ressource est de type UNKNOWN, mais vous ne pouvez pas la modifier via l'API. Il peut s'agir, par exemple, d'une nouvelle campagne ou d'une nouvelle annonce introduite dans l'interface utilisateur, mais non compatible avec la version de l'API que vous interrogez.

Voici quelques points à garder à l'esprit:

• Une ressource de type UNKNOWN peut être prise en charge ultérieurement ou rester UNKNOWN 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 cette modification dès qu'elles sont disponibles afin que vous ayez une vision précise de votre compte. La ressource UNKNOWN peut s'afficher en raison de nouvelles activités dans votre compte via d'autres interfaces ou lorsqu'une ressource n'est plus compatible.
• Les ressources UNKNOWN peuvent être associées à des métriques détaillées pouvant être interrogées.
• Les ressources "UNKNOWN" sont généralement entièrement visibles dans l'interface utilisateur Google Ads.
• Les ressources UNKNOWN ne peuvent généralement pas être modifiées.

Segmentation

La réponse contiendrait 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 dont segments.ad_network_type et segments.date dans la clause SELECT contiendra une ligne pour chaque combinaison des éléments suivants:

• campaign
• segments.ad_network_type
• segments.date

Les résultats sont segmentés implicitement 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.