La nueva API de informes de Search Ads 360 ya está disponible. Únete al grupo de Google searchads-api-announcements para mantenerte al tanto de las próximas mejoras y lanzamientos.

Se usó la API de Cloud Translation para traducir esta página.

Estructura de consultas y cláusulas

Una consulta consta de varias cláusulas: SELECT, FROM, WHERE, ORDER BY: LIMIT: y PARAMETERS.

Las cláusulas usan nombres de campo, nombres de recursos, operadores, condiciones, y orders que se combinan en una sola solicitud de consulta.

En términos básicos, para crear una consulta debes hacer lo siguiente:

Especifica un recurso desde el cual recuperar datos.
Agrega campos y métricas para definir los datos que deseas mostrar.
Agregue segmentos para agrupar sus resultados.
Agrega recursos atribuidos para unir implícitamente datos de recursos relacionados.
Filtra, ordena y limita los resultados.

Cláusula `SELECT`

La cláusula SELECT hace lo siguiente:

Es una cláusula obligatoria en una consulta.
Especifica un conjunto de campos para recuperar en la solicitud.
Toma una lista separada por comas de campos de recursos, columnas personalizadas, variables de Floodlight, campos de segmentos y métricas, y devuelve los valores en los respuesta.

En esta consulta de ejemplo, se muestra cómo seleccionar atributos de campaign recurso:

SELECT
  campaign.id,
  campaign.name
FROM campaign

Varios tipos de campos

Puedes solicitar diferentes tipos de campos en la misma solicitud.

La consulta de ejemplo a continuación muestra una sola consulta que combina:

Campos de recursos: campaign.id, campaign.name, bidding_strategy.id y bidding_strategy.name
Campos de segmento: segments.device y segments.date.
Campos de métricas: metrics.impressions y metrics.clicks.

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

Consulte Segmentación. para obtener más información sobre cómo segmentar los informes de búsqueda.

Campo de recurso principal

Por lo general, debes incluir el campo de recurso principal en el elemento SELECT pero es opcional (no es obligatorio).

En esta consulta de ejemplo, se usa un campo de recurso principal (ad_group.status) para solo filtrar los resultados.

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

Variables personalizadas de Floodlight

Puedes incluir variables personalizadas de Floodlight en la cláusula SELECT con su IDs.

En este ejemplo, la consulta incluye una variable personalizada con el ID 123454321 para recurso de campaña.

SELECT
  conversion_custom_metrics.id[123454321]
FROM campaign

SELECT
  conversion_custom_dimensions.id[123454321]
FROM campaign

Columnas personalizadas

Puedes incluir columnas personalizadas en la cláusula SELECT con sus IDs.

En este ejemplo, la consulta incluye una columna personalizada con el ID 12345678 para el recurso de campaña.

SELECT
  custom_columns.id[12345678]
FROM campaign

Consulte cómo obtener los ID de las columnas personalizadas.

Campos de métricas

Puedes seleccionar campos de métricas para un recurso determinado sin incluir ningún otro del recurso en la cláusula SELECT.

En esta consulta de ejemplo, se seleccionan las métricas impressions y clicks para campaign recurso.

SELECT
  metrics.impressions,
  metrics.clicks
FROM campaign

Consulta metrics para ver un con una lista de los campos de métricas que puedes usar en tus consultas.

Campos de segmentos

Puedes seleccionar campos de segmentos sin especificar campos de recursos complementarios o métricas en la cláusula SELECT.

En esta consulta de ejemplo, se segmentan los resultados por dispositivo.

SELECT segments.device
FROM campaign

Consulta segments para ver un una lista de campos de segmentos que puedes usar en tus consultas.

Campos prohibidos

No puedes usar los siguientes campos en la cláusula SELECT:

Campos no seleccionables, es decir, campos con los metadatos Selectable se marcó como false.
Campos repetidos, es decir, campos con el atributo de metadatos Repeated marcado como true.
Campos que no están disponibles para el recurso determinado en la cláusula FROM. No se pueden seleccionar juntos los atributos de algunos recursos. Solo algunos recursos ofrecen un subconjunto de todas las métricas y segmentos.
Segmentos o métricas incompatibles. Consulte Segmentación para obtener más información. información.

Consulta la documentación de referencia para detalles sobre dónde encontrar esta información para cada recurso.

Cláusula FROM

La cláusula FROM hace lo siguiente:

Es una cláusula obligatoria para que las consultas SearchAds360Service (métodos Search y SearchStream).
No debe incluirse en las consultas a SearchAds360FieldService.
Especifica el recurso principal que muestra la consulta.
Solo se puede especificar un recurso.
Define los campos que puedes usar en todas las demás cláusulas en la consulta.

Recursos atribuidos

Si hay recursos atribuidos disponibles, se unen implícitamente con el recurso que especificas en la cláusula FROM. Solo debes agregar sus atributos a la cláusula SELECT para mostrar sus valores.

Esta consulta de ejemplo devuelve el ID del grupo de anuncios y el ID de la campaña porque campaign es un recurso atribuido del recurso ad_group.

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Campo `resource_name`

El campo resource_name del recurso principal en la cláusula FROM siempre es que se devuelven.

En esta consulta de ejemplo, se incluirá ad_group.resource_name en la respuesta aunque no esté seleccionado explícitamente en la consulta:

SELECT ad_group.id
FROM ad_group

El campo resource_name de un recurso atribuido es que se muestra cuando se selecciona al menos un campo.

En esta consulta de ejemplo, se incluirá campaign.resource_name en la respuesta porque se seleccionó campaign.id:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Cláusula WHERE

La cláusula WHERE hace lo siguiente:

Es una cláusula opcional en una consulta.
Especifica las condiciones para filtrar y segmentar los datos para la solicitud. Las condiciones siguen este patrón: FIELD_NAME OPERATOR VALUE (separadas por espacios en blanco).
Puede incluir varias condiciones separadas por el separador AND.

En esta consulta de ejemplo, se muestra cómo usar la cláusula WHERE para mostrar impressions para un período determinado:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Consulte Segmentación. para obtener más información sobre cómo segmentar los informes de búsqueda.

Consulta Períodos para obtener más información sobre cómo especificar fechas. los rangos en tus consultas.

Filtrar por campo `resource_name`

Puedes usar el campo resource_name para ordenar o filtrar los datos.

En esta consulta de ejemplo, se usa el campo campaign.resource_name para filtrar los resultados para una campaña determinada:

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

Varias condiciones

Puedes combinar varias condiciones para filtrar tus datos.

Esta consulta de ejemplo solicita la cantidad de métricas de clicks para todas las campañas con impressions métricas en dispositivos móviles durante 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

Consulte Segmentación. para obtener más información sobre cómo segmentar sus informes.

Distinción entre mayúsculas y minúsculas

Cuando filtras valores de cadena, la distinción entre mayúsculas y minúsculas predeterminada de cada operador son importantes para filtrar correctamente los resultados.

En la siguiente tabla, se muestra la distinción entre mayúsculas y minúsculas predeterminada de cada operador.

Distinción entre mayúsculas y minúsculas predeterminada
`=/!=`	`Case sensitive`
`IN/NOT IN`	`Case sensitive`
`LIKE/NOT LIKE`	`Case insensitive`
`CONTAINS (...)`	`Case sensitive`
`REGEXP_MATCH/NOT REGEXP_MATCH`	`Case sensitive`

Puedes usar el modificador (?i) para cambiar la sensibilidad predeterminada de REGEXP_MATCH y NOT REGEXP_MATCH para que no distingan mayúsculas de minúsculas, por ejemplo:

SELECT campaign.id
FROM campaign
WHERE campaign.name REGEXP_MATCH "(?i).*test.*"

Consulta la Referencia de gramática de consulta para obtener una lista completa de operadores que puedes usar para filtrar tus datos.

Segmentos de fechas principales

Los siguientes campos de segmentos se conocen como segmentos de fechas principales: segments.date, segments.week, segments.month, segments.quarter y segments.year

Puedes usar segmentos de fechas principales en tu cláusula WHERE para especificar una hora o fecha. período.

En esta consulta de ejemplo, se especifica DURING LAST_30_DAYS para el campo segments.date en la cláusula WHERE:

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Consulte Segmentación > Segmentos de fechas principales para obtener información información sobre el uso de segmentos de fechas principales.

Filtrado prohibido

No se permite filtrar:

En campos de segmentos no seleccionados, excepto en los segmentos de fechas principales
En los campos de cualquier tipo de mensaje, excepto los tipos primitivos (por ejemplo, Int64Value, StringValue, etcétera).
En atributos de campos repetidos de cualquier tipo de mensaje, excepto las primitivas (por ejemplo, Int64Value, StringValue, etc.).

Cláusula ORDER BY

La cláusula ORDER BY hace lo siguiente:

Es una cláusula opcional en una consulta.
Especifica el orden en el que se muestran los resultados. El orden sigue a esta diseño: FIELD_NAME ORDERING_OPTION (separados por un espacio en blanco)
Permite dos opciones: ASC (ascendente) o DESC (descendente). La configuración predeterminada es ascendente.

Esta consulta de ejemplo ordena las campañas por cantidad de clics, en orden descendente. (de mayor a menor):

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

Varios pedidos

Puedes especificar varios campos en la cláusula ORDER BY con una coma separada lista. Los resultados se ordenarán en la misma secuencia que especifiques en la para cada búsqueda.

Esta consulta de ejemplo selecciona datos del grupo de anuncios y ordena los resultados en orden ascendente ordenado por nombre de campaña, luego en orden descendente por número de impresiones. 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

Combinar orden y límites

Puedes usar la cláusula ORDER BY en combinación con la cláusula LIMIT para y perfecciona tus resultados.

Esta consulta de ejemplo devuelve las cinco campañas con la mayor cantidad de impresiones durante los últimos 30 días:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.impressions DESC
LIMIT 5

Pedidos prohibidos

No se permite ordenar:

Por atributos de recursos no seleccionados
Por métricas no seleccionadas.
Por segmentos no seleccionados
Para estos tipos de campos:
- MESSAGE
- Campos repetidos
- Atributos de campos repetidos.

Cláusula LIMIT

La cláusula LIMIT hace lo siguiente:

Es una cláusula opcional en una consulta.
Te permite limitar la cantidad de resultados que muestra la consulta.

Esta cláusula es útil, por ejemplo, si solo te interesa una muestra o con un resumen de los resultados.

Esta consulta de ejemplo limita el número total de resultados a 50:

SELECT
  campaign.name,
  ad_group.name,
  segments.device,
  metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50

Cláusula VIEWERETERS

La cláusula PARAMETERS te permite especificar metaparámetros para la solicitud.

Incluir borradores

El parámetro include_drafts controla si se incluyen las entidades en borrador en los resultados. El valor predeterminado es false. Configúralo como true para incluir entidades en borrador.

Esta consulta de ejemplo muestra los borradores de campañas y las campañas normales:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

Omitir `resource_name` no seleccionado

El parámetro omit_unselected_resource_names te permite excluir la Campo resource_name de todos los recursos que no se solicitan explícitamente en tu SELECT. El valor predeterminado es false. Si estableces este parámetro en true, recomienda solicitar de forma explícita el nombre del recurso principal y cualquier recurso atribuido en tu cláusula SELECT.

Esta consulta de ejemplo no muestra ni campaign.resource_name ni campo customer.resource_name, ya que no se incluyen en SELECT siguiente:

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

Esta consulta de ejemplo muestra el campo campaign.resource_name, ya que es solicitado de forma explícita en la cláusula SELECT:

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

Cambiar la moneda que se usa en las métricas

El parámetro metrics_currency te permite especificar la moneda que se usará Cuando calculas una métrica incluida en la cláusula SELECT. La opción predeterminada es usar la moneda local de la cuenta. Si estableces esto debe utilizar el código de moneda ISO 4217 de 3 caracteres. Por ejemplo: USD o EUR.

Esta consulta de ejemplo muestra la métrica cost_micros en la moneda local del de servicio predeterminada.

SELECT
  campaign.name,
  metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"

Esta consulta de ejemplo muestra la métrica cost_micros en pesos chilenos (CLP).

SELECT
  campaign.name,
  metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"
PARAMETERS metrics_currency = "CLP"

Más información

Gramática de consulta