Lenguaje de búsqueda de Google Ads

Terminología clave

Recurso
Es una entidad en Google Ads, como campaign o ad_group.
Segmentar
Es una dimensión que se usa para agrupar datos, como segments.date o segments.device. Cuando se incluyen segmentos en la cláusula SELECT con métricas, las métricas se dividen por segmento.
Métrica
Es una medición del rendimiento, como metrics.impressions o metrics.clicks.
Recurso atribuido
Es un recurso que se une de forma implícita al recurso principal en la cláusula FROM, lo que te permite seleccionar sus atributos junto con los atributos del recurso principal.

Consulta información sobre recursos o metadatos

El lenguaje de consulta de Google Ads puede consultar la API de Google Ads para los siguientes tipos de información:

  • Recursos y sus atributos, segmentos y métricas relacionados con GoogleAdsService Search o SearchStream: El resultado de una consulta de GoogleAdsService es una lista de GoogleAdsRow instancias, en la que cada GoogleAdsRow representa un recurso.

    Si se solicitan atributos o métricas, la fila también incluye esos campos. Si se solicitan segmentos, la respuesta también muestra una fila adicional para cada tupla de segmento-recurso.

  • Metadatos sobre los campos y recursos disponibles en GoogleAdsFieldService: Este servicio proporciona un catálogo de campos consultables con detalles sobre su compatibilidad y tipo.

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

Para obtener más detalles sobre la estructura de las consultas, consulta Estructura de consulta y Gramática del lenguaje de consulta de Google Ads.

Consulta atributos de recursos

Este es un ejemplo de una consulta básica de 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 ordena por ID de campaña. Cada GoogleAdsRow resultante representa un objeto campaign propagado con los campos seleccionados, incluido el resource_name de la campaña.

Para saber qué otros campos están disponibles para las consultas de campañas, consulta la Campaign documentación de referencia.

Consulta métricas

Junto con los atributos seleccionados para un recurso determinado, también puedes consultar las 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 un estado de PAUSED y que tuvieron más de 1,000 impresiones, mientras que ordena por ID de campaña. Cada GoogleAdsRow resultante tendría un campo metrics propagado con las métricas seleccionadas.

Para obtener una lista de las métricas consultables, consulta la Metrics documentación.

Consulta segmentos

Junto con los atributos seleccionados para un recurso determinado, también puedes consultar los 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 cuando se consultan métricas, esta consulta filtra solo las campañas que tienen un estado de PAUSED y que tuvieron más de 1,000 impresiones. Sin embargo, esta consulta segmenta los datos por fecha. Esto hace que cada GoogleAdsRow resultante represente una tupla de una campaña y la fecha Segment. La segmentación divide las métricas seleccionadas y las agrupa por cada segmento en la cláusula SELECT.

Para obtener una lista de los segmentos consultables, consulta la Segments documentación.

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

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

Esta consulta no solo selecciona atributos de la campaña, sino que también incluye atributos relacionados de cada campaña seleccionada. Cada GoogleAdsRow resultante representa un objeto campaign propagado con los atributos de campaña seleccionados, así como el atributo de estrategia de ofertas seleccionado bidding_strategy.name.

Para saber qué recursos atribuidos están disponibles para las consultas de campañas, consulta la documentación de referencia de Campaign.

Prácticas recomendadas

  • Selecciona solo los campos que necesitas para evitar tiempos de respuesta largos y tiempos de espera.
  • Usa LIMIT durante el desarrollo y las pruebas para evitar el procesamiento de conjuntos de resultados grandes.
  • Aplica filtros en la cláusula WHERE para minimizar la transferencia de datos y el tamaño de la respuesta.
  • Usa GoogleAdsFieldService para verificar la compatibilidad de los campos y los tipos de datos antes de crear consultas complejas.
  • Ten en cuenta que algunos campos, en especial aquellos que implican grandes cantidades de datos o cálculos complejos, pueden aumentar el costo de la consulta.

Realiza mutaciones en función de los resultados de las consultas

Cuando consultas un recurso determinado, puedes tomar de inmediato esos resultados que se muestran como objetos, modificarlos y enviarlos de vuelta al método de mutación en el servicio de ese recurso. Este es un flujo de trabajo de muestra: 1. Ejecuta una consulta para todas las campañas que actualmente están en estado PAUSED y que tienen más de 1,000 impresiones. 1. Obtén el objeto Campaign del campo campaign de cada GoogleAdsRow en la respuesta. 1. Cambia el estado de cada campaña de PAUSED a ENABLED. 1. Llama a CampaignService.MutateCampaigns con las campañas modificadas para actualizarlas.

Metadatos de campos

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 juntos en una consulta. Dado que los datos están disponibles en la API y proporcionan los metadatos necesarios para validar o crear una consulta, esto permite que los desarrolladores lo hagan de forma programática. Esta es 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 los campos consultables, consulta la GoogleAdsField documentación.

Ejemplos de código

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

Siguiente
Gramática de consulta