Lenguaje de búsqueda de Google Ads

Sugerencia: Usa el Compilador de consultas interactivo para crear y validar tus consultas de GAQL.

Terminología clave

Recurso

Es una entidad de 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, estas 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 de recursos o metadatos

El lenguaje de consulta de Google Ads puede consultar la API de Google Ads para obtener 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 instancias de GoogleAdsRow, en la que cada GoogleAdsRow representa un recurso.

  Si se solicita algún atributo o métrica, 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 recurso de segmento.

• Metadatos sobre los campos y recursos disponibles en GoogleAdsFieldService: Este servicio proporciona un catálogo de campos que se pueden consultar 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 las consultas y Gramática del lenguaje de consulta de Google Ads.

Consulta los atributos de los recursos

A continuación, se muestra un ejemplo de una consulta básica de atributos del recurso de campaña que ilustra cómo 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 representa un objeto campaign propagado con los campos seleccionados, incluido el resource_name de la campaña.

Para averiguar qué otros campos están disponibles para las consultas 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 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, y las 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 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 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 la consulta de métricas, esta consulta filtra solo las campañas que tienen el estado 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 el segmento de fecha. 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 que se pueden consultar, consulta la documentación de Segments.

Consulta los atributos de un recurso relacionado

En una consulta para 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 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 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 campaña seleccionados, así como el atributo de estrategia de ofertas seleccionado bidding_strategy.name.

Para averiguar 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 agotados.
• 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 los que implican grandes cantidades de datos o cálculos complejos, pueden aumentar el costo de la consulta.

Mutación basada en los resultados de la consulta

Cuando consultas un recurso determinado, puedes tomar de inmediato los resultados mostrados como objetos, modificarlos y enviarlos de vuelta al método mutate en el servicio de ese recurso. Este es un flujo de trabajo de ejemplo:

1. Ejecuta una consulta para todas las campañas de PAUSED que tengan más de 1,000 impresiones.
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 y un FieldMask correspondiente para actualizarlas.

Nota: Cuando actualices los recursos recuperados de una consulta, especifica una FieldMask (o usa la utilidad de máscara de campo integrada de tu biblioteca cliente) para que solo se actualicen los campos modificados, lo que evita errores READ_ONLY_FIELD o IMMUTABLE_FIELD, o reemplazar otros atributos de forma involuntaria.

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 esta proporciona los metadatos necesarios para validar o compilar una consulta, los desarrolladores pueden 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).

Punto clave: Ten en cuenta que no hay una cláusula FROM en esta consulta.

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

Diferencias específicas de la versión

Si bien la sintaxis, las cláusulas y los operadores del lenguaje de consulta de Google Ads son idénticos en todas las versiones compatibles de la API de Google Ads (v23, v24, v25 y v26), el catálogo de recursos, segmentos, métricas y comportamientos de informes que se pueden consultar difiere según la versión principal. Consulta GoogleAdsFieldService en el extremo de la versión de la API de destino para inspeccionar los campos y las reglas de compatibilidad de esa versión:

• Vista de recursos de expansión de la URL final:
  • Compatibilidad con campañas de Shopping (v26 y versiones posteriores): final_url_expansion_asset_view admite campañas de Shopping (campaign.advertising_channel_type = 'SHOPPING'), además de campañas de máximo rendimiento y de Búsqueda. En el caso de las campañas de Shopping, puedes seleccionar y filtrar por campos ad_group, pero no puedes seleccionar campos asset_group.
  • Métricas seleccionables (v25 y versiones posteriores): Cuando se consulta final_url_expansion_asset_view, se devuelven todas las métricas seleccionables para la vista. En la versión 24 y anteriores, las respuestas solo incluyen metrics.conversions y metrics.conversions_value para las campañas de máximo rendimiento y metrics.impressions para las campañas de Búsqueda.
• Recursos de objetivos de ciclo de vida: En la versión 25 y posteriores, todos los objetivos de ciclo de vida (adquisición de clientes nuevos, retención de clientes y retención de clientes leales) se consultan desde los recursos unificados goal y campaign_goal_config, que reemplazan a customer_lifecycle_goal y campaign_lifecycle_goal (que se usaban para los objetivos de adquisición de clientes nuevos en la versión 24 y anteriores, junto con goal y campaign_goal_config para los objetivos de retención de clientes).
• Informes de productos de Shopping para las campañas de aplicaciones: En la versión 24 y posteriores, el recurso shopping_product devuelve filas de productos para las campañas de aplicaciones, además de las campañas de Shopping, de máximo rendimiento, de generación de demanda y de video (en la versión 23, las campañas de aplicaciones se excluyen de los resultados de shopping_product).
• Recursos, segmentos y métricas específicos de la versión:
  • v26 y versiones posteriores: Incluye el recurso search_lift_keyword_bundle, campaign.lift_measurement_config, local_services_lead.campaign, segments.search_lift_keyword_bundle, segments.search_property y las métricas de Efectividad de búsqueda (como metrics.relative_search_lift, metrics.normalized_incremental_searches, metrics.search_lift_cost_micros y metrics.search_lift_impressions).
  • v25 y versiones posteriores: Incluye recursos de medición de efectividad (como lift_measurement_config), segmentos como segments.ad_sub_format_type y segments.loyalty_membership, y métricas de participación de YouTube (metrics.youtube_likes, metrics.youtube_comments y metrics.youtube_shares). Quita local_services_lead.contact_details.email (que se puede seleccionar en la versión 24 y anteriores).
  • v24 y versiones posteriores: Incluye el recurso cart_data_sales_view, segments.conversion_attribution_event_type en shopping_performance_view, segments.mobile_device_platform y segments.ad_network_type en performance_max_placement_view. Se quita campaign.video_brand_safety_suitability (se reemplaza por customer.video_brand_safety_suitability), segments.ad_sub_network_type en campaign_budget y segments.click_type en ad_group_asset, campaign_asset y customer_asset (que solo se pueden seleccionar en la versión 23).
• Código de error de la ventana de visualización de fechas detalladas: Las consultas que segmentan por segments.date, segments.week o segments.hour (o filtran por un período inferior a un mes) más allá de la ventana de visualización de 37 meses devuelven DateRangeError.REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED en la versión 24 y posteriores (o DateRangeError.UNKNOWN en la versión 23). Consulta Períodos para obtener más detalles.

Ejemplos de código

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