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

Lee las secciones que se indican a continuación 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 para la búsqueda y la generación 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 consultas de Search Ads 360. Puedes definir consultas para lo siguiente:

• Recupera atributos específicos de objetos.
• Recupera métricas de rendimiento de los objetos en función de 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, independientemente del tamaño del informe.

• Los paquetes de datos comienzan a descargarse de inmediato, y todo el resultado se almacena 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 la transmisión completa.

Search

Envía varias solicitudes paginadas para descargar el informe completo.

Por lo general, SearchStream ofrece un mejor rendimiento porque elimina el tiempo de red de ida y vuelta necesario para solicitar páginas individuales. Te recomendamos que uses SearchStream para todos los informes de más de 10,000 filas. No hay una diferencia significativa de rendimiento entre los métodos para informes más pequeños (< 10,000 filas).

El método que uses no afectará 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.

Ejemplo de búsqueda

Esta consulta de ejemplo muestra los datos de rendimiento de una cuenta de los últimos 30 días por campaña y 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 sobre cómo usar cada cláusula de la búsqueda.

Haz una solicitud

Para enviar una solicitud, debes pasar una cadena customer_id y 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 demonstrar 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 informes de Search Ads 360 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 incluye un ejemplo completo de la definición del informe para searchStream adjunta en una solicitud HTTP POST:

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 se incluyen 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

La sección Referencia 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 es apropiada) y mucho más:

Recursos atribuidos

Para algunos recursos, es posible que tengas la opción de unir implícitamente 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 tu 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 incluye vínculos a más detalles sobre el campo, como su descripción, categoría, tipo de datos, URL del tipo y configuración filtrable, seleccionable, ordenable y repetida.

Columna de segmentos

No todos los campos de segmento se pueden seleccionar con un recurso determinado.

En la columna Segments, se enumeran los campos segments que puedes usar en la misma cláusula SELECT que los campos del recurso. Cada campo incluye un vínculo a los detalles completos del campo, como su descripción, categoría, tipo de datos, URL de tipo y configuración filtrable, seleccionable, ordenable y repetida. Si usas el recurso en tu 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 incluye un vínculo a los detalles completos del campo, como su descripción, categoría, tipo de datos, URL de tipo y configuración filtrable, seleccionable, ordenable y repetida. Si usas el recurso en tu 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 específica o un período, 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 tu cláusula FROM. Por ejemplo, si seleccionas un campo de recursos campaign, como campaign.name, cuando uses campaign_budget en tu cláusula FROM, campaign.resource_name se mostrará y segmentará automáticamente, ya que 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.

Seleccionable con

Algunos campos segments no son compatibles con otros recursos, segmentos ni métricas.

La página segments incluye un elemento Selectable with expandible 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 tu consulta.

Por ejemplo, segments.device en la siguiente consulta genera 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 ven similar 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 ver una lista de los campos de segmento disponibles que puedes usar.

Varios segmentos

Precaución: La cantidad de filas puede aumentar de forma exponencial por 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 para 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 implícitamente por cada instancia del recurso principal, pero no por los valores de los campos seleccionados individuales.

La siguiente consulta de ejemplo muestra 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

Cada informe se segmenta inicialmente por el recurso especificado en la cláusula FROM. Las métricas se segmentan según 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.

Esta consulta de ejemplo muestra automáticamente ad_group.resource_name y la usa de forma implícita para segmentar métricas a nivel de ad_group.

SELECT metrics.impressions
FROM ad_group

La cadena JSON que se muestra se parece 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 de fecha principales

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

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

Esta consulta de ejemplo muestra las métricas clicks de la campaña de 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 fecha 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 fecha:

• Puedes usar un campo de fecha principal en la cláusula WHERE sin incluirlo en la cláusula SELECT. Si lo deseas, también puedes incluir el campo en ambas cláusulas.

  Esta consulta de ejemplo muestra las métricas clicks por nombre de campaña durante el período. Ten en cuenta que segments.date no se incluye 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 tu cláusula SELECT, debes especificar una fecha o un período finitos en tu cláusula WHERE. No es necesario que coincidan los campos especificados en las cláusulas SELECT y WHERE.

  Esta consulta de ejemplo muestra las métricas clicks por nombre de campaña segmentadas 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'

En el caso de los segmentos de fecha 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 es el primer día de un período, recibirás un error MISALIGNED_DATE_FOR_FILTER.

Fechas predefinidas

También puedes usar las siguientes fechas y períodos predefinidos:

Fechas predefinidas
TODAY	Solo por hoy.
YESTERDAY	Solo ayer.
LAST_7_DAYS	Los 7 días anteriores, sin incluir hoy.
LAST_BUSINESS_WEEK	La 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	Los 14 días anteriores, sin incluir hoy
LAST_30_DAYS	Los últimos 30 días, sin incluir 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

Métricas cero

Cuando ejecutas una consulta, es posible que encuentres métricas con un valor de cero para algunas entidades. Obtén información para controlar las métricas cero en tus consultas.

Tipos de enumeración UNKNOWN

Si se muestra un recurso con el tipo de datos de enumeración UNKNOWN, significa que el tipo no es totalmente compatible con la versión de la API. Es posible que estos recursos se hayan creado a través de otras interfaces. Por ejemplo, se presenta 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 tiene el tipo UNKNOWN, pero debes tener en cuenta lo siguiente:

• Es posible que un recurso con un tipo UNKNOWN sea compatible más adelante, pero podría permanecer como UNKNOWN de forma indefinida.
• Pueden aparecer objetos nuevos con el tipo UNKNOWN en cualquier momento. Estos objetos son retrocompatibles porque el valor de enumeración ya está disponible. Con este cambio, presentamos 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 actividad nueva en tu cuenta a través de otras interfaces o porque un recurso ya no es compatible de forma formal.
• 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.