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.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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 para la búsqueda y la generación de 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 se pasan en una cadena de consulta escrita en el lenguaje de consultas de Search Ads 360. Puedes definir consultas para lo siguiente:

Recuperar atributos específicos de objetos
Recuperar métricas de rendimiento para objetos según un período
Ordenar objetos según sus atributos
Filtrar los resultados con condiciones que especifiquen qué objetos mostrar
Limitar 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 id y name campos establecidos, y un metrics objeto con su clicks campo establecido.

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 todo el resultado 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 finalice 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 ida y vuelta de la red 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 en el rendimiento entre los métodos para informes más pequeños (<10,000 filas).

El método que uses no afecta tus cuotas y límites de la API: una sola consulta o informe se cuenta como una operación, independientemente de si los resultados están paginados o transmitidos.

Consulta de búsqueda de ejemplo

Esta consulta de ejemplo muestra datos de rendimiento de una cuenta de 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 customer_id y una cadena query a la SearchAds360Service.SearchStream o SearchAds360Service.Search interfaz.

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 del 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"
}

Procesa una respuesta

SearchAds360Service muestra una lista de SearchAds360Row objetos.

Cada SearchAds360Row representa un objeto que muestra la consulta. Cada objeto consta de 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

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 campos de segmentos y 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 adecuada), entre otras cosas:

Recursos atribuidos

Para algunos recursos, es posible que tengas la opción de unir implícitamente los recursos relacionados seleccionando sus campos junto con los campos del recurso en tu cláusula FROM. Por ejemplo, el campaign recurso es un recurso atribuido del ad_group recurso. 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 recurso se vincula a más detalles sobre el campo, incluida su descripción, categoría, tipo de datos, URL de tipo y configuración de filtrado, selección, ordenamiento y repetición.

Columna de 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 se vincula a detalles completos sobre el campo, incluida su descripción, categoría, tipo de datos, URL de tipo y configuración de filtrado, selección, ordenamiento y repetición. 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 se vincula a detalles completos sobre el campo, incluida su descripción, categoría, tipo de datos, URL de tipo y configuración de filtrado, selección, ordenamiento y repetición. 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.

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 campaign campo de recurso, como campaign.name, cuando usas 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 son incompatibles con otros recursos, segmentos y métricas.

La página segments incluye un Seleccionable con 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.

Segmentación

Puedes segmentar los resultados de la búsqueda agregando un segments.FIELD_NAME campo a la SELECT cláusula de tu consulta.

Por ejemplo, segments.device en la siguiente consulta genera un informe con una fila para las impressions de cada dispositivo para el recurso especificado en la FROM cláusula.

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions
FROM campaign

Los resultados que muestra SearchAds360Service.SearchStream se ven de la siguiente manera en la 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 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 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

Inicialmente, cada informe se segmenta por el recurso especificado en la cláusula FROM. Las métricas se segmentan por el campo resource_name de este recurso.

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

SELECT metrics.impressions
FROM ad_group

La cadena JSON que se muestra se ve de la siguiente manera:

{
  "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 WHERE cláusula 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 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 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 de segmentos de fecha principales:

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

Esta consulta de ejemplo muestra las métricas de 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 definidos en tu cláusula WHERE. Los campos especificados en las cláusulas SELECT y WHERE no tienen que coincidir.

Esta consulta de ejemplo muestra las métricas de 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'

Para 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'

Fechas predefinidas

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

Fechas predefinidas
`TODAY`	Solo 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 30 días anteriores, 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 sobre cómo 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 introduce una nueva campaña o anuncio 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 tiene el tipo UNKNOWN, pero debes tener en cuenta lo siguiente:

Es posible que se admita un recurso con un tipo UNKNOWN más adelante, pero podría permanecer UNKNOWN de forma indefinida.
Es posible que aparezcan objetos nuevos con el tipo UNKNOWN en cualquier momento. Estos objetos son retrocompatibles porque el valor de enumeración ya está disponible. Presentamos recursos con este cambio a medida que están disponibles para que tengas una vista precisa de tu cuenta. El recurso UNKNOWN puede aparecer debido a una nueva actividad en tu cuenta a través de otras interfaces o porque un recurso ya no es compatible formalmente.
Los recursos UNKNOWN pueden tener métricas detalladas adjuntas que puedes consultar.
Por lo general, los recursos UNKNOWN son totalmente visibles en la IU de Search Ads 360.