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 instancias de
GoogleAdsRow
, donde cadaGoogleAdsRow
representa un recurso. 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 y recurso. - Metadatos sobre los campos y recursos disponibles en
GoogleAdsFieldService
Este servicio proporciona un catálogo de campos consultables con especificaciones sobre su compatibilidad y tipo.
El resultado de una consulta
GoogleAdsFieldService
es una lista de instancias deGoogleAdsField
, en la que cadaGoogleAdsField
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 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 representaría un objeto campaign
propagado con los campos seleccionados (incluido el resource_name
de esa campaña).
Si quieres saber qué otros campos están disponibles para las consultas de las 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 obtuvieron más de 1,000 impresiones, y 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
De manera similar a la consulta de métricas, esta consulta filtra solo las campañas que tienen el estado PAUSED
y tienen más de 1,000 impresiones. Sin embargo, esta consulta segmenta los datos por fecha. Esto conduce a cada GoogleAdsRow
resultante que representa 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 agrupa por cada segmento en la cláusula SELECT.
Para obtener una lista de segmentos consultables, consulta la documentación de Segments
.
Consulta atributos de un recurso relacionado
En una consulta sobre un recurso determinado, es posible que puedas unirte a otros recursos relacionados si están disponibles. Estos recursos relacionados se conocen como “recursos atribuidos”. Puedes realizar una unión implícita con recursos atribuidos 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 no solo selecciona atributos de la campaña, sino que también extrae 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 de estrategia de ofertas seleccionado bidding_strategy.name
.
Si quieres 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 de inmediato esos resultados que se muestran como objetos, modificarlos y enviarlos de vuelta al método mutate en el servicio de ese recurso. A continuación, se muestra un ejemplo de flujo de trabajo:
- Ejecuta una consulta para todas las campañas que estén actualmente en estado
PAUSED
y tengan impresiones superiores a 1,000. - Obtén el objeto
Campaign
del campocampaign
de cadaGoogleAdsRow
en la respuesta. - Cambie el estado de cada campaña de
PAUSED
aENABLED
. - 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 juntos 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 a los desarrolladores hacerlo de manera 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 de operaciones básicas tiene ejemplos como GetCampaigns
, GetKeywords
y SearchForGoogleAdsFields
.
La carpeta reporting tiene un ejemplo de GetKeywordStats
.