Récupérer des objets

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

  • Récupérer des attributs spécifiques d'objets.
  • Récupérez les métriques de performances des objets en fonction d'une plage de dates.
  • Classer des 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 en streaming, ce qui est plus efficace pour les ensembles de résultats volumineux (plus de 10 000 lignes). Cette option est recommandée si votre application télécharge des ensembles de résultats complets ou traite des lignes sous forme de flux.
  • GoogleAdsService.Search divise les réponses volumineuses en pages de résultats gérables. Cette méthode est utile si votre application interactive affiche une page de résultats à la fois.

En savoir plus sur la différence entre la pagination et le streaming

Envoyer une requête

GoogleAdsService.SearchStream attend un SearchGoogleAdsStreamRequest, et GoogleAdsService.Search attend un SearchGoogleAdsRequest. Les deux types de requêtes incluent :

  • customer_id
  • Une query en langage de requête Google Ads qui indique 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.

Selon la méthode, la requête accepte également des champs spécifiques à la méthode :

  • SearchGoogleAdsStreamRequest (SearchStream uniquement) :
    • Un summary_row_setting facultatif pour demander une ligne récapitulative contenant des métriques agrégées
  • SearchGoogleAdsRequest (Search uniquement) :
    • Un page_token facultatif pour récupérer le prochain lot de résultats lors de l'utilisation de la pagination (page_size est fixé à 10 000 lignes ; la définition de page_size dans la requête génère une erreur RequestError.PAGE_SIZE_NOT_SUPPORTED)
    • Un message search_settings facultatif pour configurer return_summary_row, return_total_results_count et omit_results
    • Un booléen validate_only facultatif pour valider la requête sans l'exécuter

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 (soit dans des lots SearchGoogleAdsStreamResponse diffusés en continu, soit dans un SearchGoogleAdsResponse paginé).

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 sur les objets GoogleAdsRow de la réponse.

Par exemple, bien qu'un ad_group_criterion possède 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 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 et UNSPECIFIED

Les ressources renvoyées avec une valeur d'énumération UNKNOWN ne sont pas entièrement compatibles avec cette version de l'API, tandis que UNSPECIFIED indique qu'un champ d'énumération n'a pas été défini ou n'a pas été demandé dans la clause SELECT. Les ressources avec une valeur d'énumération UNKNOWN ont pu être créées via 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, un type de campagne ou un type d'annonce disponible dans l'UI n'est pas compatible avec la version de l'API que vous interrogez.

Voici quelques points à prendre en compte :

  • Une ressource de type UNKNOWN peut être compatible avec une version ultérieure de l'API 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 UNKNOWN est présente sur chaque énumération de l'API. Les ressources sont renvoyées avec UNKNOWN afin que vous disposiez d'une vue précise des métriques de performances globales de votre compte.
  • Les ressources UNKNOWN peuvent être associées à des métriques détaillées qui peuvent être interrogées.
  • Les ressources UNKNOWN sont généralement entièrement visibles dans l'interface utilisateur de Google Ads.
  • Les ressources UNKNOWN ne peuvent généralement pas être modifiées via l'API.

Segmentation

La réponse contient 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 segments sélectionné

Par exemple, la réponse à une requête qui sélectionne FROM campaign et 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 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.

Précédent
Modifier des objets
Suivant
Métadonnées de ressources