Crea informes de búsqueda en la API de informes de Search Ads 360

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

Nota: El lenguaje de consulta de Search Ads 360 proporciona información detallada para usar cada cláusula de la búsqueda.

Haz una solicitud

Para emitir una solicitud, debes pasar una cadena customer_id y una query a la interfaz SearchAds360Service.SearchStream o SearchAds360Service.Search.

Nota: En los siguientes ejemplos, se muestra la solicitud HTTP/JSON subyacente. Esto se usa para demostrar los conceptos. Te recomendamos que uses nuestras bibliotecas cliente que se basan en gRPC para enviar solicitudes en tu propia app.

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 recurso campaign es un recurso atribuido del recurso ad_group. Esto significa que puedes incluir campos como campaign.id y campaign.bidding_strategy_type en tu consulta cuando usas ad_group en la cláusula FROM.

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áusula SELECT 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áusula FROM, 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áusula SELECT 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áusula FROM, usa el menú desplegable Sí/No para filtrar las métricas que no están disponibles.

Nota: Cuando obtengas métricas relacionadas con la moneda (p.ej., cost_micros) para una fecha o un período específicos, asegúrate de incluir segments.date en la cláusula SELECT.

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 recurso campaign, como campaign.name, cuando uses campaign_budget en tu cláusula FROM, campaign.resource_name se mostrará y se segmentará automáticamente, porque campaign es un recurso de segmentación de campaign_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 campo segments que enumera todos los campos de recursos compatibles, los campos metrics y otros campos segments que puedes incluir en tu cláusula SELECT.

Nota: Consulta Lenguaje de consulta de Search Ads 360 para aprender a usar cada cláusula de una consulta.

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

Precaución: La cantidad de filas puede aumentar de forma exponencial para cada campo segments adicional que agregues a tu consulta.

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

Nota: El campo resource_name del recurso en la cláusula FROM siempre se muestra, incluso cuando no se especifica en la cláusula SELECT. Consulta el campo resource_name para obtener más información.

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áusula SELECT. 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 que segments.date no está incluido en la cláusula SELECT.

  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áusula WHERE. No es necesario que los campos especificados en las cláusulas SELECT y WHERE 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'

Nota: Si especificas una fecha que no sea el primer día de un período, recibirás un error MISALIGNED_DATE_FOR_FILTER.

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 permanecer UNKNOWN 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 recurso UNKNOWN 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.