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 API de Google Ads pueden usar para validar y construir sentencias del lenguaje de consulta de Google Ads.

Ejemplo de solicitud y respuesta HTTP

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

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

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

Solicitud

https://googleads.googleapis.com/v26/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

Son 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 el category es RESOURCE.

metrics

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

segments

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

selectableWith

Son los recursos, los segmentos o las métricas que se pueden seleccionar en la misma consulta del lenguaje de consulta de Google Ads cuando este recurso o segmento no es el recurso principal en la cláusula FROM.

Compatibilidad de consultas con selectableWith

El atributo selectableWith de un campo de recurso o segmento especifica otros recursos, segmentos o métricas que se pueden seleccionar en la misma consulta del lenguaje de búsqueda 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 en el 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 este recurso o segmento que no es FROM sea compatible con todos los demás campos, segmentos y métricas que se seleccionan en la consulta.

La lista selectableWith de 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.
• Debido a que 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 consulta sea válida, el recurso campaign debe ser compatible con segments.date (otro campo que se selecciona). Por lo tanto, debes verificar el atributo selectableWith del recurso campaign. Si segments.date está presente en la lista selectableWith de campaign, la consulta es válida.

Si seleccionas campos de un recurso que no está en la cláusula FROM, la lista 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 con una consulta con SearchGoogleAdsFields) en estos niveles de GoogleAdsFieldCategory:

Recurso (RESOURCE)

Por ejemplo, googleAdsFields/campaign.

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