YouTube Reporting API - System-Managed Reports

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

YouTube genera automáticamente un conjunto de informes de ingresos por anuncios administrados por el sistema para los propietarios de contenido que tienen acceso a los informes correspondientes en Creator Studio. Estos informes están diseñados para proporcionar acceso programático a los datos que también están disponibles en los informes descargables manualmente a los que se puede acceder en la sección Informes de YouTube Creator Studio.

Nota: La API proporciona acceso a un conjunto de informes diferente del de Creator Studio, aunque los informes contienen datos similares. Es posible que los informes de la API tengan campos distintos y que, además, usen nombres distintos que los de Creator Studio.

Debido a que YouTube genera automáticamente informes administrados por el sistema, el proceso para recuperar estos informes es diferente al de los informes de datos masivos de YouTube Analytics disponibles a través de la API.

Cómo recuperar informes

Los siguientes pasos explican cómo recuperar informes administrados por el sistema a través de la API.

Paso 1: Recupera las credenciales de autorización

Se deben autorizar todas las solicitudes de la API de informes de YouTube. La Guía de autorización explica cómo utilizar el protocolo OAuth 2.0 para recuperar tokens de autorización.

Las solicitudes de la API de informes de YouTube utilizan los siguientes alcances de autorización:

Permisos
https://www.googleapis.com/auth/yt-analytics.readonly Permite ver informes de YouTube Analytics sobre tu contenido de YouTube. Este alcance proporciona acceso a las métricas de actividad del usuario, como el número de reproducciones y de calificaciones.
https://www.googleapis.com/auth/yt-analytics-monetary.readonly Permite ver informes monetarios de YouTube Analytics sobre tu contenido de YouTube. Este alcance proporciona acceso a las métricas de actividad del usuario y a las estimaciones de ingresos y de rendimiento de los anuncios.

Paso 2: Recupera el ID de trabajo para el informe deseado

Llama al método jobs.list para recuperar una lista de trabajos administrados por el sistema. Establece el parámetro includeSystemManaged en true.

La propiedad reportTypeId en cada recurso Job que se muestra identifica el tipo de informe administrado por el sistema asociado con ese trabajo. Tu aplicación necesita el valor de propiedad id del mismo recurso en el siguiente paso.

En el documento Informes, se enumeran los informes disponibles, sus ID de tipo de informe y los campos que contienen. También puedes usar el método reportTypes.list para recuperar una lista de los tipos de informes admitidos.

Paso 3: Recuperar la URL de descarga del informe

Llama al método jobs.reports.list a fin de recuperar una lista de informes creados para el trabajo. En la solicitud, establece el parámetro jobId en el ID del trabajo del informe que deseas recuperar.

Puede filtrar la lista de informes mediante uno o todos los parámetros siguientes:

  • Usa el parámetro createdAfter para indicar que la API solo debe mostrar informes creados después de un tiempo específico. Este parámetro se puede usar para garantizar que la API solo muestre informes que no hayas procesado.

  • Usa el parámetro startTimeBefore para indicar que la respuesta de la API solo debe contener informes si los primeros datos del informe son anteriores a la fecha especificada. Mientras que el parámetro createdAfter corresponde a la hora en que se creó el informe, esta fecha corresponde a los datos del informe.

  • Usa el parámetro startTimeAtOrAfter para indicar que la respuesta de la API solo debe contener informes si los primeros datos del informe son la fecha especificada o una posterior. Al igual que el parámetro startTimeBefore, este valor corresponde a los datos del informe y no a la hora en que se creó el informe.

La respuesta de la API contiene una lista de recursos Report para ese trabajo. Cada recurso se refiere a un informe que contiene datos de un período único.

  • Las propiedades startTime y endTime del recurso identifican el período que abarcan los datos del informe.
  • La propiedad downloadUrl del recurso identifica la URL desde la cual se puede recuperar el informe.

  • La propiedad createTime del recurso especifica la fecha y hora en que se generó el informe. Tu aplicación debe almacenar este valor y usarlo para determinar si los informes descargados previamente han cambiado.

Paso 4: Descargue el informe

Envía una solicitud GET de HTTP a la downloadUrl que obtuviste en el paso 4 para recuperar el informe.

Procesando informes

Prácticas recomendadas

Las aplicaciones que utilizan la API de informes de YouTube siempre deben seguir estas prácticas:

  • Use la fila de encabezado de un informe para determinar el orden de las columnas del informe. Por ejemplo, no supongas que las vistas serán la primera métrica que se muestra en un informe solo porque es la primera métrica que aparece en la descripción de un informe. En su lugar, utilice la fila del encabezado del informe para determinar qué columna contiene esos datos.

  • Conserve un registro de los informes que ha descargado para evitar el procesamiento repetido del mismo informe. En la siguiente lista, se sugieren dos formas de hacerlo.

    • Cuando llames al método reports.list, usa el parámetro createdAfter para recuperar solo los informes creados después de una fecha determinada. (Omite el parámetro createdAfter la primera vez que recuperas informes).

      Cada vez que recupere y procese con éxito los informes, almacene la marca de tiempo correspondiente a la fecha y hora en que se creó la más reciente. Luego, actualiza el valor del parámetro createdAfter en cada llamada sucesiva al método reports.list para asegurarte de que solo recuperes informes nuevos, incluidos los informes nuevos con datos reabastecidos, cada vez que llames a la API.

      Como medida de protección, antes de recuperar un informe, verifique que el ID del informe no se incluya en la lista en su base de datos.

    • Almacene el ID para cada informe que descargó y procesó. También puede almacenar información adicional, como la fecha y hora en la que se generó cada informe, o los informes startTime y endTime, que en conjunto identifican el período para el cual el informe contiene datos. Para los informes que recuperan datos masivos de YouTube Analytics, es probable que cada trabajo tenga muchos informes, ya que cada informe contiene datos por un período de 24 horas. Los trabajos administrados por el sistema que abarcan períodos más largos tendrán menos informes.

      Use el ID de informe para identificar los informes que aún debe descargar e importar. Sin embargo, si dos informes nuevos tienen los mismos valores de propiedad startTime y endTime, solo importa el informe con el valor createTime más reciente.

Características del informe

Los informes de API son versiones de archivos .csv (valores separados por comas) que tienen las siguientes características:

  • Cada informe contiene datos de un período único que abarca desde las 12:00 a.m. hasta la hora del Pacífico de la fecha de inicio del informe hasta las 11:59 p.m. de la hora del Pacífico de la fecha de finalización del informe.

  • Los datos del informe no están ordenados.