Metadatos de recursos

Puedes usar GoogleAdsFieldService (a través de GetGoogleAdsField o SearchGoogleAdsFields) para solicitar de forma dinámica el catálogo de recursos, los campos de recursos, las claves de segmentación y las métricas disponibles en los métodos GoogleAdsService Search y SearchStream. El catálogo proporciona metadatos que los clientes de la API de Google Ads pueden usar para validar y crear instrucciones del lenguaje de consulta de Google Ads.

Ejemplo de solicitud y respuesta HTTP

La solicitud consta de un HTTP GET al servidor de la API de Google Ads en la siguiente URL:

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

En el siguiente ejemplo, se muestra una solicitud seguida de la respuesta que devolvió GoogleAdsFieldService para el recurso ad_group:

Solicitud

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

Respuesta

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

En este ejemplo, los arrays importantes son los siguientes:

attributeResources

Recursos que se pueden unir de forma implícita al recurso en la cláusula FROM sin segmentar las métricas. Solo se completa para los campos en los que category es RESOURCE.

metrics

Son las métricas que se pueden seleccionar con el recurso en la cláusula FROM. Solo se completa para los campos en los que category es RESOURCE.

segments

Son las claves de segmentación (campos segments.* y recursos de segmentación) que se pueden seleccionar con el recurso en la cláusula FROM. Estos campos segmentan las métricas especificadas en la consulta. Solo se completa para los campos en los que category es RESOURCE.

selectableWith

Recursos, segmentos o métricas que se pueden seleccionar en la misma consulta del Lenguaje de consultas de Google Ads cuando este recurso o segmento no es el recurso principal en la cláusula FROM.

Compatibilidad de la consulta con selectableWith

El atributo selectableWith en un campo de recurso o segmento especifica otros recursos, segmentos o métricas que se pueden seleccionar en la misma consulta del lenguaje de consultas de Google Ads. Este atributo es fundamental cuando deseas incluir campos de un recurso o segmento que no se especifica en la cláusula FROM.

Cuando construyas una consulta del lenguaje de consulta de Google Ads, ten en cuenta lo siguiente:

1. El recurso en la cláusula FROM es la entidad principal. Siempre puedes seleccionar campos de este recurso.
2. También puedes seleccionar métricas y segmentos compatibles que estén disponibles con la entidad principal.
3. Si incluyes campos de cualquier recurso o segmento fuera de la cláusula FROM, debes asegurarte de que ese recurso o segmento que no es FROM sea compatible con todos los demás campos, segmentos y métricas que se seleccionen en la consulta.

La lista de selectableWith para un recurso específico (recurso A) contiene todos los demás recursos, segmentos y métricas que se pueden seleccionar junto con los campos del recurso A cuando este no es la entidad principal.

Ejemplo

Considera esta consulta de ejemplo:

SELECT ad_group.id, segments.date, campaign.name FROM ad_group

• La cláusula FROM especifica ad_group.
• Esta consulta selecciona ad_group.id (del recurso FROM), segments.date y campaign.name.
• Como se seleccionó campaign.name, pero campaign no está en la cláusula FROM, debes verificar su compatibilidad con otros elementos seleccionados.
• Para garantizar que esta búsqueda sea válida, el recurso campaign debe ser compatible con segments.date (otro campo seleccionado). Por lo tanto, debes verificar el atributo selectableWith del recurso campaign. Si segments.date está presente en la lista selectableWith de campaign, la búsqueda es válida.

Si seleccionas campos de un recurso que no está en la cláusula FROM, la lista de selectableWith de ese recurso debe incluir todos los demás segmentos y recursos presentes en tu cláusula SELECT.

Detalles de los metadatos

Puedes solicitar el catálogo con GoogleAdsFieldService (ya sea por nombre de recurso con GetGoogleAdsField o por consulta con SearchGoogleAdsFields) en estos niveles de GoogleAdsFieldCategory:

Recurso (RESOURCE)

Por ejemplo, googleAdsFields/campaign.

Atributo del recurso (ATTRIBUTE)

Por ejemplo, googleAdsFields/campaign.name.

Campo de segmentación (SEGMENT)

Por ejemplo, googleAdsFields/segments.ad_network_type.

Métrica (METRIC)

Por ejemplo, googleAdsFields/metrics.clicks.