Метаданные ресурса

Вы можете использовать GoogleAdsFieldService для динамического запроса каталога ресурсов, полей ресурсов, ключей сегментации и метрик, доступных в методах Search и SearchStream GoogleAdsService . Каталог предоставляет метаданные, которые клиенты API Google Ads могут использовать для проверки и построения операторов языка запросов Google Ads.

Пример HTTP-запроса и ответа

Запрос состоит из HTTP GET к серверу API Google Ads по следующему URL-адресу:

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

В следующем примере показан запрос, за которым следует ответ, возвращаемый GoogleAdsFieldService для ресурса ad_group :

Запрос

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

Ответ

{
  "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",
    ...
  ]
}

Для этого примера важными массивами являются:

attributeResources

Ресурсы, которые могут быть неявно присоединены к ресурсу в предложении FROM .

metrics

Метрики, которые можно выбрать с ресурсом в предложении FROM . Заполняется только для полей с category RESOURCE .

segments

Ключи сегмента, которые можно выбрать с ресурсом в предложении FROM . Они сегментируют метрики, указанные в запросе. Заполняется только для полей с category RESOURCE .

selectableWith

Атрибут selectableWith поля ресурса или сегмента указывает другие ресурсы, сегменты или метрики, которые можно выбрать в том же запросе GAQL. Этот атрибут имеет решающее значение, если требуется включить поля из ресурса или сегмента, не указанного в предложении FROM .

При построении GAQL-запроса:

1. Ресурс в предложении FROM является первичной сущностью. Вы всегда можете выбрать поля из этого ресурса.
2. Вы также можете выбрать совместимые метрики и сегменты, доступные для основного объекта.
3. Если вы включаете поля из любого ресурса или сегмента за пределами предложения FROM , вы должны убедиться, что этот ресурс или сегмент, не являющийся FROM , совместим со всеми другими полями, сегментами и метриками, выбранными в запросе.

Список selectableWith для определенного ресурса (назовем его Ресурсом А) содержит все остальные ресурсы, сегменты и метрики, которые можно выбрать вместе с полями из Ресурса А, когда Ресурс А не является основной сущностью.

Пример:

Рассмотрим этот пример запроса: SELECT ad_group.id, segments.date, campaign.name FROM ad_group

• Предложение FROM указывает ad_group .

• Этот запрос выбирает ad_group.id (из ресурса FROM ), segments.date и campaign.name .

• Поскольку выбрано campaign.name , но campaign отсутствует в предложении FROM , необходимо проверить его совместимость с другими выбранными элементами.

• Чтобы этот запрос был корректным, ресурс campaign должен быть совместим с segments.date (другим выбранным полем). Поэтому необходимо проверить атрибут selectableWith ресурса campaign . Если segments.date присутствует в списке selectableWith campaign , запрос корректен.

Если вы выбираете поля из ресурса, который не указан в предложении FROM , список selectableWith этого ресурса должен включать все остальные сегменты и ресурсы, присутствующие в предложении SELECT .

Подробности метаданных

Вы можете запросить каталог с помощью GoogleAdsFieldService на следующих уровнях:

Ресурс

Например, googleAdsFields/campaign .

Поле ресурса

Например, googleAdsFields/campaign.name .

Поле сегментации

Например, googleAdsFields/segments.ad_network_type .

Метрическая

Например, googleAdsFields/metrics.clicks .