Metadados do recurso

Use GoogleAdsFieldService (com GetGoogleAdsField ou SearchGoogleAdsFields) 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 construçã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/v26/googleAdsFields/{resource_or_field}

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

Solicitação

https://googleads.googleapis.com/v26/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 sem segmentar as métricas. Preenchido apenas para campos em que o category é RESOURCE.

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 (campos segments.* e recursos de segmentação) 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

Recursos, segmentos ou métricas que podem ser selecionados na mesma consulta da Linguagem de consulta do Google Ads quando esse recurso ou segmento não é o principal na cláusula FROM.

Consultar compatibilidade com selectableWith

O atributo selectableWith em um campo de recurso ou segmento especifica outros recursos, segmentos ou métricas que podem ser selecionados na mesma consulta da Linguagem de consulta do Google Ads. 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 na Linguagem de consulta do Google Ads:

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

A lista selectableWith de um recurso específico (Recurso A) contém todos os outros recursos, segmentos e métricas que podem ser selecionados com 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, é necessário verificar a compatibilidade com outros elementos selecionados.
• Para garantir que essa consulta seja válida, o recurso campaign precisa ser compatível com segments.date (outro campo que está sendo selecionado). Portanto, é preciso verificar 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 GoogleAdsFieldService (pelo nome do recurso com GetGoogleAdsField ou por consulta com SearchGoogleAdsFields) nestes níveis de GoogleAdsFieldCategory:

Recurso (RESOURCE)

Por exemplo, googleAdsFields/campaign.

Atributo de recurso (ATTRIBUTE)

Por exemplo, googleAdsFields/campaign.name.

Campo de segmentação (SEGMENT)

Por exemplo, googleAdsFields/segments.ad_network_type.

Métrica (METRIC)

Por exemplo, googleAdsFields/metrics.clicks.