Structure d'une requête

Les requêtes sur les champs de ressource, de segment et de métrique peuvent être envoyées à GoogleAdsService Search ou SearchStream méthodes. Pour créer une requête dans le langage de requête Google Ads, vous devez la créer à l'aide de la méthode grammaire du langage. Une requête se compose de plusieurs :

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

Elles utilisent des noms de champ, des noms de ressources, des opérateurs, des conditions et classements pour vous aider à sélectionner les bonnes données. Une fois combinés en un vous pouvez envoyer une demande à l'aide de l'API Google Ads.

Important: Le GoogleAdsFieldService Il fournit un catalogue aux clients utilisant le langage de requête Google Ads, avec des métadonnées sur toutes les ressources champs, champs de segment et paramètres, ainsi que leurs relations avec chacun d'eux et la disponibilité dans chaque clause, comme défini ci-dessous. Pour en savoir plus, consultez la documentation sur GoogleAdsField.

Clauses

Vidéo: Compatibilité des champs GAQL

SELECT

La clause SELECT spécifie un ensemble de champs à extraire dans la requête. SELECT prend une liste de champs de ressource, de champs de segment séparés par une virgule, et les métriques, en renvoyant 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:

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

  • campaign.id
  • campaign.name

• Champs de la ressource

  • bidding_strategy.id
  • bidding_strategy.name

• Champs de segment

  • segments.device
  • segments.date

• Métriques

  • metrics.impressions
  • metrics.clicks

Il est possible que certains champs ne soient pas autorisés dans la clause SELECT pour les raisons suivantes : restrictions:

• Interroger des champs non sélectionnables Ces champs ont leurs valeurs Attribut de métadonnées Selectable marqué comme false.
• Sélection des attributs des champs répétés. Ces champs ont leurs valeurs Attribut de métadonnées isRepeated marqué comme true.
• Sélection des champs qui ne sont pas disponibles pour la ressource donnée dans FROM . Les attributs de certaines ressources ne peuvent pas être sélectionnés ensemble. un sous-ensemble de toutes les métriques et de tous les segments sera disponible pour la ressource dans FROM.
• Sélectionner des segments ou des métriques qui ne sont pas compatibles entre eux Pour Pour en savoir plus, consultez les section sur la segmentation.

Vous trouverez des informations relatives aux conditions ci-dessus dans notre documentation de référence. ou à partir de GoogleAdsFieldService.

FROM

La clause FROM spécifie la ressource principale qui sera renvoyée. La ressource dans la clause FROM définit les champs pouvant être utilisés dans tous les autres pour la requête donnée. Vous ne pouvez spécifier qu'une seule ressource dans le champ FROM. La clause FROM est obligatoire dans une requête envoyée au GoogleAdsService Search ou SearchStream . Toutefois, vous ne devez pas l'indiquer lorsque vous utilisez la méthode GoogleAdsFieldService

Bien qu'une seule ressource puisse exister dans la clause FROM pour une requête donnée, les champs provenant des ressources attribuées peuvent également être disponibles. Ces ressources sont implicitement jointe à la ressource dans la clause FROM. Il vous suffit donc de ajoutez leurs attributs à la clause SELECT pour renvoyer leurs valeurs. Il est possible que ressources ont des ressources attribuées. Dans l'exemple suivant, vous pouvez demander à la fois l'ID du groupe d'annonces et l'ID de la campagne des 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 bien qu'il ne soit 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 pour le la requête suivante:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Important :Si la ressource dans la clause FROM indique une autre ressource en tant que segment, puis la sélection d'un attribut de cette ressource servira de segment.

WHERE

La clause WHERE spécifie les conditions à appliquer lors du filtrage des données pour le 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 suivre le modèle field_name Operator value La clause WHERE est facultative dans une requête.

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

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. Cet exemple va demander le nombre de clics pour toutes les campagnes ayant enregistré des impressions sur mobile dans 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 se trouver dans la clause SELECT, avec le paramètre les plages de dates suivantes, appelées 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 une date finie plage composée de segments de dates principaux dans la clause WHERE à fournir.

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.mois", "segments.trimestres" et "segments.année". Si l'un de ces segments sont sélectionnées, 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 avec une seule condition d'opérateur (WHERE segments.device != "DESKTOP" AND "MOBILE"),

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

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

ORDER BY

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

La requête suivante trie les campagnes renvoyées en fonction du nombre de clics enregistrés par ordre décroissant:

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'un fichier liste. Le tri s'effectuera dans la même séquence que celle spécifiée dans la requête. Par exemple, si cette requête sélectionne les données d'un groupe d'annonces, les résultats sont triés dans l'ordre croissant par nom de campagne, puis dans l'ordre décroissant en fonction du nombre de impressions, puis par nombre de clics 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

LIMIT

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

Par exemple, LIMIT peut être utilisé pour limiter le nombre total de résultats pour la 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. Utiliser le champ page_size de GoogleAdsService.Search à de longues listes de résultats.

PARAMÈTRES

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

Actuellement, les méta-paramètres suivants sont acceptés:

include_drafts

Définissez include_drafts sur true pour autoriser le renvoi des entités brouillons. La valeur par défaut est false.

Par exemple, la requête suivante permet d'extraire des brouillons de campagne campagnes:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

omit_unselected_resource_names

Définissez omit_unselected_resource_names sur true pour empêcher le nom de ressource de que chaque type de ressource dans la réponse soit renvoyé, sauf demande 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 la mise à jour ou la 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 des opérations mutate. Si vous définissez cette option sur true, veillez à demander explicitement les noms de ressources des deux la ressource principale et toutes les ressources d'attribut que vous récupérez à l'aide de la requête.

Exemples omises_unselected_resource_names
SELECT campaign.name, customer.id FROM campaign	Returned resources: campaign.resource_name customer.resource_name La valeur par défaut de omit_unselected_resource_names est false. Tous les champs "resource_name" sont renvoyés.
SELECT campaign.name, customer.id FROM campaign PARAMETERS omit_unselected_resource_names = true	Returned resources: Aucune. omit_unselected_resource_names est spécifié en tant que 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 le cadre SELECT.

Règles supplémentaires concernant les langues

En plus des exemples associés à chaque clause, le langage de requête Google Ads propose les fonctionnalités suivantes : comportements pouvant être utilisés:

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

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

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

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

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

  SELECT segments.device FROM campaign
  

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

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