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
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
.
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 ressourcecampaign
est une ressource attribuée à la ressourcead_group
. Cela signifie que vous pouvez inclure des champs tels quecampaign.id
etcampaign.bidding_strategy_type
dans votre requête lorsque vous utilisezad_group
dans la clauseFROM
.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 clauseSELECT
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 clauseFROM
, 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 clauseSELECT
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 clauseFROM
, utilisez le menu déroulant Oui/Non pour filtrer les métriques qui ne sont pas disponibles.
- 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 ressourcecampaign
, tel quecampaign.name
, lorsque vous utilisezcampaign_budget
dans votre clauseFROM
,campaign.resource_name
est automatiquement renvoyé et segmenté, carcampaign
est une ressource de segmentation decampaign_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 champsegments
. Celui-ci répertorie tous les champs de ressources compatibles, les champsmetrics
et les autres champssegments
que vous pouvez inclure dans votre clauseSELECT
.
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
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
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 clauseSELECT
. 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 quesegments.date
n'est pas inclus dans la clauseSELECT
.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 clauseWHERE
. Les champs spécifiés dans les clausesSELECT
etWHERE
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'
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 resterUNKNOWN
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 ressourceUNKNOWN
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.