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

Lee las secciones a continuación para obtener información sobre cómo crear informes de búsqueda en los anuncios de búsqueda API de 360 Reporting.

Servicio de búsqueda

La API de Search Ads 360 Reporting proporciona un servicio especial para buscar y informes.

SearchAds360Service es un servicio unificado de recuperación de objetos y generación de informes que proporciona dos métodos de búsqueda: SearchStream y Search. Las búsquedas son pasar una cadena de consulta escrita en el lenguaje de consulta de Search Ads 360 Puedes definir consultas para lo siguiente:

• Recupera atributos específicos de los objetos.
• Recupera métricas de rendimiento de 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 devuelven 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 y un objeto metrics con su campo clicks configurado.

Métodos de búsqueda

SearchStream

Envía una sola solicitud e 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 con el resultado completo. 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 toda la transmisión para terminarla.

Search

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

SearchStream suele ofrecer un mejor rendimiento porque elimina la necesidad 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 un valor significativo diferencia de rendimiento entre los métodos para informes más pequeños (menos de 10,000 filas).

El método que utilizas no afecta las cuotas y los límites de tu API: se hace una única consulta o informe. se cuentan como una operación, independientemente de si los resultados se paginan o se transmiten.

Ejemplo de búsqueda

Esta consulta de ejemplo devuelve los datos de rendimiento de una cuenta durante los últimos 30 días por campaña, segmentada 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 emitir una solicitud, debes pasar una cadena customer_id y una query. a SearchAds360Service.SearchStream o SearchAds360Service.Search interfaz de usuario.

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

La solicitud consiste en un POST HTTP a la API de Search Ads 360 Reporting servidor en cualquiera de las siguientes URL:

https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream

https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:search

Aquí se incluye un ejemplo completo de la definición del informe para searchStream 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 según los campos solicitados en la cláusula SELECT de la consulta. Atributos no incluidos en SELECT no se propagan en los objetos de la respuesta.

Por ejemplo, la siguiente consulta propaga cada objeto SearchAds360Row con solo el elemento campaign.id, campaign.name y campaign.status. Otros atributos, como Se omiten campaign.engine_id o campaign.bidding_strategy_type.

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign

Documentación de referencia

Sección Referencia incluye toda la información que necesitas para usar cada artefacto de forma correcta. Hay una página para cada recurso, por ejemplo, ad_group y campaign Las páginas segments y metrics Enumera todos los segmentos y campos de métricas disponibles.

Algunos recursos, segmentos y métricas son incompatibles y no se pueden usar mientras que otras son totalmente compatibles y se complementan mutuamente. Cada la página del recurso incluye la siguiente información (si está disponible y apropiadas) y mucho más:

Recursos atribuidos

Para algunos recursos, puedes tener la opción de unir implícitamente los recursos recursos seleccionando 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 cuando uses 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 se vincula con más detalles sobre el campo, incluida su descripción, categoría, tipo de datos, tipo URL, y filtrables, seleccionables, que se puede ordenar y repetir.

Columna Segmentos

No todos los campos de segmento 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 tiene un vínculo detalles sobre el campo, incluida su descripción, categoría, tipo de datos, tipo URL y el parámetro de configuración filtrable, seleccionable, ordenable y repetido. Si eres Si usas el recurso de 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 tiene un vínculo detalles sobre el campo, incluida su descripción, categoría, tipo de datos, tipo URL y el parámetro de configuración filtrable, seleccionable, ordenable y repetido. Si eres Con 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) de un fecha o período, asegúrate de incluir segmentos.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 usando campaign_budget en tu cláusula FROM, campaign.resource_name se devolverán y se segmentarán automáticamente, porque campaign es una recurso de segmentación de campaign_budget.

La sección Recursos de segmentación enumera 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 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 obtener información sobre cómo usar cada cláusula. de una consulta.

Segmentación

Para segmentar los resultados de la búsqueda, agrega una segments.FIELD_NAME a la cláusula SELECT de tu consulta.

Por ejemplo, segments.device en la a continuación, da como resultado un informe con una fila para los 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 devuelve SearchAds360Service.SearchStream tienen un aspecto similar como 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 un lista de campos de segmento disponibles que puedes utilizar.

Varios segmentos

Precaución: La cantidad de filas puede aumentar exponencialmente por cada fila adicional segments que agregues a tu consulta.

Puedes especificar varios segmentos en la cláusula SELECT de tu consulta. El contiene un objeto SearchAds360Row por cada combinación de instancia del recurso principal especificado en la cláusula FROM y en la value de cada campo segment seleccionado.

Por ejemplo, la siguiente consulta devolverá 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 de la instancia 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

Inicialmente, cada informe se segmenta según el recurso especificado en el archivo FROM. . Las métricas están segmentadas por el campo resource_name de este recurso

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

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

SELECT metrics.impressions
FROM ad_group

La cadena 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 de fechas principales

Puedes usar segmentos de fechas principales en tu cláusula WHERE para especificar una fecha. o 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 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 fechas principales son una excepción a la regla general que establece no puedes usar un campo de segmentos en tu cláusula WHERE, a menos que también incluyas el en tu cláusula SELECT. Consulta Filtrado prohibido para obtener más información información.

Reglas principales de los segmentos de fechas:

• Puedes usar un campo de fecha principal en la cláusula WHERE sin incluirlo en la SELECT. También puedes incluir el campo en ambas cláusulas si quieres.

  Esta consulta de ejemplo muestra métricas de clicks por nombre de campaña durante la fecha del rango de destino de la ruta. 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 período finitos en tu cláusula WHERE. Los campos especificados en el No es necesario que las cláusulas SELECT y WHERE coincidan.

  Esta consulta de ejemplo muestra métricas de clicks por nombre de campaña segmentadas por mes para todos los días incluidos en el período.

  SELECT
    campaign.name,
    metrics.clicks,
    segments.month
  FROM campaign
  WHERE segments.date > '2022-02-01'
    AND segments.date < '2022-03-01'
  

Fechas de la norma 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 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 es el primer día de un período, deberás recibes un error MISALIGNED_DATE_FOR_FILTER.

Fechas predefinidas

También puedes utilizar los siguientes períodos y fechas predefinidos:

Fechas predefinidas
TODAY	Solo por hoy.
YESTERDAY	Solo ayer.
LAST_7_DAYS	Últimos 7 días sin incluir hoy.
LAST_BUSINESS_WEEK	Semana hábil 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 incluir el día de hoy
LAST_30_DAYS	Ú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	en un período de 7 días a partir del domingo anterior.
LAST_WEEK_MON_SUN	de 7 días a partir del lunes anterior.

Ejemplo:

WHERE segments.date DURING LAST_30_DAYS

Cero métricas

Cuando ejecutes una consulta, es posible que encuentres métricas con valor cero 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, esto significa que El tipo no es totalmente compatible con la versión de la API. Estos recursos pueden tener se crearon a través de otras interfaces. Por ejemplo, cuando se agrega una nueva campaña o anuncio que se introdujo en la IU de Search Ads 360, pero aún no es compatible con la versión de la API que estás consultando.

Aún puedes seleccionar métricas cuando un recurso tenga el tipo UNKNOWN, pero debes tener en cuenta lo siguiente:

• Es posible que más adelante se admita un recurso con el tipo UNKNOWN, pero podría permanecer UNKNOWN indefinidamente.
• Los objetos nuevos con el tipo UNKNOWN pueden aparecer en cualquier momento. Estos objetos se es retrocompatible porque el valor enum ya está disponible. Presentamos recursos con este cambio a medida que estén disponibles para que tengas un vista de tu cuenta. El recurso UNKNOWN puede aparecer debido a actividad en tu cuenta a través de otras interfaces o porque un recurso deja de recibir asistencia formal.
• Es posible que UNKNOWN recurso tenga métricas detalladas adjuntas que puedes para cada búsqueda.
• Los recursos de UNKNOWN suelen ser completamente visibles en la IU de Search Ads 360.