Lenguaje de búsqueda de Google Ads

El lenguaje de consulta de Google Ads puede consultar la API de Google Ads para obtener la siguiente 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 instancias de GoogleAdsRow, cada una de las cuales representa un recurso.GoogleAdsRow Si se solicitan atributos o métricas, la fila también incluye esos campos. Si se solicita algún segmento, 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, cada una de las cuales contiene detalles sobre el campo solicitado.GoogleAdsField

Cómo consultar los atributos de un recurso

A continuación, se muestra una consulta básica para 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 ordena los datos por ID de campaña. Cada GoogleAdsRow resultante representaría un objeto campaign propagado con los campos seleccionados (incluido el resource_name de esa campaña determinada).

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

Cómo consultar métricas

Además de 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 se ordenan 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 documentación de Metrics.

Cómo consultar 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 las consultas de 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. 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 consultables, consulta la documentación de Segments.

En una consulta de un recurso determinado, es posible que puedas unirte a otros recursos relacionados si están disponibles. Estos recursos relacionados se conocen como “recursos asignados”. Para unirte a recursos atribuidos de forma implícita, selecciona 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 los atributos de la campaña, sino que también extrae los atributos relacionados de cada campaña seleccionada. Cada GoogleAdsRow resultante representa un objeto campaign propagado con los atributos de la campaña seleccionados, así como el atributo bidding_strategy.name de la estrategia de ofertas seleccionada.

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

Cómo realizar mutaciones en función de los resultados de la consulta

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. A continuación, se muestra un flujo de trabajo de ejemplo:

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

Metadatos de campos

Las consultas que se envían a GoogleAdsFieldService están destinadas a recuperar metadatos de campo. 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 desde la API y proporcionan los metadatos necesarios para validar o compilar 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 campos consultables, 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 operaciones básicas tiene ejemplos como GetCampaigns, GetKeywords y SearchForGoogleAdsFields.

Siguiente
Gramática de consulta