Métadonnées de ressources

Vous pouvez utiliser GoogleAdsFieldService (via GetGoogleAdsField ou SearchGoogleAdsFields) pour demander de manière dynamique le catalogue de ressources, de champs de ressources, de clés de segmentation et de métriques disponibles dans les méthodes GoogleAdsService Search et SearchStream. Le catalogue fournit des métadonnées qui peuvent être utilisées par les clients d'API Google Ads pour valider et créer des instructions en langage de requête Google Ads.

Exemple de requête et de réponse HTTP

Remarque : L'exemple montre la requête HTTP/JSON sous-jacente à titre indicatif, mais nous vous recommandons vivement d'utiliser l'une des bibliothèques clientes basées sur gRPC pour envoyer vos requêtes.

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

https://googleads.googleapis.com/v26/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/v26/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 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 Google Ads Query Language lorsque cette ressource ou ce segment n'est pas la ressource principale de 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 pouvant être sélectionnés dans la même requête Google Ads Query Language. Cet attribut est crucial lorsque vous souhaitez inclure des champs d'une ressource ou d'un segment qui n'est pas spécifié dans la clause FROM.

Lorsque vous créez une requête en langage de requête Google Ads :

1. La ressource de la clause FROM est l'entité principale. Vous pouvez toujours sélectionner des champs 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 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, segments et métriques pouvant être sélectionnés avec 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.
• Comme campaign.name est sélectionné, mais que campaign ne figure 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 de 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 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 (soit par nom de ressource avec GetGoogleAdsField, soit en interrogeant 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.