Créer des rapports de recherche dans l'API Search Ads 360 Reporting

Lisez les sections ci-dessous pour découvrir comment créer des rapports de recherche dans l'API Search Ads 360 Reporting.

Service de recherche

L'API Search Ads 360 Reporting fournit un service spécial pour la recherche et la création de rapports.

SearchAds360Service est un service unifié de récupération d'objets et de création de rapports qui fournit deux méthodes de recherche : SearchStream et Search. Les recherches sont transmises dans une chaîne de requête écrite dans le langage de requête Search Ads 360. Vous pouvez définir des requêtes pour :

• récupérer des attributs spécifiques d'objets ;
• récupérer des métriques de performances pour des objets en fonction d'une période ;
• ordonner des objets en fonction de leurs attributs ;
• filtrer vos résultats à l'aide de conditions qui spécifient les objets à renvoyer ;
• limiter le nombre d'objets renvoyés.

Les deux méthodes de recherche renvoient toutes les lignes qui correspondent à votre requête. Par exemple, lorsque vous récupérez campaign.id, campaign.name et metrics.clicks, l'API renvoie un SearchAds360Row contenant un objet de campagne avec ses champs id et name définis, ainsi qu'un objet metrics avec son champ clicks défini.

Méthodes de recherche

SearchStream

Envoie une seule requête et initie une connexion persistante avec l'API Search Ads 360 Reporting, quelle que soit la taille du rapport.

• Les paquets de données commencent à être téléchargés immédiatement, et l'ensemble des résultats est mis en cache dans une mémoire tampon de données.
• Votre code peut commencer à lire les données mises en mémoire tampon sans avoir à attendre la fin du flux.

Search

Envoie plusieurs requêtes paginées pour télécharger l'intégralité du rapport.

SearchStream offre généralement de meilleures performances, car elle élimine le temps de trajet aller-retour du réseau nécessaire pour demander des pages individuelles. Nous vous recommandons d'utiliser SearchStream pour tous les rapports de plus de 10 000 lignes. Il n'existe aucune différence significative de performances entre les méthodes pour les rapports plus petits (moins de 10 000 lignes).

La méthode que vous utilisez n'a aucune incidence sur vos API quotas et limites : une seule requête ou un seul rapport est comptabilisé comme une seule opération, que les résultats soient paginés ou diffusés.

Exemple de requête de recherche

Cet exemple de requête renvoie les données de performances d'un compte pour les 30 derniers jours par campagne, segmentées par appareil :

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Remarque : Le langage de requête Search Ads 360 fournit des informations détaillées sur l'utilisation de chaque clause de la requête de recherche.

Envoyer une requête

Pour envoyer une requête, vous devez transmettre une chaîne customer_id et une chaîne query à l'interface SearchAds360Service.SearchStream ou SearchAds360Service.Search.

Remarque : Les exemples ci-dessous montrent la requête HTTP/JSON sous-jacente. Elle est utilisée pour illustrer les concepts. Nous vous recommandons d'utiliser nos bibliothèques clientes basées sur gRPC pour envoyer des requêtes dans votre propre application.

La requête consiste en une requête HTTP POST adressée au serveur de l'API Search Ads 360 Reporting à l'une des URL suivantes :

https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream

https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:search

Voici un exemple complet de la définition de rapport pour searchStream incluse dans une requête HTTP POST :

POST /VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream HTTP/1.1
Host: searchads360.googleapis.com
User-Agent: curl
Content-Type: application/json
Accept: application/json
Authorization: Bearer [OAUTH_2.0_ACCESS_TOKEN]

Parameters:
{
  "query" : "SELECT campaign.name, campaign.status, segments.device,
                    metrics.impressions, metrics.clicks, metrics.ctr,
                    metrics.average_cpc, metrics.cost_micros
            FROM campaign
            WHERE segments.date DURING LAST_30_DAYS"
}

Traiter une réponse

SearchAds360Service renvoie une liste d' SearchAds360Row objets.

Chaque SearchAds360Row représente un objet renvoyé par la requête. Chaque objet se compose d'un ensemble d'attributs qui sont renseignés en fonction des champs demandés dans la clause SELECT de la requête. Les attributs non inclus dans la clause SELECT ne sont pas renseignés dans les objets de la réponse.

Par exemple, la requête ci-dessous ne renseigne chaque objet SearchAds360Row qu'avec campaign.id, campaign.name et campaign.status. Les autres attributs, tels que campaign.engine_id ou campaign.bidding_strategy_type, sont omis.

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign

Documentation de référence

La section Référence inclut toutes les informations dont vous avez besoin pour utiliser correctement chaque artefact. Il existe une page pour chaque ressource, par exemple ad_group et campaign. Les pages segments et metrics listent tous les champs de segment et de métrique disponibles.

Certaines ressources, certains segments et certaines métriques sont incompatibles et ne peuvent pas être utilisés ensemble, tandis que d'autres sont entièrement compatibles et se complètent. Chaque page de ressource inclut les informations suivantes (si elles sont disponibles et appropriées), entre autres :

Ressources attribuées

Pour certaines ressources, vous pouvez avoir la possibilité de joindre implicitement des ressources associées en sélectionnant leurs champs avec les champs de la ressource dans votre clause FROM. Par exemple, la campaign ressource est une ressource attribuée de la ad_group ressource. Cela signifie que vous pouvez inclure des champs tels que campaign.id et campaign.bidding_strategy_type dans votre requête lorsque vous utilisez ad_group dans votre clause FROM.

La section Ressources attribuées liste les ressources attribuées disponibles. Toutes les ressources n'ont pas de ressources attribuées.

Colonne "Champs de ressource"

Tous les champs de la ressource sont inclus dans la colonne Champs de ressource. Chaque champ de ressource renvoie à plus de détails sur le champ, y compris sa description, sa catégorie, son type de données, son URL de type et son paramètre filtrable, sélectionnable, triable et répété.

Colonne "Segments"

Les champs de segment ne peuvent pas tous être sélectionnés avec une ressource donnée.

La colonne Segments liste les champs segments que vous pouvez utiliser dans la même clause SELECT que les champs de la ressource. Chaque champ renvoie à des informations complètes sur le champ, y compris sa description, sa catégorie, son type de données, son URL de type et son paramètre filtrable, sélectionnable, triable et répété. Si vous utilisez la ressource dans votre clause FROM, vous pouvez utiliser le menu déroulant Oui/Non pour filtrer les segments qui ne sont pas disponibles.

Colonne "Métriques"

Les champs de métrique ne peuvent pas tous être sélectionnés avec une ressource donnée.

La colonne Métriques liste les champs metrics que vous pouvez utiliser dans la même clause SELECT que les champs de la ressource. Chaque champ renvoie à des informations complètes sur le champ, y compris sa description, sa catégorie, son type de données, son URL de type et son paramètre filtrable, sélectionnable, triable et répété. Si vous utilisez la ressource dans votre clause FROM, utilisez le menu déroulant Oui/Non pour filtrer les métriques qui ne sont pas disponibles.

Remarque : Lorsque vous obtenez des métriques liées à la devise (par exemple, cost_micros) pour une date ou une période spécifique, veillez à inclure segments.date dans la clause SELECT.

Segmentation des ressources

Certaines ressources comportent des champs de ressource de segmentation que vous pouvez sélectionner lorsque la ressource se trouve dans votre clause FROM. Par exemple, si vous sélectionnez un campaign champ de ressource, tel que campaign.name, lorsque vous utilisez campaign_budget dans votre clause FROM, campaign.resource_name est automatiquement renvoyé et segmenté, car campaign est une ressource de segmentation de campaign_budget.

La section Ressources de segmentation liste les ressources de segmentation disponibles. Toutes les ressources n'ont pas de ressources de segmentation.

Sélectionnable avec

Certains champs segments sont incompatibles avec d'autres ressources, segments et métriques.

La page segments inclut un élément extensible Sélectionnable avec pour chaque champ segments qui liste tous les champs de ressource compatibles, les champs metrics et les autres champs segments que vous pouvez inclure dans votre clause SELECT.

Remarque : Consultez le langage de requête Search Ads 360 pour découvrir comment utiliser chaque clause d'une requête.

Segmentation

Vous pouvez segmenter vos résultats de recherche en ajoutant un segments.FIELD_NAME champ à la SELECT clause de votre requête.

Par exemple, segments.device dans la requête ci-dessous génère un rapport avec une ligne pour les impressions de chaque appareil pour la ressource spécifiée dans la FROM clause.

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions
FROM campaign

Les résultats renvoyés par SearchAds360Service.SearchStream ressemblent à cette chaîne JSON :

{
  "results":[
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"10922"
      },
      "segments":{
        "device":"MOBILE"
      }
    },
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"28297"
      },
      "segments":{
        "device":"DESKTOP"
      }
    },
    ...
  ]
}

Consultez segments pour obtenir la liste des champs de segment disponibles que vous pouvez utiliser.

Plusieurs segments

Attention : Le nombre de lignes peut augmenter de manière exponentielle pour chaque champ segments supplémentaire que vous ajoutez à votre requête.

Vous pouvez spécifier plusieurs segments dans la clause SELECT de votre requête. La réponse contient un objet SearchAds360Row pour chaque combinaison de l'instance de la ressource principale spécifiée dans la clause FROM et de la valeur de chaque champ segment sélectionné.

Par exemple, la requête suivante renvoie une ligne pour chaque combinaison de campaign, segments.ad_network_type et segments.date.

SELECT
  segments.ad_network_type
  segments.date
FROM campaign

Notez que les résultats sont segmentés implicitement par chaque instance de la ressource principale, mais pas par les valeurs des champs individuels sélectionnés.

L'exemple de requête suivant génère une ligne par campagne, et non une ligne par valeur distincte du champ campaign.status.

SELECT
  campaign.status,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS

Segmentation implicite

Chaque rapport est initialement segmenté par la ressource spécifiée dans la clause FROM. Les métriques sont segmentées par le champ resource_name de cette ressource.

Remarque : Le champ resource_name de la ressource dans la clause FROM est toujours renvoyé, même lorsqu'il n'est pas spécifié dans la clause SELECT. Pour en savoir plus, consultez le champ resource_name pour plus d'informations.

Cet exemple de requête renvoie automatiquement ad_group.resource_name et l'utilise implicitement pour segmenter les métriques au niveau ad_group.

SELECT metrics.impressions
FROM ad_group

La chaîne JSON renvoyée ressemble à ceci :

{
  "results":[
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/2222222222"
      },
      "metrics":{
        "impressions":"237"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/33333333333"
      },
      "metrics":{
        "impressions":"15"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/44444444444"
      },
      "metrics":{
        "impressions":"0"
      }
    }
  ]
}

Segments de date principaux

Vous pouvez utiliser des segments de date principaux dans votre WHERE clause pour spécifier une date ou une période.

Les champs de segment suivants sont appelés segments de date principaux: segments.date, segments.week, segments.month, segments.quarter, et segments.year.

Cet exemple de requête renvoie les métriques clicks de la campagne pour les 30 derniers jours.

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Les champs de segment de date principaux sont une exception à la règle générale selon laquelle vous ne pouvez pas utiliser de champ de segment dans votre clause WHERE, sauf si vous incluez également le champ dans votre clause SELECT. Pour en savoir plus, consultez la section Filtrage interdit.

Règles de segment de date principaux :

• Vous pouvez utiliser un champ de date principal dans votre clause WHERE sans l'inclure dans votre clause SELECT. Vous pouvez également inclure le champ dans les deux clauses si vous le souhaitez.

  Cet exemple de requête renvoie les métriques clicks par nom de campagne au cours de la période. Notez que segments.date n'est pas inclus dans la clause SELECT.

  SELECT
      campaign.name,
      metrics.clicks
  FROM campaign
  WHERE segments.date > '2022-02-01'
    AND segments.date < '2022-03-01'
  

• Si vous incluez un champ de date principal dans votre clause SELECT, vous devez spécifier une date ou une période finie dans votre clause WHERE. Les champs spécifiés dans les clauses SELECT et WHERE ne doivent pas nécessairement correspondre.

  Cet exemple de requête renvoie les métriques clicks par nom de campagne segmentées par mois pour tous les jours de la période.

  SELECT
    campaign.name,
    metrics.clicks,
    segments.month
  FROM campaign
  WHERE segments.date > '2022-02-01'
    AND segments.date < '2022-03-01'
  

Dates au format ISO 8601

Vous pouvez utiliser le format YYYY-MM-DD (ISO 8601) pour spécifier des dates et des périodes, par exemple :

WHERE segments.date BETWEEN '2022-06-01' AND '2022-06-30'

WHERE segments.date >= '2022-06-01' AND segments.date <= '2022-06-30'

Pour les segments de date principaux qui nécessitent une période (segments.week, segments.month, segments.quarter) vous pouvez utiliser l'opérateur = avec le premier jour de la période, par exemple :

WHERE segments.month = '2022-06-01'

Remarque : Si vous spécifiez une date qui n'est pas le premier jour d'une période, vous recevrez une erreur MISALIGNED_DATE_FOR_FILTER.

Dates prédéfinies

Vous pouvez également utiliser les dates et périodes prédéfinies suivantes :

Dates prédéfinies
TODAY	Aujourd'hui uniquement.
YESTERDAY	Hier uniquement.
LAST_7_DAYS	Les sept jours précédents, sans compter aujourd'hui.
LAST_BUSINESS_WEEK	La semaine de travail précédente de cinq jours (du lundi au vendredi).
THIS_MONTH	Tous les jours du mois en cours.
LAST_MONTH	Tous les jours du mois précédent.
LAST_14_DAYS	Les 14 jours précédents, sans compter aujourd'hui.
LAST_30_DAYS	Les 30 jours précédents, sans compter aujourd'hui.
THIS_WEEK_SUN_TODAY	Période comprise entre le dimanche précédent et le jour actuel.
THIS_WEEK_MON_TODAY	Période comprise entre le lundi précédent et le jour actuel.
LAST_WEEK_SUN_SAT	Période de sept jours à compter du dimanche précédent.
LAST_WEEK_MON_SUN	Période de sept jours à compter du lundi précédent.

Exemple :

WHERE segments.date DURING LAST_30_DAYS

Métriques nulles

Lorsque vous exécutez une requête, vous pouvez rencontrer des métriques dont la valeur est nulle pour certaines entités. Découvrez comment gérer les métriques nulles dans vos requêtes.

Types d'énumération UNKNOWN

Si une ressource est renvoyée avec le type de données d'énumération UNKNOWN, cela signifie que le type n'est pas entièrement compatible avec la version de l'API. Ces ressources ont peut-être été créées via d'autres interfaces. Par exemple, une nouvelle campagne ou annonce est introduite dans l'interface utilisateur Search Ads 360, mais n'est pas encore compatible avec la version de l'API que vous interrogez.

Vous pouvez toujours sélectionner des métriques lorsqu'une ressource est de type UNKNOWN, mais vous devez garder à l'esprit les points suivants :

• Une ressource de type UNKNOWN pourra peut-être être compatible ultérieurement, mais elle peut 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. Nous introduisons des ressources avec cette modification dès qu'elles sont disponibles afin que vous ayez une vue précise de votre compte. La ressource UNKNOWN peut apparaître en raison d'une nouvelle activité dans votre compte via d'autres interfaces ou parce qu'une ressource n'est plus officiellement compatible.

• Des métriques détaillées peuvent être associées aux ressources UNKNOWN que vous pouvez interroger.

• Les ressources UNKNOWN sont généralement entièrement visibles dans l'interface utilisateur Search Ads 360.