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

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

Service de recherche

L'API Search Ads 360 Reporting offre 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é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.
• Filtrer les résultats à l'aide de conditions spécifiant 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 "campaign" avec les champs id et name définis, et un objet metrics avec le champ clicks.

Méthodes de recherche

SearchStream

Envoie une demande unique et établit une connexion persistante avec l'API Search Ads 360 Reporting, quelle que soit la taille du rapport.

• Le téléchargement des paquets de données commence immédiatement avec l'intégralité du résultat mis en cache dans un tampon de données.
• Votre code peut commencer à lire les données 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 réseau aller-retour 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'y a pas de différence de performances significative entre les méthodes pour les petits rapports (moins de 10 000 lignes).

La méthode que vous utilisez n'a aucune incidence sur 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 des données sur les performances d'un compte au cours des 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 émettre une requête, vous devez transmettre une customer_id et une chaîne query à l'interface SearchAds360Service.SearchStream ou SearchAds360Service.Search.

Remarque :Les exemples ci-dessous illustrent la requête HTTP/JSON sous-jacente. Ceci est utilisé pour démontrer 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 un POST HTTP envoyé 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 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'objets SearchAds360Row.

Chaque SearchAds360Row représente un objet renvoyé par la requête. Chaque objet est constitué 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 insérés dans les objets de la réponse.

Par exemple, la requête ci-dessous insère chaque objet SearchAds360Row avec uniquement 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 répertorient tous les champs de métriques et de segments 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 ressources comprend les informations suivantes (si 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 ceux 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 la clause FROM.

La section Ressources attribuées liste les ressources attribuées disponibles. Certaines ressources ne sont pas attribuées à des ressources.

Colonne "Champs de ressource"

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

Colonne "Segments"

Tous les champs de segment ne peuvent pas être sélectionnés 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 vers des informations complètes sur le champ, y compris sa description, sa catégorie, son type de données, son type d'URL, ainsi que le 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"

Tous les champs de métriques ne peuvent pas être sélectionnés avec une ressource donnée.

La colonne Metrics (Métriques) répertorie les champs metrics que vous pouvez utiliser dans la même clause SELECT que les champs de la ressource. Chaque champ renvoie vers des informations complètes sur le champ, y compris sa description, sa catégorie, son type de données, son type d'URL, ainsi que le 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 aux devises (par exemple, cost_micros) pour une date ou une plage de dates spécifique, veillez à inclure segments.date dans la clause SELECT.

Segmenter des ressources

Certaines ressources présentent 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 champ de ressource campaign, 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 Segmenter les ressources répertorie 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 extensible pour chaque champ segments. Celui-ci répertorie tous les champs de ressources compatibles, les champs metrics et les autres champs segments que vous pouvez inclure dans votre clause SELECT.

Remarque :Consultez la section Langage de requête Search Ads 360 pour apprendre à utiliser chaque clause d'une requête.

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

Consultez la section segments pour obtenir la liste des champs de segment 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 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 implicitement segmentés 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é en fonction de la ressource spécifiée dans la clause FROM. Les métriques sont segmentées en fonction du champ resource_name de cette ressource

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

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

Vous pouvez utiliser des 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" 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 segments de date principaux constituent 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 l'incluez également dans la clause SELECT. Pour en savoir plus, consultez la section Filtrage interdit.

Règles principales relatives aux segments de dates:

• 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 des 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 plage de dates finie dans votre clause WHERE. Les champs spécifiés dans les clauses SELECT et WHERE n'ont pas besoin de 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 plage de dates.

  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 nécessitant 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 de règles, vous recevrez une erreur MISALIGNED_DATE_FOR_FILTER.

Dates prédéfinies

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

Dates prédéfinies
TODAY	Aujourd'hui seulement.
YESTERDAY	Hier seulement.
LAST_7_DAYS	Les 7 jours précédents, sans compter la journée en cours.
LAST_BUSINESS_WEEK	Semaine ouvrée 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	14 jours précédents (sauf aujourd'hui).
LAST_30_DAYS	30 jours précédents (sauf aujourd'hui)
THIS_WEEK_SUN_TODAY	Règles entre le dimanche précédent et le jour en cours.
THIS_WEEK_MON_TODAY	Période comprise entre le lundi précédent et le jour en cours.
LAST_WEEK_SUN_SAT	période de 7 jours à partir du dimanche précédent.
LAST_WEEK_MON_SUN	période de 7 jours à partir du lundi précédent.

Exemple :

WHERE segments.date DURING LAST_30_DAYS

Aucune métrique

Lorsque vous exécutez une requête, vous pouvez rencontrer des métriques avec une valeur de zéro pour certaines entités. Découvrez comment gérer l'absence de métriques dans vos requêtes.

Types d'énumérations UNKNOWN

Si une ressource est renvoyée avec le type de données enum UNKNOWN, cela signifie que le type n'est pas entièrement compatible avec la version de l'API. Ces ressources peuvent avoir été créées via d'autres interfaces. Par exemple, une nouvelle campagne ou annonce est introduite dans l'interface utilisateur de 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 peut être acceptée 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 vision précise de votre compte. La ressource UNKNOWN peut s'afficher en raison d'une nouvelle activité sur 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.