Lenguaje de búsqueda de Google Ads

El lenguaje de consulta de Google Ads puede realizar consultas a la API de Google Ads para

Recursos y sus atributos, segmentos y métricas relacionados con
GoogleAdsService Búsqueda o SearchStream
El resultado de una consulta de GoogleAdsService es una lista de GoogleAdsRow instancias, con cada GoogleAdsRow que representan un recurso. Si se solicitan atributos o métricas, también incluye esos campos. Si se solicitan segmentos, el también muestra una fila adicional para cada tupla segmento-recurso.
Metadatos sobre los campos y recursos disponibles en
GoogleAdsFieldService

Este servicio proporciona un catálogo de campos consultables con información específica sobre su compatibilidad y tipo.

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

Consulta los atributos de un recurso

A continuación, se muestra una consulta básica para los atributos del recurso de la campaña, que ilustra cómo para devolver 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 representaría un objeto campaign propagado con los campos seleccionados (incluidos los que se proporcionan resource_name de la campaña).

Para saber qué otros campos están disponibles para las consultas de la campaña, 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 para las campañas que tienen el estado PAUSED y tuvieron más de 1, 000 impresiones y se ordenaron por ID de campaña. Cada GoogleAdsRow resultante tendrá un campo metrics propagado con el métricas seleccionadas.

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

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 la consulta de métricas, esta consulta filtra solo por las campañas que Tener un estado de PAUSED y tener más de 1,000 impresiones. Sin embargo, esta consulta segmenta los datos por fecha. Esto conduce a que cada resultado GoogleAdsRow, que representa una tupla de una campaña y la fecha Segment. Es es importante tener en cuenta que la segmentación divide las métricas seleccionadas y se agrupa según segmento en la cláusula SELECT.

Para obtener una lista de segmentos que puedes consultar, consulta el Segments documentación.

En una consulta sobre un recurso determinado, es posible que puedas combinarlo con otro recursos si están disponibles. Estos recursos relacionados se conocen como “recursos recursos”. Puedes realizar una unión implícita con recursos atribuidos si seleccionas un 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 incorpora atributos 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 de estrategia de ofertas seleccionado bidding_strategy.name.

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

Mutación basada en los resultados de la consulta

Cuando consultas un recurso determinado, puedes tomar inmediatamente resultados como objetos, modificarlos y enviarlos de vuelta al método {i>mutate<i} de ese servicio del recurso. A continuación, se muestra un ejemplo de flujo de trabajo:

  1. Ejecuta una consulta para todas las campañas que estén actualmente PAUSED y tengan 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 campos

Las consultas enviadas 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 en conjunto en una consulta. Dado que los datos están disponibles en la API y proporcionan los elementos metadatos necesarios para validar o crear una consulta, lo que permite que los desarrolladores programáticamente. Este es un consulta típica para 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 campo (como campaign.id, metrics.impressions o ad_group.id).

Para obtener una lista de campos consultables, consulta el GoogleAdsField documentación.

Ejemplos de código

Las bibliotecas cliente tienen ejemplos del uso de la Lenguaje de consulta de Google Ads en GoogleAdsService. La carpeta basic operations tiene con ejemplos, como GetCampaigns, GetKeywords y SearchForGoogleAdsFields. La carpeta reporting tiene un ejemplo de GetKeywordStats.