Métadonnées de ressources

Vous pouvez utiliser GoogleAdsFieldService (via GetGoogleAdsField ou SearchGoogleAdsFields) pour demander de manière dynamique le catalogue des ressources, des champs de ressources, des clés de segmentation et des métriques disponibles dans les méthodes GoogleAdsService Search et SearchStream. Le catalogue fournit des métadonnées que les clients de l'API Google Ads peuvent utiliser 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/v25/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/v25/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 de manière implicite à la ressource dans la clause FROM sans segmenter les métriques. Renseigné uniquement pour les champs où category est RESOURCE.

metrics

Métriques

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

segments

Clés de segment

(champs segments.* et ressources de segmentation) pouvant être sélectionnées avec la ressource dans la clause FROM. Ils segmentent les métriques spécifiées dans la requête. Renseigné uniquement pour les champs où category est RESOURCE.

selectableWith

Ressources, segments ou métriques pouvant être sélectionnés dans la même requête du langage de requête Google Ads lorsque cette ressource ou ce segment n'est pas la ressource principale dans la clause FROM.

Compatibilité des requêtes avec 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 du langage de requête Google Ads. 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 du langage de requête Google Ads :

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 disponibles 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 (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é). Par conséquent, vous devez 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 (par nom de ressource avec GetGoogleAdsField ou par requête avec SearchGoogleAdsFields) aux niveaux GoogleAdsFieldCategory suivants :

Ressource (RESOURCE)

Par exemple, googleAdsFields/campaign.

Attribut de ressource (ATTRIBUTE)

Par exemple, googleAdsFields/campaign.name.

Champ de segmentation (SEGMENT)

Par exemple, googleAdsFields/segments.ad_network_type.

Métrique (METRIC)

Par exemple, googleAdsFields/metrics.clicks.