La nouvelle API Search Ads 360 Reporting est désormais disponible. Rejoignez le groupe Google searchads-api-announcements pour vous tenir informé des améliorations et versions à venir.

Cette page a été traduite par l'API Cloud Translation.

Structure des requêtes et clauses

Une requête est composée de plusieurs clauses: SELECT, FROM, WHERE, ORDER BY LIMIT et PARAMETERS.

Les clauses utilisent des noms de champ, des noms de ressources, des opérateurs, des conditions, et les classements combinés en une seule requête.

En termes simples, pour créer une requête, vous devez:

Spécifiez une ressource à partir de laquelle récupérer des données.
Ajoutez des champs et des métriques pour définir les données que vous souhaitez renvoyer.
Ajoutez des segments pour regrouper vos résultats.
Ajoutez des ressources attribuées pour joindre implicitement les données de ressources associées.
Filtrez, triez et limitez vos résultats.

Clause `SELECT`

La clause SELECT:

Est une clause obligatoire dans une requête.
Spécifie un ensemble de champs à extraire dans la requête.
Utilise une liste de champs de ressource, de colonnes personnalisées, de colonnes personnalisées variables Floodlight, champs de segment et statistiques, puis renvoie les valeurs des de réponse.

Cet exemple de requête vous montre comment sélectionner les attributs de campaign ressource:

SELECT
  campaign.id,
  campaign.name
FROM campaign

Plusieurs types de champs

Vous pouvez demander différents types de champs dans la même demande.

L'exemple de requête ci-dessous montre une seule requête combinant les éléments suivants:

Champs de ressources: campaign.id, campaign.name, bidding_strategy.id et bidding_strategy.name
Champs de segment: segments.device et segments.date.
Champs de métriques: metrics.impressions et metrics.clicks.

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

Voir Segmentation pour en savoir plus sur la segmentation de vos rapports sur le Réseau de Recherche.

Champ de ressource principal

En règle générale, vous devez inclure votre champ de ressource principal dans le champ SELECT. , mais celle-ci est facultative (non obligatoire).

Cet exemple de requête utilise un champ de ressource principal (ad_group.status) pour filtrer uniquement les résultats.

SELECT campaign.id
FROM ad_group
WHERE ad_group.status = PAUSED

Variables Floodlight personnalisées

Vous pouvez inclure des variables Floodlight personnalisées dans la clause SELECT en utilisant leur .

Dans cet exemple, la requête inclut une variable personnalisée portant l'ID 123454321 pour la variable .

SELECT
  conversion_custom_metrics.id[123454321]
FROM campaign

SELECT
  conversion_custom_dimensions.id[123454321]
FROM campaign

Colonnes personnalisées

Vous pouvez inclure des colonnes personnalisées dans la clause SELECT en utilisant leurs ID.

Dans cet exemple, la requête inclut une colonne personnalisée portant l'ID 12345678 pour la variable .

SELECT
  custom_columns.id[12345678]
FROM campaign

Découvrez comment obtenir des ID de colonnes personnalisées.

Champs de métriques

Vous pouvez sélectionner des champs de métriques pour une ressource donnée sans inclure d'autres de la ressource dans la clause SELECT.

Cet exemple de requête sélectionne les métriques impressions et clicks pour le campaign ressource.

SELECT
  metrics.impressions,
  metrics.clicks
FROM campaign

Consultez metrics pour découvrir liste des champs de métriques que vous pouvez utiliser dans vos requêtes.

Champs "Segments"

Vous pouvez sélectionner des champs de segments sans spécifier de champs de ressources associés ou métriques dans la clause SELECT.

Cet exemple de requête segmente les résultats par appareil.

SELECT segments.device
FROM campaign

Consultez segments pour découvrir de segments que vous pouvez utiliser dans vos requêtes.

Champs interdits

Vous ne pouvez pas utiliser les champs suivants dans la clause SELECT:

Champs non sélectionnables, c'est-à-dire ceux avec les métadonnées Selectable est marqué comme false.
Champs répétés, c'est-à-dire avec l'attribut de métadonnées Repeated marqué comme true.
Champs qui ne sont pas disponibles pour la ressource donnée dans la clause FROM. Les attributs de certaines ressources ne peuvent pas être sélectionnés ensemble. Certaines ressources uniquement pour qu'un sous-ensemble de toutes les métriques et tous les segments soit disponible.
Segments ou métriques incompatibles. Pour en savoir plus, consultez la section Segmentation. des informations.

Consultez la documentation de référence pour : où trouver ces informations pour chaque ressource.

Clause FROM

La clause FROM:

Clause obligatoire pour les requêtes SearchAds360Service (méthodes Search et SearchStream).
Ne doit pas être inclus pour les requêtes destinées à SearchAds360FieldService.
Spécifie la ressource principale renvoyée par la requête.
Vous ne pouvez spécifier qu'une seule ressource.
Définit les champs que vous pouvez utiliser dans toutes les autres clauses de la requête.

Ressources attribuées

Si des ressources attribuées sont disponibles, elles sont implicitement associées au que vous spécifiez dans la clause FROM. Il vous suffit d'ajouter leurs attributs à la clause SELECT pour renvoyer leurs valeurs.

Cet exemple de requête renvoie l'ID du groupe d'annonces et l'ID de la campagne, car campaign est une ressource attribuée de la ressource ad_group.

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Champ `resource_name`

Dans la clause FROM, le champ resource_name de la ressource principale est toujours renvoyé.

Dans cet exemple de requête, ad_group.resource_name sera inclus dans la réponse même si elle n'est pas explicitement sélectionnée dans la requête:

SELECT ad_group.id
FROM ad_group

Le champ resource_name d'une ressource attribuée est affiché lorsqu'au moins un champ est sélectionné.

Dans cet exemple de requête, campaign.resource_name sera inclus dans réponse, car campaign.id est sélectionné:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Clause WHERE

La clause WHERE:

Est une clause facultative d'une requête.
Spécifie les conditions de filtrage et de segmentation des données pour la requête. Les conditions suivent le format suivant: FIELD_NAME OPERATOR VALUE (séparés par les espaces vides).
Peut inclure plusieurs conditions séparées par le séparateur AND.

Cet exemple de requête montre comment utiliser la clause WHERE pour renvoyer impressions pour une période donnée:

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

Voir Segmentation pour en savoir plus sur la segmentation de vos rapports sur le Réseau de Recherche.

Pour en savoir plus sur la spécification de dates, consultez l'article Plages de dates. dans vos requêtes.

Filtrer par champ `resource_name`

Vous pouvez utiliser le champ resource_name pour filtrer ou trier les données.

Cet exemple de requête utilise le champ campaign.resource_name pour filtrer les résultats par une campagne donnée:

SELECT
  campaign.id,
  campaign.name
FROM campaign
WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'

Conditions multiples

Vous pouvez combiner plusieurs conditions pour filtrer vos données.

Cet exemple de requête demande le nombre de métriques clicks pour toutes les campagnes avec des métriques impressions sur mobile au cours des 30 derniers jours.

SELECT
  campaign.id,
  campaign.name,
  segments.device,
  metrics.clicks
FROM campaign
WHERE metrics.impressions > 0
  AND segments.device = MOBILE
  AND segments.date DURING LAST_30_DAYS

Voir Segmentation pour en savoir plus sur la segmentation de vos rapports.

Sensibilité à la casse

Lors du filtrage sur des valeurs de chaîne, la sensibilité à la casse par défaut de chaque opérateur joue un rôle important dans le filtrage correct de vos résultats.

Le tableau suivant indique la sensibilité à la casse par défaut de chaque opérateur.

Sensibilité à la casse par défaut
`=/!=`	`Case sensitive`
`IN/NOT IN`	`Case sensitive`
`LIKE/NOT LIKE`	`Case insensitive`
`CONTAINS (...)`	`Case sensitive`
`REGEXP_MATCH/NOT REGEXP_MATCH`	`Case sensitive`

Vous pouvez utiliser le modificateur (?i) pour modifier la sensibilité par défaut de REGEXP_MATCH et NOT REGEXP_MATCH pour qu'elles ne soient pas sensibles à la casse, par exemple:

SELECT campaign.id
FROM campaign
WHERE campaign.name REGEXP_MATCH "(?i).*test.*"

Consultez la documentation de référence sur la grammaire des requêtes pour obtenir la liste complète des que vous pouvez utiliser pour filtrer vos données.

Segments de dates principaux

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

Vous pouvez utiliser des plages de dates principales dans votre clause WHERE pour spécifier une date ou une heure période.

Cet exemple de requête spécifie DURING LAST_30_DAYS pour le champ segments.date dans la clause WHERE:

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

Voir Segmentation > Segments de dates principaux pour obtenir des des informations sur l'utilisation des plages de dates principales.

Filtrage interdit

Le filtrage n'est pas autorisé:

Dans les champs de segment non sélectionnés, à l'exception des segments de dates principaux.
Sur les champs de tout type de message, à l'exception des champs primitifs (par exemple, Int64Value, StringValue, etc.).
Pour les attributs de champs répétés de n'importe quel type de message, à l'exception des primitives (par exemple, Int64Value, StringValue, etc.).

Clause ORDER BY

La clause ORDER BY:

Est une clause facultative d'une requête.
Spécifie l'ordre dans lequel les résultats sont renvoyés. L'ordre suit ceci motif: FIELD_NAME ORDERING_OPTION (séparés par un espace).
Autorise deux options: ASC (ordre croissant) ou DESC (ordre décroissant). La valeur par défaut est croissant.

Cet exemple de requête classe les campagnes par nombre de clics dans l'ordre décroissant. (ordre décroissant):

SELECT
  campaign.name,
  metrics.clicks
FROM campaign
ORDER BY metrics.clicks DESC

Commandes multiples

Vous pouvez spécifier plusieurs champs dans la clause ORDER BY à l'aide d'un fichier liste. Les résultats seront classés dans l'ordre indiqué dans la section requête.

Cet exemple de requête sélectionne les données d'un groupe d'annonces et classe les résultats par ordre croissant classer par nom de campagne, puis par nombre d'impressions décroissant Puis, par nombre de clics, par ordre décroissant:

SELECT
  campaign.name,
  ad_group.name,
  metrics.impressions,
  metrics.clicks
FROM ad_group
ORDER BY
  campaign.name,
  metrics.impressions DESC,
  metrics.clicks DESC

Combiner les options de tri et de limite

Vous pouvez utiliser les clauses ORDER BY en combinaison avec la clause LIMIT pour affiner vos résultats.

Cet exemple de requête renvoie les cinq campagnes ayant enregistré le plus d'impressions sur au cours des 30 derniers jours:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.impressions DESC
LIMIT 5

Commande interdite

L'ordre n'est pas autorisé:

Par attributs des ressources non sélectionnées.
Par métriques non sélectionnées.
Par segments non sélectionnés.
Pour ces types de champs: <ph type="x-smartling-placeholder">
- MESSAGE
- Champs répétés
- Attributs des champs répétés.

Clause LIMIT

La clause LIMIT:

Est une clause facultative d'une requête.
Vous permet de limiter le nombre de résultats renvoyés par la requête.

Cette clause est utile, par exemple, si vous vous intéressez uniquement à un échantillon et un résumé des résultats.

Cet exemple de requête limite le nombre total de résultats à 50:

SELECT
  campaign.name,
  ad_group.name,
  segments.device,
  metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50

Clause PARAMETERS

La clause PARAMETERS vous permet de spécifier des méta-paramètres pour la requête.

Inclure les brouillons

Le paramètre include_drafts détermine si les entités brouillons sont incluses ou non dans les résultats. La valeur par défaut est false. Définissez-le sur true pour inclure les entités brouillons.

Cet exemple de requête renvoie des campagnes brouillons et standards:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

Omettre les `resource_name` non sélectionnés

Le paramètre omit_unselected_resource_names vous permet d'exclure champ resource_name de toutes les ressources qui ne sont pas explicitement demandées dans votre SELECT. La valeur par défaut est false. Si vous définissez ce paramètre sur true, vous recommandons de demander explicitement le nom de la ressource principale et toutes les ressources attribuées dans votre clause SELECT.

Cet exemple de requête ne renvoie ni le campaign.resource_name, ni les customer.resource_name, car ils ne sont pas inclus dans le champ SELECT. :

SELECT
  campaign.name,
  customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true

Cet exemple de requête renvoie le champ campaign.resource_name, car il s'agit explicitement demandé dans la clause SELECT:

SELECT
  campaign.name,
  campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true

Modifier la devise utilisée dans les métriques

Le paramètre metrics_currency vous permet de spécifier la devise à utiliser. lors du calcul d'une métrique incluse dans votre clause SELECT. Par défaut, la devise locale du compte est utilisée. Si vous définissez cette vous devez utiliser le code de devise à trois caractères ISO 4217. Exemple: USD, EUR.

Cet exemple de requête renvoie la métrique cost_micros dans la devise locale du Google Cloud.

SELECT
  campaign.name,
  metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"

Cet exemple de requête renvoie la métrique cost_micros en pesos chiliens (CLP).

SELECT
  campaign.name,
  metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"
PARAMETERS metrics_currency = "CLP"

En savoir plus

Grammaire des requêtes