Estructura de la consulta

Las consultas para los campos de recursos, segmentos y métricas se pueden enviar a GoogleAdsService Búsqueda o SearchStream . Para crear una consulta en el lenguaje de consulta de Google Ads, deberás crearla con el gramática del idioma. Una consulta consta de varios cláusulas:

• SELECT
• FROM
• WHERE
• ORDER BY
• LIMIT
• PARAMETERS

Las cláusulas usan nombres de campo, nombres de recursos, operadores, condiciones y ordenados para ayudarte a seleccionar los datos correctos. Una vez combinados en una sola se puede realizar una solicitud con la API de Google Ads.

modelo de la UE

ondemand_video Video: Compatibilidad de 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 obligatorio en una consulta.

La consulta de muestra a continuación muestra un ejemplo de cómo seleccionar atributos para un determinado recurso:

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 del segmento

  • segments.device
  • segments.date

• Métricas

  • metrics.impressions
  • metrics.clicks

Es posible que algunos campos no se permitan en la cláusula SELECT debido a los siguientes motivos: restricciones:

• Consulta de campos que no se pueden seleccionar. Estos campos tendrán su Se marcó el atributo de metadatos Selectable como false.
• Seleccionar atributos de campos repetidos Estos campos tendrán su Se marcó el atributo de metadatos isRepeated como true.
• La selección de campos que no están disponibles para el recurso determinado en el FROM . No se pueden seleccionar juntos los atributos de algunos recursos. subconjunto de todas las métricas y segmentos estará disponible para el recurso en la FROM.
• Seleccionar segmentos o métricas que no son compatibles entre sí. Para 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 desde GoogleAdsFieldService.

FROM

La cláusula FROM especifica el recurso principal que se mostrará. El de la cláusula FROM define qué campos se pueden usar todos los demás para la consulta dada. Solo se puede especificar un recurso en el FROM. La cláusula FROM es obligatoria en una consulta que se realiza al GoogleAdsService Búsqueda o SearchStream métodos, pero no se debe especificar cuando se use GoogleAdsFieldService.

Si bien solo puede existir 1 recurso en la cláusula FROM para una consulta determinada, los campos de Recursos atribuidos también pueden estar disponibles. Estos recursos son unido de forma implícita al recurso en la cláusula FROM, por lo que solo necesitas agregar sus atributos a la cláusula SELECT para mostrar sus valores. Es posible que no todas recursos tienen recursos atribuidos. En el siguiente ejemplo, puedes solicitar el ID del grupo de anuncios y el ID de la campaña de 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, se incluirá ad_group.resource_name en la a pesar de no haber sido seleccionado explícitamente en la consulta:

SELECT ad_group.id
FROM ad_group

Lo mismo sucede con otros recursos cuando se selecciona al menos un campo. Por ejemplo: se incluirá campaign.resource_name 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 para cada solicitud. Cuando se usa la cláusula WHERE, se pueden especificar una o más condiciones con AND para separarlos. 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 momento determinado período:

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, solicitar la cantidad de clics de todas las campañas con impresiones en dispositivos móviles en 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 el los siguientes, que se denominan segmentos de fechas principales excepciones:

• segments.date
• segments.week
• segments.month
• segments.quarter
• segments.year

En la siguiente consulta, ten en cuenta que segments.date está seleccionado. Dado que este es un segmento de fecha principal, requiere una fecha limitada período compuesto por segmentos de fechas principales en la cláusula WHERE que se proporcionará.

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.mes, segmentos.trimestre y segmentos.año. Si alguno de estos segmentos se seleccionan, se debe usar al menos una de ellas en la cláusula WHERE.

Cuando filtres, es importante mantener la distinción entre mayúsculas y minúsculas de tu operador en la mente. Consulta Distinción entre mayúsculas y minúsculas para obtener más detalles.

Para obtener una lista completa de operadores, consulta el lenguaje gramática.

ORDER BY

La cláusula ORDER BY especifica el orden en el que se deben ejecutar los resultados. que se devuelven. 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 valor predeterminado del orden a ASC. La cláusula ORDER BY es opcional en una consulta.

La siguiente consulta ordena las campañas devueltas por cantidad de clics de de mayor a menor:

SELECT
  campaign.name,
  metrics.clicks
FROM campaign
ORDER BY metrics.clicks DESC

Puedes especificar varios campos en la cláusula ORDER BY con una coma separada lista. El orden se producirá en la misma secuencia que se especifica en la consulta. Por ejemplo, en esta consulta, cuando seleccionas datos del grupo de anuncios, los resultados se ordenarán. en orden ascendente por nombre de campaña y, a continuación, en orden descendente por número de impresiones, luego, en orden descendente por número 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 el resumen.

Por ejemplo, se puede usar LIMIT para restringir el número total de resultados para el 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 el tipo de filas que se muestran.

Actualmente, se admiten los siguientes metadatos:

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 los borradores de campañas junto con las campañas campañas:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

omit_unselected_resource_names

Establece omit_unselected_resource_names en true para evitar que el nombre del recurso sea para que no se muestre 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.

SELECT
  campaign.name,
  customer.id
FROM campaign

SELECT
  campaign.name,
  customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true

SELECT
  campaign.name,
  campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true

Reglas de idiomas adicionales

Además de los ejemplos de cada cláusula, el lenguaje de consulta de Google Ads cuenta con las siguientes características: comportamientos que se pueden usar:

• No es obligatorio que el campo de recurso principal esté en SELECT para una consulta. Por ejemplo, es posible que desees usar solo uno o más de recursos para filtrar datos:

  SELECT campaign.id
  FROM ad_group
  WHERE ad_group.status = PAUSED
  

• Las métricas se pueden seleccionar exclusivamente para un recurso determinado. ningún otro campo del recurso son obligatorios en la consulta:

  SELECT
    metrics.impressions,
    metrics.clicks,
    metrics.cost_micros
  FROM campaign
  

• Los campos de segmentación se pueden seleccionar sin ningún campo de recurso que los acompañe o métricas:

  SELECT segments.device FROM campaign
  

• El campo resource_name (campaign.resource_name, por ejemplo) puede ser usarse para ordenar o filtrar datos:

  SELECT
    campaign.id,
    campaign.name
  FROM campaign
  WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'