Métadonnées de ressources

Vous pouvez utiliser GoogleAdsFieldService pour demander dynamiquement le catalogue des ressources, des champs de ressources, des clés de segmentation et des métriques disponibles dans les méthodes Search et SearchStream de GoogleAdsService. Le catalogue fournit des métadonnées qui peuvent être utilisées par les clients de l'API Google Ads pour valider et construire des instructions du langage de requête Google Ads.

Exemple de requête et de réponse HTTP

La requête consiste en un HTTP GET adressé au serveur de l'API Google Ads à l'URL suivante :

https://googleads.googleapis.com/v22/googleAdsFields/{resource_or_field}

L'exemple suivant montre une requête suivie de la réponse renvoyée par GoogleAdsFieldService pour la ressource ad_group :

Requête

https://googleads.googleapis.com/v22/googleAdsFields/ad_group

Réponse

{
  "resourceName": "googleAdsFields/ad_group",
  "name": "ad_group",
  "category": "RESOURCE",
  "selectable": false,
  "filterable": false,
  "sortable": false,
  "selectableWith": [
    "campaign",
    "customer",
    "metrics.average_cpc",
    "segments.device",
    ...
  ],
  "attributeResources": [
    "customer",
    "campaign"
  ],

  "metrics": [
    "metrics.conversions",
    "metrics.search_budget_lost_impression_share",
    "metrics.average_cost",
    "metrics.clicks",
    ...
  ],
  "segments": [
    "segments.date",
    "segments.ad_network_type",
    "segments.device",
    ...
  ]
}

Dans cet exemple, les tableaux importants sont les suivants :

attributeResources

Ressources pouvant être jointes implicitement à la ressource dans la clause FROM.

metrics

Métriques pouvant être sélectionnées avec la ressource dans la clause FROM. Renseigné uniquement pour les champs où category est défini sur RESOURCE.

segments

Clés de segment

pouvant être sélectionnées avec la ressource dans la clause FROM. Ils segmentent les métriques spécifiées dans la requête. Rempli uniquement pour les champs où category est défini sur RESOURCE.

selectableWith

L'attribut selectableWith d'un champ de ressource ou de segment spécifie d'autres ressources, segments ou métriques qui peuvent être sélectionnés dans la même requête GAQL. Cet attribut est essentiel lorsque vous souhaitez inclure des champs provenant d'une ressource ou d'un segment qui n'est pas spécifié dans la clause FROM.

Lorsque vous créez une requête GAQL :

1.  La ressource de la clause FROM est l'entité principale. Vous pouvez toujours sélectionner des champs à partir de cette ressource.
2.  Vous pouvez également sélectionner des métriques et des segments compatibles avec l'entité principale.
3.  Si vous incluez des champs provenant d'une ressource ou d'un segment en dehors de la clause FROM, vous devez vous assurer que cette ressource ou ce segment non FROM est compatible avec tous les autres champs, segments et métriques sélectionnés dans la requête.

La liste selectableWith d'une ressource spécifique (appelons-la Ressource A) contient toutes les autres ressources, tous les autres segments et toutes les autres métriques qui peuvent être sélectionnés en même temps que les champs de la Ressource A lorsque celle-ci n'est pas l'entité principale.

Exemple :

Prenons l'exemple de requête suivant : SELECT ad_group.id, segments.date, campaign.name FROM ad_group

•   La clause FROM spécifie ad_group.

•   Cette requête sélectionne ad_group.id (à partir de la ressource FROM), segments.date et campaign.name.

•   Étant donné que campaign.name est sélectionné, mais que campaign ne l'est pas dans la clause FROM, vous devez vérifier sa compatibilité avec les autres éléments sélectionnés.

•   Pour que cette requête soit valide, la ressource campaign doit être compatible avec segments.date (un autre champ sélectionné). Vous devez donc vérifier l'attribut selectableWith pour la ressource campaign. Si segments.date est présent dans la liste selectableWith de campaign, la requête est valide.

Si vous sélectionnez des champs à partir d'une ressource qui ne figure pas dans la clause FROM, la liste selectableWith de cette ressource doit inclure tous les autres segments et ressources présents dans votre clause SELECT.

Détails des métadonnées

Vous pouvez demander le catalogue à l'aide de GoogleAdsFieldService à ces niveaux :

Ressource

Par exemple, googleAdsFields/campaign.

Champ de la ressource

Par exemple, googleAdsFields/campaign.name.

Champ de segmentation

Par exemple, googleAdsFields/segments.ad_network_type.

Métrique

Par exemple, googleAdsFields/metrics.clicks.