Las consultas de campos de recursos, segmentos y métricas se pueden enviar a los métodos GoogleAdsService
Search o SearchStream. Para crear una consulta en el lenguaje de consulta de Google Ads, deberás crearla con la gramática del idioma. Una consulta se compone de varias cláusulas:
SELECT
FROM
WHERE
ORDER BY
LIMIT
PARAMETERS
Las cláusulas usan nombres de campo, nombres de recursos, operadores, condiciones y ordenes para ayudarte a seleccionar los datos correctos. Una vez que se combina en una sola consulta, se puede realizar una solicitud con la API de Google Ads.
modelo de la UE
Video: Compatibilidad con campos de GAQL
SELECT
La cláusula SELECT
especifica un conjunto de campos para recuperar en la solicitud.
SELECT
toma una lista separada por comas de campos de recursos, campos de segmentos y métricas, y muestra los valores en la respuesta. La cláusula SELECT
es obligatoria en una consulta.
La siguiente consulta de muestra muestra un ejemplo de selección de atributos para un recurso determinado:
SELECT
campaign.id,
campaign.name
FROM campaign
Puedes solicitar diferentes tipos de campos en una sola solicitud, por ejemplo:
SELECT
campaign.id,
campaign.name,
bidding_strategy.id,
bidding_strategy.name,
segments.device,
segments.date,
metrics.impressions,
metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
Campos de recursos
campaign.id
campaign.name
Campos de recursos
bidding_strategy.id
bidding_strategy.name
Campos de segmentos
segments.device
segments.date
Métricas
metrics.impressions
metrics.clicks
Es posible que algunos campos no estén permitidos en la cláusula SELECT
debido a las siguientes restricciones:
- Consulta campos que no se pueden seleccionar. Estos campos tendrán el atributo de metadatos
Selectable
marcado comofalse
. - Selección de atributos de campos repetidos. Estos campos tendrán el atributo de metadatos
isRepeated
marcado comotrue
. - Seleccionar campos que no están disponibles para el recurso dado en la cláusula
FROM
Los atributos de algunos recursos no se pueden seleccionar juntos; además, solo un subconjunto de todas las métricas y segmentos estará disponible para el recurso en la cláusulaFROM
. - Seleccionar segmentos o métricas que no son compatibles entre sí Para obtener más información sobre esto, consulta la sección de segmentación.
Puedes encontrar información relacionada con las condiciones anteriores en nuestros documentos de referencia o en GoogleAdsFieldService
.
FROM
La cláusula FROM
especifica el recurso principal que se mostrará. El recurso de la cláusula FROM
define qué campos se pueden usar en todas las demás cláusulas para la consulta determinada. Solo se puede especificar un recurso en la cláusula FROM
. La cláusula FROM
es obligatoria en una consulta a los métodos GoogleAdsService
Search o SearchStream; sin embargo, no se debe especificar cuando se usa GoogleAdsFieldService
.
Si bien solo puede existir 1 recurso en la cláusula FROM
para una consulta determinada, los campos de los recursos atribuidos también pueden estar disponibles. Estos recursos están unidos implícitamente al recurso en la cláusula FROM
, por lo que solo necesitas agregar sus atributos a la cláusula SELECT
para mostrar sus valores. No todos los recursos tienen recursos atribuidos. En el siguiente ejemplo, puedes solicitar el ID del grupo de anuncios y el ID de la campaña a los grupos de anuncios:
SELECT
campaign.id,
ad_group.id
FROM ad_group
Siempre se muestra el campo resource_name
del recurso principal.
En el siguiente ejemplo, ad_group.resource_name
se incluirá en la respuesta a pesar de no estar seleccionado de forma explícita en la consulta:
SELECT ad_group.id
FROM ad_group
Lo mismo ocurre con otros recursos cuando se selecciona al menos un campo.
Por ejemplo: campaign.resource_name
se incluirá en la respuesta de la siguiente consulta:
SELECT
campaign.id,
ad_group.id
FROM ad_group
WHERE
La cláusula WHERE
especifica las condiciones que se deben aplicar cuando se filtran los datos para la solicitud. Cuando se usa la cláusula WHERE
, se pueden especificar una o más condiciones mediante AND
para separarlas. Cada condición debe seguir el patrón field_name Operator value
. La cláusula WHERE
es opcional en una consulta.
El siguiente es un ejemplo del uso de WHERE
para mostrar métricas de un período determinado:
SELECT
campaign.id,
campaign.name,
metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
Puedes combinar varias condiciones para filtrar los datos. En este ejemplo, se solicitará la cantidad de clics de todas las campañas con impresiones en dispositivos móviles en los últimos 30 días.
SELECT
campaign.id,
campaign.name,
segments.device,
metrics.clicks
FROM campaign
WHERE metrics.impressions > 0
AND segments.device = MOBILE
AND segments.date DURING LAST_30_DAYS
Los segmentos en la cláusula WHERE
deben estar en la cláusula SELECT
, con los siguientes segmentos de fecha, que se denominan segmentos de fechas principales, que son las excepciones:
segments.date
segments.week
segments.month
segments.quarter
segments.year
En la siguiente consulta, ten en cuenta que se seleccionó segments.date
.
Debido a que este segmento es un segmento de fechas principal, se requiere un período limitado compuesto por segmentos de fechas principales en la cláusula WHERE
.
SELECT
campaign.id,
campaign.name,
segments.date,
metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
Todos los segmentos que cumplen con la condición anterior son: segments.date, segments.week, segmentos.month, segments.quarter y segments.year. Si se selecciona alguno de estos segmentos, se debe usar al menos uno de ellos en la cláusula WHERE
.
Cuando se filtra, es importante que tu operador distinga mayúsculas de minúsculas. Consulta la sección Distinción entre mayúsculas y minúsculas para obtener más detalles.
Para obtener una lista completa de operadores, consulta la gramática del lenguaje.
ORDER BY
La cláusula ORDER BY
especifica el orden en el que se deben mostrar los resultados. Esto te permite organizar los datos en orden ascendente o descendente según el nombre de un campo. Cada orden se especifica como un field_name
seguido de ASC
o DESC
. Si no se especifica ASC
ni DESC
, el orden predeterminado es ASC
. La cláusula ORDER BY
es opcional en una consulta.
La siguiente consulta ordena las campañas mostradas por la cantidad de clics, del más alto al más bajo:
SELECT
campaign.name,
metrics.clicks
FROM campaign
ORDER BY metrics.clicks DESC
Puedes especificar varios campos en la cláusula ORDER BY
mediante una lista separada por comas. El orden ocurrirá en la misma secuencia que se especifica en la consulta.
Por ejemplo, en esta consulta que seleccionas datos del grupo de anuncios, los resultados se ordenarán
en forma ascendente por nombre de campaña, luego en orden descendente por cantidad
de impresiones y, luego, en orden descendente por cantidad de clics:
SELECT
campaign.name,
ad_group.name,
metrics.impressions,
metrics.clicks
FROM ad_group
ORDER BY
campaign.name,
metrics.impressions DESC,
metrics.clicks DESC
LIMIT
La cláusula LIMIT
te permite especificar la cantidad de resultados que se mostrarán.
Esto es útil si solo te interesa un resumen.
Por ejemplo, se puede usar LIMIT
para restringir la cantidad total de resultados de la siguiente consulta:
SELECT
campaign.name,
ad_group.name,
segments.device,
metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50
PARÁMETROS
La cláusula PARAMETERS
te permite especificar metaparámetros para la solicitud.
Estos parámetros pueden afectar los tipos de filas que se muestran.
Actualmente, se admiten los siguientes metaparámetros:
include_drafts
Establece include_drafts
en true
para permitir que se muestren las entidades de borrador.
La configuración predeterminada es false
.
Por ejemplo, la siguiente consulta recupera borradores de campaña junto con las campañas normales:
SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true
omit_unselected_resource_names
Configura omit_unselected_resource_names
como true
para evitar que se muestre el nombre del recurso de cada tipo de recurso en la respuesta, a menos que se solicite explícitamente en la cláusula SELECT
. La configuración predeterminada es false
.
Ejemplos de omitir_unselected_resource_names | |
---|---|
SELECT campaign.name, customer.id FROM campaign |
Returned resources:campaign.resource_name
El valor predeterminado de omit_unselected_resource_names es false , por lo que
se muestran todos los campos resource_name.
|
SELECT campaign.name, customer.id FROM campaign PARAMETERS omit_unselected_resource_names = true |
Returned resources: Ninguno. omit_unselected_resource_names se especifica como true , y campaign.resource_name y customer.resource_name no son parte de la cláusula SELECT .
|
SELECT campaign.name, campaign.resource_name FROM campaign PARAMETERS omit_unselected_resource_names = true |
Returned resource:campaign.resource_name
omit_unselected_resource_names se especifica como true y campaign.resource_name solicitados como parte de la cláusula SELECT .
|
Reglas de lenguaje adicionales
Además de los ejemplos para cada cláusula, el lenguaje de consulta de Google Ads tiene los siguientes comportamientos que se pueden utilizar:
No es obligatorio que el campo de recursos principal esté en la cláusula
SELECT
para una consulta. Por ejemplo, es posible que solo quieras usar uno o más campos de recursos principales para filtrar datos:SELECT campaign.id FROM ad_group WHERE ad_group.status = PAUSED
Las métricas se pueden seleccionar de forma exclusiva para un recurso determinado; no se requieren otros campos del recurso en la consulta:
SELECT metrics.impressions, metrics.clicks, metrics.cost_micros FROM campaign
Los campos de segmentación se pueden seleccionar sin campos de recursos o métricas que los acompañen:
SELECT segments.device FROM campaign
El campo
resource_name
(por ejemplo,campaign.resource_name
) se puede usar para ordenar o filtrar los datos:SELECT campaign.id, campaign.name FROM campaign WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'