Metadados do recurso

É possível usar GoogleAdsFieldService (por 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 por 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/v25/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/v25/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 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 o 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.

Compatibilidade de consulta com 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 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 da linguagem de consulta do Google Ads:

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 (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, 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 GoogleAdsFieldService (por nome do recurso com GetGoogleAdsField ou consultando com SearchGoogleAdsFields) nestes níveis de GoogleAdsFieldCategory:

Recurso (RESOURCE)

Por exemplo, googleAdsFields/campaign.

Atributo do 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.