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 sur les recherches 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 de récupération et de création de rapports d'objets unifié qui propose 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érez des attributs spécifiques d'objets.
• Récupérez les métriques de performances d'objets en fonction d'une plage de dates.
• Classer les objets en fonction de leurs attributs
• Filtrer vos résultats à l'aide de conditions qui spécifient les objets à renvoyer
• Limitez le nombre d'objets renvoyés.

Les deux méthodes de recherche renvoient toutes les lignes correspondant à 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, et un objet metrics avec son champ clicks défini.

Méthodes de recherche

SearchStream

Envoie une seule demande et établit 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'intégralité du résultat est mise en cache dans un tampon de données.
• Votre code peut commencer à lire les données mises en mémoire tampon sans avoir à attendre la fin de l'ensemble du flux.

Search

Envoie plusieurs demandes paginées pour télécharger l'intégralité du rapport.

SearchStream offre généralement de meilleures performances, car il élimine le temps d'aller-retour réseau requis 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 de performances significative entre les méthodes pour les rapports de petite taille (< 10 000 lignes).

La méthode utilisée n'affecte pas les quotas et limites de votre API: une seule requête ou un seul rapport est comptabilisé comme une opération, que les résultats soient paginés ou diffusés en continu.

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

Envoyer une requête

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

La demande consiste en un POST HTTP vers le serveur de l'API Search Ads 360 Reporting sur 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 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'objets SearchAds360Row.

Chaque SearchAds360Row représente un objet renvoyé par la requête. Chaque objet se compose d'un ensemble d'attributs 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 que avec campaign.id, campaign.name et campaign.status. Les autres attributs, comme campaign.engine_id ou campaign.bidding_strategy_type, sont ignorés.

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 répertorient tous les champs de segments et de métriques disponibles.

Certains segments, ressources et 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 ressources inclut les informations suivantes (si elles sont disponibles et appropriées), et plus encore:

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 ressource campaign est une ressource attribuée à la ressource ad_group. 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 ressources"

Tous les champs de la ressource sont inclus dans la colonne Champs de la ressource. Chaque champ de ressource renvoie vers des informations supplémentaires sur le champ, y compris sa description, sa catégorie, son type de données, son URL de type, ainsi que les paramètres filtrables, sélectionnables, triables et répétés.

Colonne "Segments"

Tous les champs de segment ne sont pas sélectionnables avec une ressource donnée.

La colonne Segments répertorie 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, ainsi que les paramètres de filtrage, de sélection, de tri et de répétition. 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"

Tous les champs de métriques ne sont pas sélectionnables 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, ainsi que les paramètres de filtrage, de sélection, de tri et de répétition. 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.

Segmenter des ressources

Certaines ressources disposent de champs de segmentation que vous pouvez sélectionner lorsque la ressource se trouve dans votre clause FROM. Par exemple, si vous sélectionnez un champ de ressource campaign, comme campaign.name, lorsque vous utilisez campaign_budget dans votre clause FROM, campaign.resource_name sera 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 ne disposent pas de ressources de segmentation.

Sélectionnable avec

Certains champs segments ne sont pas compatibles avec d'autres ressources, segments et métriques.

La page segments inclut un élément Selectable with (Champ sélectionnable avec) extensible pour chaque champ segments qui liste tous les champs de ressources compatibles, les champs metrics et les autres champs segments que vous pouvez inclure dans votre clause SELECT.

Segmentation

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

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

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"
      }
    },
    ...
  ]
}

Pour obtenir la liste des champs de segment disponibles, consultez segments.

Plusieurs segments

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 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 sélectionnés individuellement.

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 en fonction du champ resource_name de cette ressource

Cet exemple de requête renvoie automatiquement ad_group.resource_name et l'utilise implicitement pour segmenter les métriques au niveau de 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 dates principaux

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

Les champs de segments 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 des campagnes 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 segments de date de base constituent une exception à la règle générale selon laquelle vous ne pouvez pas utiliser de champ de segments 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 principales concernant les segments de date:

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

  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 de base dans votre clause SELECT, vous devez spécifier une date ou une plage de dates définies 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 des 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 ISO 8601

Vous pouvez utiliser le format YYYY-MM-DD (ISO 8601) pour spécifier des dates et des plages de dates, 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'

Dates prédéfinies

Vous pouvez également utiliser les dates et plages de dates prédéfinies suivantes:

Exemple :

WHERE segments.date DURING LAST_30_DAYS

Aucune métrique

Lorsque vous exécutez une requête, vous pouvez rencontrer des métriques ayant la valeur zéro 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 ajoutée dans l'interface utilisateur de Search Ads 360, mais elle 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 gardez à l'esprit les points suivants:

• Une ressource de type UNKNOWN peut être prise en charge 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 mettons en place des ressources avec ce changement dès qu'elles sont disponibles afin que vous disposiez d'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 prise en charge.
• Les ressources UNKNOWN peuvent être associées à des métriques détaillées que vous pouvez interroger.
• Les ressources UNKNOWN sont généralement entièrement visibles dans l'interface utilisateur de Search Ads 360.