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 le Réseau de Recherche dans les annonces sur le Réseau de Recherche. API 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 d'objets en fonction d'une plage de dates.
• Ordonnez les objets en fonction de leurs attributs.
• Filtrez 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ère campaign.id, campaign.name et metrics.clicks, l'API renvoie une SearchAds360Row contenant un objet "campagne" avec ses champs id et name. et un objet metrics dont le champ clicks est 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.

• 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 l'intégralité de la diffusion.

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 le temps nécessaire au réseau aller-retour 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 performances différentes entre les méthodes pour les petits rapports (moins de 10 000 lignes).

La méthode employée n'affecte pas les quotas et limites de votre API: une seule requête ou un seul rapport est est comptabilisée comme une seule 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ée 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 un customer_id et une chaîne query pour SearchAds360Service.SearchStream ou SearchAds360Service.Search de commande.

Remarque :Les exemples ci-dessous illustrent la requête HTTP/JSON sous-jacente. Ceci est utilisé pour 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 demande consiste en un POST HTTP pour 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 de searchStream, inclus 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 qui sont renseignés en fonction des champs demandés dans la clause SELECT de la requête. Attributs non inclus dans le SELECT ne sont pas renseignées dans les objets de la réponse.

Par exemple, la requête ci-dessous renseigne chaque objet SearchAds360Row avec uniquement les campaign.id, campaign.name et campaign.status. D'autres attributs, comme campaign.engine_id ou campaign.bidding_strategy_type sont omis.

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

Documentation de référence

Section Référence inclut toutes les informations dont vous avez besoin pour utiliser correctement chaque artefact. Il y a Une page pour chaque ressource (par exemple, ad_group et campaign Pages segments et metrics afficher la liste de 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 de la ressource comporte les informations suivantes (le cas échéant et approprié), et plus encore:

Ressources attribuées

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

La section Ressources attribuées liste les ressources attribuées disponibles. Non toutes les ressources ont des ressources attribuées.

Colonne "Champs de la ressource"

Tous les champs de la ressource sont inclus dans la colonne Champs de la ressource. Chaque champ "resource" renvoie vers plus de détails sur le champ, y compris ses description, catégorie, type de données, type URL, et filtrable, sélectionnable, triable et répété.

Colonne "Segments"

Il n'est pas possible de sélectionner tous les champs de segment avec une ressource donnée.

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

Colonne des métriques

Il n'est pas possible de sélectionner tous les champs de métriques avec une ressource donnée.

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

Remarque :Lors de l'obtention de métriques liées aux devises (cost_micros, par exemple) pour une valeur ou une plage de dates, veillez à inclure segments.date dans la clause SELECT.

Segmenter des ressources

Certaines ressources incluent des champs de ressources segmentés que vous pouvez sélectionner la ressource se trouve dans la clause FROM. Par exemple, si vous sélectionnez un champ de ressource campaign, comme campaign.name, lorsque en utilisant campaign_budget dans votre clause FROM, campaign.resource_name sera automatiquement renvoyée et segmentée, car campaign est un la ressource de segmentation de campaign_budget.

La section Segmenter les ressources répertorie les ressources de segmentation disponibles. Non toutes les ressources sont segmentées.

Sélectionnable avec

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

Page segments inclut une option Sélectionnable pouvant être développée pour chaque champ segments qui Répertorie tous les champs de ressource compatibles, les champs metrics et les autres champs segments que vous pouvez inclure dans votre clause SELECT.

Remarque :Consultez la page 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 à la clause SELECT de votre requête.

Par exemple, segments.device dans le 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 ont un aspect comme suit:

{
  "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 découvrir 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 segments que vous ajoutez à votre requête.

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

Par exemple, la requête suivante renverra 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 instance de l'instance principale ressource, mais pas en fonction des valeurs de chaque champ sélectionné.

L'exemple de requête suivant renvoie 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 le 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. Voir Champ resource_name pour en savoir plus informations.

Cet exemple de requête renvoie automatiquement ad_group.resource_name et implicitement l'utilise pour segmenter les métriques au niveau des 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 plages de dates principales dans votre clause WHERE pour spécifier une date ou 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 principaux des plages de dates font exception à la règle générale selon laquelle ne peut pas utiliser de champ de segments dans votre clause WHERE, sauf si vous incluez également le dans votre clause SELECT. Pour en savoir plus, consultez la section Filtrage interdit. des informations.

Principales règles relatives aux segments de dates:

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

  Cet exemple de requête renvoie des métriques clicks par nom de campagne pour la date sélectionnée la plage d'adresses IP. 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 un une date ou une plage de dates limitée dans votre clause WHERE. Les champs spécifiés dans le Les clauses SELECT et WHERE n'ont pas besoin de correspondre.

  Cet exemple de requête renvoie clicks métriques par nom de campagne segmenté 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 plages de dates principales qui nécessitent une période (segments.week, segments.month, segments.quarter), vous pouvez utiliser l'opérateur = avec 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 des règles, vous recevez 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 derniers jours, sans compter aujourd'hui.
LAST_BUSINESS_WEEK	La 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	Au cours des 14 derniers jours, sauf aujourd'hui.
LAST_30_DAYS	Au cours des 30 derniers jours, sauf aujourd'hui.
THIS_WEEK_SUN_TODAY	Période comprise 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 sept jours à compter du dimanche précédent.
LAST_WEEK_MON_SUN	Période de 7 jours à compter 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 égale à zéro pour certaines entités. Découvrez comment gérer zéro métrique 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 peuvent comporter via d'autres interfaces. Par exemple, une nouvelle campagne ou annonce Présentée dans l'interface utilisateur de Search Ads 360, mais pas encore prise en charge dans 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 gardez à l'esprit ce qui suit:

• Une ressource de type UNKNOWN peut être acceptée ultérieurement, mais elle pourrait rester UNKNOWN indéfiniment.
• De nouveaux objets de type UNKNOWN peuvent apparaître à tout moment. Ces objets sont rétrocompatible, car la valeur d'énumération est déjà disponible. Nous présentons de vos ressources au fur et à mesure qu'elles sont disponibles. de votre compte. La ressource UNKNOWN peut s'afficher en raison de nouveaux l'activité de votre compte via d'autres interfaces ou parce qu'une ressource n'est plus officiellement prise en charge.
• UNKNOWN ressources peuvent être associées à des métriques détaillées que vous pouvez requête.
• Les ressources UNKNOWN sont généralement entièrement visibles dans l'interface utilisateur de Search Ads 360.