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 ressource, des opérateurs, des conditions et des tris qui se combinent en une seule requête.

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

• spécifier une ressource à partir de laquelle récupérer des données ;
• ajouter des champs et des métriques pour définir les données que vous souhaitez afficher ;
• ajouter des segments pour regrouper vos résultats ;
• ajouter des ressources attribuées pour joindre implicitement les données de ressources associées ;
• filtrer, trier et limiter 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 métriques et de champs de segment, de colonnes personnalisées et de variables Floodlight personnalisées séparés par une virgule, renvoyant les valeurs dans la réponse.

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

SELECT
  campaign.id,
  campaign.name
FROM campaign

Plusieurs types de champs

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

L'exemple de requête ci-dessous présente une seule requête avec une combinaison des éléments suivants :

• Champs de ressource : 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

Pour en savoir plus sur la segmentation de vos rapports de recherche, consultez Segmentation.

Champ de ressource principal

En règle générale, vous incluez le champ de ressource principal dans la clause SELECT, mais cela est facultatif (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 à l'aide de leurs ID.

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

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 à l'aide de leurs ID.

Dans cet exemple, la requête inclut une colonne personnalisée avec l'ID 12345678 pour la ressource de campagne.

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 champs de la ressource dans la clause SELECT.

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

SELECT
  metrics.impressions,
  metrics.clicks
FROM campaign

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

Champs de segments

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

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

SELECT segments.device
FROM campaign

Consultez segments pour obtenir la liste des champs 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 les champs dont l'attribut de métadonnées Selectable est défini sur false.

• Champs répétés, c'est-à-dire les champs dont l'attribut de métadonnées Repeated est défini sur 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 ne mettent à disposition qu'un sous-ensemble de toutes les métriques et de tous les segments.

• Segments ou métriques incompatibles. Pour en savoir plus, consultez Segmentation.

Pour savoir où trouver ces informations pour chaque ressource, consultez la documentation de référence.

Clause FROM

La clause FROM :

• est une clause obligatoire pour les requêtes adressées à SearchAds360Service (méthodes Search et SearchStream) ;

• ne doit pas être incluse pour les requêtes adressées à SearchAds360FieldService.

• spécifie la ressource principale renvoyée par la requête ;

• ne peut spécifier qu'une seule ressource ;

• définit les champs que vous pouvez utiliser dans toutes les autres clauses de la requête.

Remarque : Un champ de sélection Oui/Non est disponible sur chaque page de ressource de la section Référence. Il permet de filtrer les champs de ressources, les champs de segments et les champs de métriques qui ne peuvent pas être utilisés lorsqu'une ressource est spécifiée dans la clause FROM.

Ressources attribuées

Si des ressources attribuées sont disponibles, elles sont jointes implicitement à la ressource 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 à la fois 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

Remarque : Toutes les ressources ne disposent pas de ressources attribuées. La section Référence inclut des informations sur les ressources attribuées disponibles avec chaque ressource.

Champ resource_name

Le champ resource_name de la ressource principale dans la clause FROM est toujours renvoyé.

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

SELECT ad_group.id
FROM ad_group

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

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

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Remarque : Si la ressource de la clause FROM répertorie une autre ressource en tant que segment, la sélection d'attributs de cette ressource agit comme un segment.

Clause WHERE

La clause WHERE :

• est une clause facultative dans une requête ;

• spécifie les conditions de filtrage et de segmentation des données pour la requête. Les conditions suivent ce modèle : FIELD_NAME OPERATOR VALUE (séparés par des espaces).

• 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 les métriques impressions pour une période donnée :

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

Pour en savoir plus sur la segmentation de vos rapports de recherche, consultez Segmentation.

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

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 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

Remarque : Le séparateur AND ne peut être utilisé qu’entre des conditions d’opérateur (WHERE segments.device != "DESKTOP" AND segments.device != "MOBILE"), et non au sein d’une même condition d’opérateur (WHERE segments.device != "DESKTOP" AND "MOBILE").

Pour en savoir plus sur la segmentation de vos rapports, consultez Segmentation.

Sensibilité à la casse

Lorsque vous filtrez sur les valeurs de chaîne, la sensibilité à la casse par défaut de chaque opérateur joue un rôle important pour filtrer correctement 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 afin qu'elle ne soit pas sensible à la casse. Exemple :

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

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

Segments de date 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 segments de date principaux dans votre clause WHERE pour spécifier une date ou une 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

Pour en savoir plus sur l'utilisation des segments de date principaux, consultez Segmentation > Segments de date principaux.

Filtrage interdit

Le filtrage n'est pas autorisé :

• sur les champs de segments non sélectionnés, à l'exception des segments de date principaux.

• sur les champs de tout type de message, à l'exception des types primitifs (par exemple, Int64Value, StringValue, etc.) ;

• sur les attributs des champs répétés de tout type de message, à l'exception des types primitifs (par exemple, Int64Value, StringValue, etc.).

Clause ORDER BY

La clause ORDER BY :

• est une clause facultative dans une requête ;
• spécifie l'ordre dans lequel les résultats sont affichés. Le tri suit ce modèle : FIELD_NAME ORDERING_OPTION (séparés par un espace).
• autorise deux options : ASC (croissant) ou DESC (décroissant). La valeur par défaut est croissante.

Cet exemple de requête trie les campagnes par nombre de clics par ordre décroissant (du plus élevé au plus faible) :

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

Plusieurs tris

Vous pouvez spécifier plusieurs champs dans la clause ORDER BY à l'aide d'une liste d'éléments séparés par une virgule. Les résultats seront triés dans la même séquence que celle spécifiée dans la requête.

Cet exemple de requête sélectionne les données du groupe d'annonces et trie les résultats par ordre croissant en fonction du nom de la campagne, puis par ordre décroissant en fonction du nombre d'impressions, puis par ordre décroissant en fonction du nombre de clics :

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

Combiner le tri et la limite

Vous pouvez utiliser la clause 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 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

Tri interdit

Le tri n'est pas autorisé :

• par attributs de ressources non sélectionnées ;
• par métriques non sélectionnées ;
• par segments non sélectionnés ;
• pour les types de champs suivants :
  • MESSAGE
  • Champs répétés
  • Attributs de champs répétés.

Clause LIMIT

La clause LIMIT :

• est une clause facultative dans 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 ne souhaitez obtenir qu'un échantillon ou 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 brouillons

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

Cet exemple de requête renvoie à la fois les campagnes brouillons et les campagnes standards :

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

Omettre resource_name non sélectionné

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

Cet exemple de requête ne renvoie ni le champ campaign.resource_name, ni le champ customer.resource_name, car ils ne sont pas inclus dans la clause 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 est 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 du compte spécifié par customer_id est utilisée. Si vous définissez ce paramètre, vous devez utiliser le code de devise à trois lettres ISO 4217. Exemple : USD, EUR.

Cet exemple de requête renvoie la métrique cost_micros dans la devise du compte spécifié par le customer_id.

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"

Activer l'expansion des comptes MCC

Lorsque le paramètre enable_mcc_expansion est défini sur "true", il vous permet d'inclure des métriques, des champs et des segments de tous les comptes associés à customer_id, pour la ressource de la clause FROM. La réponse utilisera la devise du customer_id, sauf si elle est explicitement spécifiée dans le paramètre metrics_currency.

Remarque : Le paramètre enable_mcc_expansion n'est compatible qu'avec bidding_strategy. L'API inclura des ressources supplémentaires au fil du temps.

Cet exemple de requête renvoie bidding_strategy.name, bidding_strategy.type et metrics.cost_micros de tous les comptes de la hiérarchie de comptes associés à customer_id, car le paramètre enable_mcc_expansion est défini sur true.

SELECT
  bidding_strategy.name,
  bidding_strategy.type,
  metrics.cost_micros
FROM bidding_strategy
WHERE segments.date DURING LAST_14_DAYS
PARAMETERS enable_mcc_expansion = true

En savoir plus

• Grammaire des requêtes