Idioma de consulta de Google Ads

El lenguaje de consulta de Google Ads puede realizar consultas en la API de Google Ads

Recursos y sus atributos, segmentos y métricas relacionados mediante
GoogleAdsService Búsqueda o SearchStream
El resultado de una consulta de Google AdsService es una lista de instancias de GoogleAdsRow, y cada GoogleAdsRow representa un recurso. Si se solicitan atributos o métricas, la fila también incluirá esos campos. Si se solicita algún segmento, la respuesta también mostrará una fila adicional para cada tupla de recursos de segmentos.
Metadatos sobre campos y recursos disponibles en
GoogleAdsFieldService

Este servicio brinda un catálogo de campos que pueden consultarse con información específica sobre su compatibilidad y tipo.

El resultado de una consulta GoogleAdsFieldService es una lista de instancias de GoogleAdsField, y cada GoogleAdsField contiene detalles sobre el campo solicitado.

Consulta atributos de un recurso

A continuación, se muestra una consulta básica de los atributos del recurso de campaña, que ilustra cómo mostrar el ID, el nombre y el estado de la campaña:

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign
ORDER BY campaign.id

Esta consulta se ordena por ID de campaña. Cada GoogleAdsRow resultante representaría un objeto campaign propagado con los campos seleccionados (incluido ese resource_name de la campaña).

A fin de descubrir qué otros campos están disponibles para las búsquedas de campañas, consulta la documentación de referencia de Campaign.

Consulta métricas

Además de los atributos seleccionados para un recurso determinado, también puedes consultar métricas relacionadas:

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
ORDER BY campaign.id

Esta consulta filtra solo las campañas que tienen el estado PAUSED y tienen más de 1,000 impresiones, y se ordenan según el ID de la campaña. Cada GoogleAdsRow resultante tendrá un campo metrics propagado con las métricas seleccionadas.

Para obtener una lista de métricas que se pueden consultar, consulta la documentación de Metrics.

Consulta segmentos

Además de los atributos seleccionados para un recurso determinado, también puedes consultar segmentos relacionados:

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions,
  segments.date,
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
  AND segments.date during LAST_30_DAYS
ORDER BY campaign.id

Al igual que con la consulta de métricas, esta consulta filtra solo las campañas que tienen el estado PAUSED y tuvieron más de 1,000 impresiones. Sin embargo, esta consulta segmenta los datos por fecha. Esto genera que cada GoogleAdsRow resultante represente una tupla de una campaña y la fecha Segment. Es importante tener en cuenta que la segmentación divide las métricas seleccionadas y las agrupa por cada segmento en la cláusula SELECT.

Para obtener una lista de segmentos que se pueden consultar, consulta la documentación de Segments.

En una consulta para un recurso determinado, es posible que puedas unirte con otros recursos relacionados si están disponibles. Estos recursos relacionados se conocen como recursos atribuidos. Puedes unir recursos atribuidos de manera implícita si seleccionas un atributo en tu consulta.

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  bidding_strategy.name
FROM campaign
ORDER BY campaign.id

Esta consulta selecciona atributos de campaña y también extrae atributos relacionados de cada campaña seleccionada. Cada GoogleAdsRow resultante representa un objeto campaign propagado con los atributos de campaña seleccionados y el atributo de estrategia de oferta bidding_strategy.name seleccionado.

A fin de saber qué recursos atribuidos están disponibles para las búsquedas de las campañas, consulta la documentación de referencia de Campaign.

Mutación basada en los resultados de la consulta

Cuando realizas una consulta para un recurso determinado, puedes tomar de inmediato los resultados que se muestran como objetos, modificarlos y enviarlos al método de mutación de ese recurso. A continuación, se incluye un flujo de trabajo de muestra:

  1. Ejecuta una consulta para todas las campañas que están actualmente PAUSED y tienen impresiones superiores a 1,000.
  2. Obtén el objeto Campaign del campo campaign de cada GoogleAdsRow en la respuesta.
  3. Cambie el estado de cada campaña de PAUSED a ENABLED.
  4. Llama a CampaignService.MutateCampaigns con las campañas modificadas para actualizarlas.

Metadatos de campo

Las consultas enviadas a GoogleAdsFieldService están destinadas a recuperar metadatos de campos. Esta información se puede usar para comprender cómo se pueden usar los campos en conjunto en una consulta. Dado que los datos están disponibles en la API y proporcionan los metadatos necesarios para validar o compilar una consulta, esto permite que los desarrolladores lo hagan de manera programática. A continuación, se detalla una consulta típica de metadatos:

SELECT
  name,
  category,
  selectable,
  filterable,
  sortable,
  selectable_with,
  data_type,
  is_repeated
WHERE name = "<INSERT_RESOURCE_OR_FIELD>"

Puedes reemplazar <INSERT_RESOURCE_OR_FIELD> en esta consulta por un recurso (como customer o campaign) o un campo (como campaign.id, metrics.impressions o ad_group.id).

Para obtener una lista de campos que se pueden consultar, consulta la documentación de GoogleAdsField.

Ejemplos de código

Las bibliotecas cliente tienen ejemplos del uso del lenguaje de consulta de Google Ads en GoogleAdsService. La carpeta de operaciones básicas tiene ejemplos como GetCampaigns, GetKeywords y SearchForGoogleAdsFields. La carpeta reporting tiene un ejemplo de GetKeywordStats.

Siguiente
Gramática de consulta