Lee las siguientes secciones para obtener información sobre cómo crear informes de búsqueda en la API de Search Ads 360 Reporting.
Servicio de búsqueda
La API de Search Ads 360 Reporting proporciona un servicio especial de búsquedas y de informes.
SearchAds360Service
es un servicio unificado de informes y recuperación de objetos que proporciona dos métodos de búsqueda: SearchStream
y Search
. Las búsquedas se pasan en una cadena de consulta escrita en el lenguaje de consulta de Search Ads 360. Puedes definir consultas de las siguientes maneras:
- Recupera atributos específicos de objetos.
- Recuperar métricas de rendimiento de objetos basadas en un período
- Ordena los objetos según sus atributos.
- Filtra los resultados con condiciones que especifiquen qué objetos mostrar
- Limita la cantidad de objetos que se muestran.
Ambos métodos de búsqueda muestran todas las filas que coinciden con tu consulta. Por ejemplo, cuando recuperas campaign.id
, campaign.name
y metrics.clicks
, la API muestra un SearchAds360Row
que contiene un objeto de campaña con sus campos id
y name
configurados, y un objeto metrics
con su campo clicks
configurado.
Métodos de búsqueda
SearchStream
Envía una sola solicitud y, luego, inicia una conexión persistente con la API de Search Ads 360 Reporting, sin importar el tamaño del informe.
- Los paquetes de datos comienzan a descargarse de inmediato con el resultado completo almacenado en caché en un búfer de datos.
- Tu código puede comenzar a leer los datos almacenados en búfer sin tener que esperar a que termine toda la transmisión.
Search
Envía varias solicitudes paginadas para descargar el informe completo.
SearchStream
suele ofrecer un mejor rendimiento porque elimina el tiempo de red de ida y vuelta necesario para solicitar páginas individuales. Recomendamos usar SearchStream
para todos los informes de más de 10,000 filas. No hay una diferencia de rendimiento significativa entre los métodos para informes más pequeños (<10,000 filas).
El método que uses no afecta las cuotas y los límites de tu API: una sola consulta o informe se cuenta como una operación, independientemente de si los resultados se paginan o se transmiten.
Búsqueda de ejemplo
Esta consulta de ejemplo muestra los datos de rendimiento de una cuenta durante los últimos 30 días por campaña, segmentados por dispositivo:
SELECT
campaign.name,
campaign.status,
segments.device,
metrics.impressions,
metrics.clicks,
metrics.ctr,
metrics.average_cpc,
metrics.cost_micros
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
Haz una solicitud
Para emitir una solicitud, debes pasar una cadena customer_id
y una query
a la interfaz SearchAds360Service.SearchStream
o SearchAds360Service.Search
.
La solicitud consiste en un POST
HTTP al servidor de la API de Search Ads 360 Reporting en cualquiera de las siguientes URLs:
https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream
https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:search
A continuación, se muestra un ejemplo completo de la definición de informe para searchStream
incluida en una solicitud POST
HTTP:
POST /VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream HTTP/1.1 Host: searchads360.googleapis.com User-Agent: curl Content-Type: application/json Accept: application/json Authorization: Bearer [OAUTH_2.0_ACCESS_TOKEN] Parameters: { "query" : "SELECT campaign.name, campaign.status, segments.device, metrics.impressions, metrics.clicks, metrics.ctr, metrics.average_cpc, metrics.cost_micros FROM campaign WHERE segments.date DURING LAST_30_DAYS" }
Cómo procesar una respuesta
SearchAds360Service
muestra una lista de objetos SearchAds360Row
.
Cada SearchAds360Row
representa un objeto que muestra la consulta. Cada objeto consiste en un conjunto de atributos que se propagan en función de los campos solicitados en la cláusula SELECT
de la consulta. Los atributos que no están incluidos en la cláusula SELECT
no se propagan en los objetos de la respuesta.
Por ejemplo, la siguiente consulta propaga cada objeto SearchAds360Row
solo con campaign.id
, campaign.name
y campaign.status
. Se omiten otros atributos, como campaign.engine_id
o campaign.bidding_strategy_type
.
SELECT
campaign.id,
campaign.name,
campaign.status
FROM campaign
Documentación de referencia
En la sección Referencia, se incluye toda la información que necesitas para usar correctamente cada artefacto. Hay una página para cada recurso, por ejemplo, ad_group
y campaign
.
En las páginas segments
y metrics
, se enumeran todos los segmentos y campos de métricas disponibles.
Algunos recursos, segmentos y métricas son incompatibles y no se pueden usar juntos, mientras que otros son totalmente compatibles y se complementan entre sí. Cada página de recursos incluye la siguiente información (si está disponible y corresponde) y más:
- Recursos atribuidos
Para algunos recursos, es posible que tengas la opción de unir de forma implícita recursos relacionados si seleccionas sus campos junto con los campos del recurso en tu cláusula
FROM
. Por ejemplo, el recursocampaign
es un recurso atribuido del recursoad_group
. Esto significa que puedes incluir campos comocampaign.id
ycampaign.bidding_strategy_type
en tu consulta cuando usasad_group
en la cláusulaFROM
.En la sección Recursos atribuidos, se enumeran los recursos atribuidos disponibles. No todos los recursos tienen recursos atribuidos.
- Columna de campos de recursos
Todos los campos del recurso se incluyen en la columna Campos de recursos. Cada campo de recursos se vincula a más detalles sobre el campo, incluida su descripción, categoría, tipo de datos, tipo de URL y configuración que se puede filtrar, seleccionar, ordenar y repetir.
- Columna de segmentos
No todos los campos de segmentos se pueden seleccionar con un recurso determinado.
En la columna Segmentos, se enumeran los campos
segments
que puedes usar en la misma cláusulaSELECT
que los campos del recurso. Cada campo se vincula con detalles completos, como su descripción, categoría, tipo de datos, tipo de URL y configuración para filtrar, seleccionar, ordenar y repetir. Si usas el recurso en la cláusulaFROM
, puedes usar el menú desplegable Sí/No para filtrar los segmentos que no están disponibles.- Columna de métricas
No todos los campos de métricas se pueden seleccionar con un recurso determinado.
En la columna Métricas, se enumeran los campos
metrics
que puedes usar en la misma cláusulaSELECT
que los campos del recurso. Cada campo se vincula con detalles completos, como su descripción, categoría, tipo de datos, tipo de URL y configuración para filtrar, seleccionar, ordenar y repetir. Si usas el recurso en la cláusulaFROM
, usa el menú desplegable Sí/No para filtrar las métricas que no están disponibles.
- Segmentación de recursos
Algunos recursos tienen campos de recursos de segmentación que puedes seleccionar cuando el recurso está en la cláusula
FROM
. Por ejemplo, si seleccionas un campo de recursocampaign
, comocampaign.name
, cuando usescampaign_budget
en tu cláusulaFROM
,campaign.resource_name
se mostrará y se segmentará automáticamente, porquecampaign
es un recurso de segmentación decampaign_budget
.En la sección Recursos de segmentación, se enumeran los recursos de segmentación disponibles. No todos los recursos tienen recursos de segmentación.
- Se puede seleccionar con
Algunos campos
segments
no son compatibles con otros recursos, segmentos y métricas.La página
segments
incluye un elemento expandible Seleccionable con para cada camposegments
que enumera todos los campos de recursos compatibles, los camposmetrics
y otros campossegments
que puedes incluir en tu cláusulaSELECT
.
Segmentación
Para segmentar los resultados de la búsqueda, agrega un campo segments.FIELD_NAME
a la cláusula SELECT
de la consulta.
Por ejemplo, segments.device
en la siguiente consulta da como resultado un informe con una fila para el impressions
de cada dispositivo para el recurso especificado en la cláusula FROM
.
SELECT
campaign.name,
campaign.status,
segments.device,
metrics.impressions
FROM campaign
Los resultados que muestra SearchAds360Service.SearchStream
se parecen a esta cadena JSON:
{
"results":[
{
"campaign":{
"resourceName":"customers/1234567890/campaigns/111111111",
"name":"Test campaign",
"status":"ENABLED"
},
"metrics":{
"impressions":"10922"
},
"segments":{
"device":"MOBILE"
}
},
{
"campaign":{
"resourceName":"customers/1234567890/campaigns/111111111",
"name":"Test campaign",
"status":"ENABLED"
},
"metrics":{
"impressions":"28297"
},
"segments":{
"device":"DESKTOP"
}
},
...
]
}
Consulta segments
para obtener una lista de los campos de segmentos disponibles que puedes usar.
Varios segmentos
Puedes especificar varios segmentos en la cláusula SELECT
de tu consulta. La respuesta contiene un objeto SearchAds360Row
por cada combinación de la instancia del recurso principal especificado en la cláusula FROM
y el valor de cada campo segment
seleccionado.
Por ejemplo, la siguiente consulta mostrará una fila para cada combinación de campaign
, segments.ad_network_type
y segments.date
.
SELECT
segments.ad_network_type
segments.date
FROM campaign
Ten en cuenta que los resultados se segmentan de forma implícita por cada instancia del recurso principal, pero no por los valores de los campos individuales seleccionados.
La siguiente consulta de ejemplo genera una fila por campaña, no una fila por valor distinto del campo campaign.status
.
SELECT
campaign.status,
metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS
Segmentación implícita
En un principio, todos los informes están segmentados por el recurso especificado en la cláusula FROM
. Las métricas se segmentan por el campo resource_name
de este recurso
En esta consulta de ejemplo, se muestra automáticamente ad_group.resource_name
y se la usa de forma implícita para segmentar las métricas en el nivel de ad_group
.
SELECT metrics.impressions
FROM ad_group
La string JSON que se muestra es similar a la siguiente:
{
"results":[
{
"adGroup":{
"resourceName":"customers/1234567890/adGroups/2222222222"
},
"metrics":{
"impressions":"237"
}
},
{
"adGroup":{
"resourceName":"customers/1234567890/adGroups/33333333333"
},
"metrics":{
"impressions":"15"
}
},
{
"adGroup":{
"resourceName":"customers/1234567890/adGroups/44444444444"
},
"metrics":{
"impressions":"0"
}
}
]
}
Segmentos principales de fechas
Puedes usar segmentos de fechas principales en tu cláusula WHERE
para especificar una fecha o un período.
Los siguientes campos de segmentos se conocen como segmentos de fechas principales: segments.date
, segments.week
, segments.month
, segments.quarter
y segments.year
.
Esta consulta de ejemplo muestra las métricas de la campaña clicks
para los últimos 30 días.
SELECT
campaign.id,
campaign.name,
segments.date,
metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
Los campos de segmentos de fechas principales son una excepción a la regla general de que no puedes usar un campo de segmentos en tu cláusula WHERE
, a menos que también incluyas el campo en tu cláusula SELECT
. Consulta Filtrado prohibido para obtener más información.
Reglas principales de segmentos de fechas:
Puedes usar un campo de fecha principal en la cláusula
WHERE
sin incluirlo en la cláusulaSELECT
. También puedes incluir el campo en ambas cláusulas si lo deseas.Esta consulta de ejemplo muestra métricas de
clicks
por nombre de campaña durante el período. Ten en cuenta quesegments.date
no está incluido en la cláusulaSELECT
.SELECT campaign.name, metrics.clicks FROM campaign WHERE segments.date > '2022-02-01' AND segments.date < '2022-03-01'
Si incluyes un campo de fecha principal en la cláusula
SELECT
, debes especificar una fecha o un período limitados en la cláusulaWHERE
. No es necesario que los campos especificados en las cláusulasSELECT
yWHERE
coincidan.Esta consulta de ejemplo muestra métricas
clicks
por nombre de campaña segmentada por mes para todos los días del período.SELECT campaign.name, metrics.clicks, segments.month FROM campaign WHERE segments.date > '2022-02-01' AND segments.date < '2022-03-01'
Fechas ISO 8601
Puedes usar el formato YYYY-MM-DD
(ISO 8601) para especificar fechas y períodos, por ejemplo:
WHERE segments.date BETWEEN '2022-06-01' AND '2022-06-30'
WHERE segments.date >= '2022-06-01' AND segments.date <= '2022-06-30'
Para los segmentos de fechas principales que requieren un período (segments.week
, segments.month
, segments.quarter
), puedes usar el operador =
con el primer día del período, por ejemplo:
WHERE segments.month = '2022-06-01'
Fechas predefinidas
También puedes utilizar las fechas y los períodos predefinidos:
Fechas predefinidas | |
---|---|
TODAY |
Solo por hoy. |
YESTERDAY |
Solo ayer. |
LAST_7_DAYS |
Últimos 7 días sin incluir el día de hoy. |
LAST_BUSINESS_WEEK |
Semana laboral anterior de 5 días (de lunes a viernes). |
THIS_MONTH |
Todos los días del mes actual. |
LAST_MONTH |
Todos los días del mes anterior |
LAST_14_DAYS |
Últimos 14 días, sin contar hoy. |
LAST_30_DAYS |
Últimos 30 días, sin contar hoy. |
THIS_WEEK_SUN_TODAY |
Período entre el domingo anterior y el día actual. |
THIS_WEEK_MON_TODAY |
Período entre el lunes anterior y el día actual |
LAST_WEEK_SUN_SAT |
Período de 7 días a partir del domingo anterior. |
LAST_WEEK_MON_SUN |
Período de 7 días a partir del lunes anterior. |
Ejemplo:
WHERE segments.date DURING LAST_30_DAYS
Ninguna métrica
Cuando ejecutas una consulta, es posible que encuentres métricas con un valor de cero para algunas entidades. Obtén más información para manejar cero métricas en tus consultas.
Tipos de enumeración UNKNOWN
Si se muestra un recurso con el tipo de datos enum UNKNOWN
, significa que el tipo no es totalmente compatible con la versión de la API. Estos recursos pueden haberse creado a través de otras interfaces. Por ejemplo, se introduce una campaña o un anuncio nuevos en la IU de Search Ads 360, pero aún no son compatibles con la versión de la API que consultas.
Puedes seleccionar métricas cuando un recurso tenga el tipo UNKNOWN
, pero debes tener en cuenta lo siguiente:
- Un recurso con un tipo
UNKNOWN
puede ser compatible más adelante, pero podría permanecerUNKNOWN
indefinidamente. - Los objetos nuevos con el tipo
UNKNOWN
pueden aparecer en cualquier momento. Estos objetos son retrocompatibles porque el valor enum ya está disponible. Incorporamos este cambio a los recursos a medida que están disponibles para que tengas una vista precisa de tu cuenta. Es posible que el recursoUNKNOWN
aparezca debido a una nueva actividad en tu cuenta a través de otras interfaces o porque un recurso ya no se admite formalmente. - Los recursos
UNKNOWN
pueden tener métricas detalladas adjuntas que puedes consultar. - Por lo general, los recursos de
UNKNOWN
son completamente visibles en la IU de Search Ads 360.