Structure d'une requête

Les requêtes sur les champs de ressources, de segments et de métriques peuvent être envoyées aux méthodes GoogleAdsService Search ou SearchStream. Pour créer une requête dans le langage de requête Google Ads, vous devez utiliser la grammaire du langage. Une requête est composée de plusieurs clauses:

• SELECT
• FROM
• WHERE
• ORDER BY
• LIMIT
• PARAMETERS

Les clauses utilisent des noms de champs, des noms de ressources, des opérateurs, des conditions et des classements pour vous aider à sélectionner les données correctes. Une fois combinée en une seule requête, une demande peut être effectuée à l'aide de l'API Google Ads.

Important :GoogleAdsFieldService fournit un catalogue pour les clients du langage de requête Google Ads avec des métadonnées sur tous les champs de ressources, les champs de segment et les métriques, ainsi que leurs relations les uns avec les autres et la disponibilité dans chaque clause, comme défini ci-dessous. Pour en savoir plus, consultez la documentation de GoogleAdsField.

Clauses

Vidéo: Compatibilité des champs GAQL

SELECT

La clause SELECT spécifie un ensemble de champs à extraire dans la requête. SELECT utilise une liste de champs de ressources, de champs de segment et de métriques séparés par une virgule, puis renvoie les valeurs dans la réponse. La clause SELECT est obligatoire dans une requête.

L'exemple de requête ci-dessous montre comment sélectionner des attributs pour une ressource donnée:

SELECT
  campaign.id,
  campaign.name
FROM campaign

Vous pouvez demander différents types de champs dans une même requête, par exemple:

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

• Champs de ressource

  • campaign.id
  • campaign.name

• Champs de ressource

  • bidding_strategy.id
  • bidding_strategy.name

• Champs de segment

  • segments.device
  • segments.date

• Métriques

  • metrics.impressions
  • metrics.clicks

Certains champs peuvent ne pas être autorisés dans la clause SELECT en raison des restrictions suivantes:

• Interrogation des champs non sélectionnables L'attribut de métadonnées Selectable de ces champs sera marqué comme false.
• Sélection des attributs de champs répétés. L'attribut de métadonnées isRepeated de ces champs sera marqué comme true.
• Sélectionner des 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. De plus, seul un sous-ensemble de toutes les métriques et de tous les segments sera disponible pour la ressource dans la clause FROM.
• Sélectionner des segments ou des métriques non compatibles entre eux Pour en savoir plus, consultez la section Segmentation.

Vous trouverez des informations concernant les conditions ci-dessus dans notre documentation de référence ou sur la page GoogleAdsFieldService.

FROM

La clause FROM spécifie la ressource principale qui sera renvoyée. La ressource de la clause FROM définit les champs qui peuvent être utilisés dans toutes les autres clauses de la requête donnée. Une seule ressource peut être spécifiée dans la clause FROM. La clause FROM est obligatoire dans les requêtes envoyées aux méthodes GoogleAdsService Search ou SearchStream, mais ne doit pas être spécifiée lorsque vous utilisez GoogleAdsFieldService.

Bien qu'une seule ressource puisse exister dans la clause FROM pour une requête donnée, des champs des ressources attribuées peuvent également être disponibles. Ces ressources sont implicitement associées à la ressource dans la clause FROM. Il vous suffit donc d'ajouter leurs attributs à la clause SELECT pour renvoyer leurs valeurs. Les ressources ne sont pas toutes attribuées à des ressources. Dans l'exemple suivant, vous pouvez demander à la fois l'ID du groupe d'annonces et l'ID de la campagne aux groupes d'annonces:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Le champ resource_name de la ressource principale est toujours renvoyé. Dans l'exemple suivant, 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

Il en va de même pour les autres ressources lorsqu'au moins un champ est sélectionné. Par exemple, campaign.resource_name sera inclus dans la réponse à la requête suivante :

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Important :Si la ressource dans la clause FROM répertorie une autre ressource en tant que segment, la sélection de n'importe quel attribut de cette ressource fera office de segment.

WHERE

La clause WHERE spécifie les conditions à appliquer lors du filtrage des données pour la requête. Lorsque vous utilisez la clause WHERE, vous pouvez spécifier une ou plusieurs conditions à l'aide de AND pour les séparer. Chaque condition doit respecter le format field_name Operator value. La clause WHERE est facultative dans une requête.

Voici un exemple d'utilisation de WHERE pour renvoyer les métriques d'une période donnée:

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

Vous pouvez combiner plusieurs conditions pour filtrer les données. Dans cet exemple, la requête porte sur le nombre de clics pour toutes les campagnes ayant enregistré des 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

Les segments de la clause WHERE doivent figurer dans la clause SELECT, les segments de date suivants, appelés segments de dates principaux, étant des exceptions:

• segments.date
• segments.week
• segments.month
• segments.quarter
• segments.year

Dans la requête suivante, notez que segments.date est sélectionné. Comme ce segment est un segment de date principal, il nécessite de fournir une plage de dates finie composée de segments de dates principaux dans la clause WHERE.

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

Tous les segments qui remplissent la condition ci-dessus sont: segments.date, segments.week, segments.month, segments.quarter et segments.year. Si l'un de ces segments est sélectionné, au moins l'un d'entre eux doit être utilisé dans la clause WHERE.

Important :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").

Lors du filtrage, il est important de garder à l'esprit la sensibilité à la casse de l'opérateur. Pour en savoir plus, consultez Sensibilité à la casse.

Pour obtenir la liste complète des opérateurs, consultez la grammaire du langage.

ORDER BY

La clause ORDER BY spécifie l'ordre dans lequel les résultats doivent être renvoyés. Cela vous permet d'organiser les données dans l'ordre croissant ou décroissant en fonction d'un nom de champ. Chaque tri est spécifié en tant que field_name suivi de ASC ou DESC. Si ni ASC, ni DESC n'est spécifié, la valeur par défaut est ASC. La clause ORDER BY est facultative dans une requête.

La requête suivante trie les campagnes renvoyées par nombre de clics, du plus élevé au moins élevé:

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

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. Le tri aura lieu dans la même séquence que celle spécifiée dans la requête. Par exemple, dans cette requête de sélection des données de groupes d'annonces, les résultats sont triés par ordre croissant par nom de campagne, puis par ordre décroissant du nombre d'impressions, puis par ordre décroissant 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

LIMIT

La clause LIMIT vous permet de spécifier le nombre de résultats à renvoyer. Ceci est utile si seul un résumé vous intéresse.

Par exemple, LIMIT permet de limiter le nombre total de résultats pour la requête suivante:

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

Important :LIMIT vous permet de tronquer les résultats. Utilisez le champ page_size de GoogleAdsService.Search pour gérer de longues listes de résultats.

PARAMÈTRES

La clause PARAMETERS vous permet de spécifier des métaparamètres pour la requête. Ces paramètres peuvent avoir une incidence sur les types de lignes renvoyées.

Actuellement, les métaparamètres suivants sont acceptés:

include_drafts

Définissez include_drafts sur true pour permettre le renvoi d'entités de brouillon. La valeur par défaut est false.

Par exemple, la requête suivante récupère les campagnes brouillons avec les campagnes standards:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

omit_unselected_resource_names

Définissez omit_unselected_resource_names sur true pour éviter que le nom de ressource de chaque type de ressource présent dans la réponse ne soit renvoyé, sauf indication contraire explicite dans la clause SELECT. La valeur par défaut est false.

Remarque :Si vous prévoyez d'utiliser l'un des objets renvoyés pour des opérations de mise à jour ou de suppression, nous vous recommandons de définir cette option sur false, car les ressources sans nom de ressource ne peuvent pas être utilisées dans les opérations mutate. Si vous définissez cette option sur true, assurez-vous de demander explicitement les noms de ressource de la ressource principale et de toutes les ressources d'attribut que vous extrayez à l'aide de la requête.

Exemples d'omettre_unselected_resource_names
SELECT campaign.name, customer.id FROM campaign	Returned resources: campaign.resource_name customer.resource_name omit_unselected_resource_names est défini par défaut sur false. Tous les champs resource_name sont donc renvoyés.
SELECT campaign.name, customer.id FROM campaign PARAMETERS omit_unselected_resource_names = true	Returned resources: Aucun. omit_unselected_resource_names est spécifié, car true, et campaign.resource_name et customer.resource_name ne font pas partie de la clause SELECT.
SELECT campaign.name, campaign.resource_name FROM campaign PARAMETERS omit_unselected_resource_names = true	Returned resource: campaign.resource_name omit_unselected_resource_names est spécifié en tant que true et campaign.resource_name demandés dans la clause SELECT.

Règles supplémentaires concernant les langues

Outre les exemples pour chaque clause, le langage de requête Google Ads présente les comportements suivants:

• Il n'est pas nécessaire que le champ de ressource principal se trouve dans la clause SELECT d'une requête. Par exemple, vous pouvez n'utiliser qu'un ou plusieurs champs de ressources principaux pour filtrer les données:

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

• Les métriques peuvent être exclusivement sélectionnées pour une ressource donnée. Aucun autre champ de la ressource n'est requis dans la requête:

  SELECT
    metrics.impressions,
    metrics.clicks,
    metrics.costMicros
  FROM campaign
  

• Les champs de segmentation peuvent être sélectionnés sans champ de ressource ni métrique associé:

  SELECT segments.device FROM campaign
  

• Le champ resource_name (campaign.resource_name, par exemple) peut être utilisé pour filtrer ou trier les données:

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