Metadados do recurso

Você pode usar GoogleAdsFieldService para solicitar dinamicamente o catálogo de recursos, campos de recursos, chaves de segmentação e métricas disponíveis nos métodos GoogleAdsService Search e SearchStream. O catálogo fornece metadados que podem ser usados pelos clientes da API Google Ads para validação e criação de instruções da linguagem de consulta do Google Ads.

Exemplo de solicitação e resposta HTTP

A solicitação consiste em um HTTP GET para o servidor da API Google Ads no seguinte URL:

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

O exemplo a seguir mostra uma solicitação seguida da resposta retornada de GoogleAdsFieldService para o recurso ad_group:

Solicitação

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

Resposta

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

Neste exemplo, as matrizes importantes são:

attributeResources

Recursos que podem ser unidos implicitamente ao recurso na cláusula FROM.

metrics

Métricas que podem ser selecionadas com o recurso na cláusula FROM. Preenchido apenas para campos em que category é RESOURCE.

segments

Chaves de segmento que podem ser selecionadas com o recurso na cláusula FROM. Eles segmentam as métricas especificadas na consulta. Preenchido apenas para campos em que category é RESOURCE.

selectableWith

O atributo selectableWith em um recurso ou campo de segmento especifica outros recursos, segmentos ou métricas que podem ser selecionados na mesma consulta da GAQL. Esse atributo é crucial quando você quer incluir campos de um recurso ou segmento que não está especificado na cláusula FROM.

Ao criar uma consulta GAQL:

1.  O recurso na cláusula FROM é a entidade principal. Você sempre pode selecionar campos desse recurso.
2.  Você também pode selecionar métricas e segmentos compatíveis disponíveis com a entidade principal.
3.  Se você incluir campos de qualquer recurso ou segmento fora da cláusula FROM, verifique se esse recurso ou segmento não FROM é compatível com todos os outros campos, segmentos e métricas selecionados na consulta.

A lista selectableWith de um recurso específico (vamos chamar de Recurso A) contém todos os outros recursos, segmentos e métricas que podem ser selecionados com os campos do Recurso A quando ele não é a entidade principal.

Exemplo:

Considere este exemplo de consulta: SELECT ad_group.id, segments.date, campaign.name FROM ad_group

•   A cláusula FROM especifica ad_group.

•   Essa consulta seleciona ad_group.id (do recurso FROM), segments.date e campaign.name.

•   Como campaign.name está selecionado, mas campaign não está na cláusula FROM, verifique a compatibilidade dele com outros elementos selecionados.

•  Para garantir que essa consulta seja válida, o recurso campaign precisa ser compatível com segments.date (outro campo selecionado). Portanto, verifique o atributo selectableWith do recurso campaign. Se segments.date estiver presente na lista selectableWith de campaign, a consulta será válida.

Se você selecionar campos de um recurso que não está na cláusula FROM, a lista selectableWith desse recurso precisará incluir todos os outros segmentos e recursos presentes na cláusula SELECT.

Detalhes dos metadados

É possível solicitar o catálogo usando o GoogleAdsFieldService nestes níveis:

Recurso

Por exemplo, googleAdsFields/campaign.

Campo do recurso

Por exemplo, googleAdsFields/campaign.name.

Campo de segmentação

Por exemplo, googleAdsFields/segments.ad_network_type.

Métrica

Por exemplo, googleAdsFields/metrics.clicks.