YouTube Reporting API - System-Managed Reports

O YouTube gera automaticamente um conjunto de relatórios de receita de anúncios gerenciados pelo sistema para os proprietários do conteúdo que têm acesso aos relatórios correspondentes no Estúdio de Criação. Esses relatórios foram desenvolvidos para oferecer acesso programático a dados que também estão disponíveis em relatórios para download manual, que podem ser acessados no menu "Relatórios" do YouTube Creator Studio.

Observação:a API dá acesso a um conjunto de relatórios diferente do Estúdio de Criação, embora os relatórios tenham dados semelhantes. Os relatórios da API podem ter campos diferentes e usar nomes de campo diferentes dos relatórios do Estúdio de Criação.

Como o YouTube gera automaticamente relatórios gerenciados pelo sistema, o processo de recuperação desses relatórios é diferente daquele dos relatórios de dados em massa do YouTube Analytics disponíveis por meio da API.

Como recuperar relatórios

As etapas a seguir explicam como recuperar relatórios gerenciados pelo sistema por meio da API.

Etapa 1: recuperar credenciais de autorização

Todas as solicitações da API YouTube Reporting precisam ser autorizadas. O Guia de autorização explica como usar o protocolo OAuth 2.0 para recuperar tokens de autorização.

As solicitações da API YouTube Reporting usam os seguintes escopos de autorização:

Escopos
https://www.googleapis.com/auth/yt-analytics.readonly Visualizar os relatórios do YouTube Analytics para seu conteúdo do YouTube. Este escopo fornece acesso às métricas de atividade do usuário, como contagens de visualização e de classificação.
https://www.googleapis.com/auth/yt-analytics-monetary.readonly Visualizar os relatórios monetários do YouTube Analytics para seu conteúdo do YouTube. Este escopo fornece acesso às métricas de atividade do usuário e às métricas estimadas de receita e performance de anúncios.

Etapa 2: recuperar o ID da tarefa do relatório desejado

Chame o método jobs.list para recuperar uma lista de jobs gerenciados pelo sistema. Defina o parâmetro includeSystemManaged como true.

A propriedade reportTypeId em cada recurso Job retornado identifica o tipo de relatório gerenciado pelo sistema associado a esse job. Seu aplicativo precisa do valor da propriedade id do mesmo recurso na etapa a seguir.

O documento Relatórios lista os relatórios disponíveis, os IDs de tipo de relatório e os campos que eles contêm. Também é possível usar o método reportTypes.list para recuperar uma lista de tipos de relatório compatíveis.

Etapa 3: recuperar o URL de download do relatório

Chame o método jobs.reports.list para recuperar uma lista de relatórios criados para o job. Na solicitação, defina o parâmetro jobId como o ID da tarefa do relatório que você quer recuperar.

É possível filtrar a lista de relatórios usando um ou todos os parâmetros a seguir:

  • Use o parâmetro createdAfter para indicar que a API precisa retornar relatórios criados após um período especificado. Esse parâmetro pode ser usado para garantir que a API retorne apenas relatórios que ainda não foram processados.

  • Use o parâmetro startTimeBefore para indicar que a resposta da API só vai conter relatórios se os dados mais antigos forem anteriores à data especificada. Enquanto o parâmetro createdAfter é referente ao momento em que o relatório foi criado, essa data refere-se aos dados dele.

  • Use o parâmetro startTimeAtOrAfter para indicar que a resposta da API só vai conter relatórios se os dados mais antigos estiverem na data especificada ou em datas posteriores. Assim como o parâmetro startTimeBefore, esse valor corresponde aos dados do relatório, e não à hora em que o relatório foi criado.

A resposta da API contém uma lista de recursos Report para esse job. Cada recurso se refere a um relatório que contém dados de um período exclusivo.

  • As propriedades startTime e endTime do recurso identificam o período abrangido pelos dados do relatório.
  • A propriedade downloadUrl do recurso identifica o URL em que o relatório pode ser buscado.

  • A propriedade createTime do recurso especifica a data e a hora em que o relatório foi gerado. Seu aplicativo deve armazenar esse valor e usá-lo para determinar se os relatórios baixados anteriormente foram alterados.

Etapa 4: fazer o download do relatório

Envie uma solicitação HTTP GET para o downloadUrl obtido na etapa 4 para recuperar o relatório.

Processamento de relatórios

Práticas recomendadas

Os aplicativos que usam a API YouTube Reporting devem sempre seguir estas práticas:

  • Use a linha do cabeçalho de um relatório para determinar a ordem das colunas. Por exemplo, não presuma que visualizações serão a primeira métrica retornada em um relatório só porque ela é a primeira métrica listada na descrição do relatório. Em vez disso, use a linha do cabeçalho do relatório para determinar qual coluna contém esses dados.

  • Mantenha um registro dos relatórios que você transferiu por download para evitar o processamento repetido do mesmo relatório. A lista a seguir sugere algumas maneiras de fazer isso.

    • Ao chamar o método reports.list, use o parâmetro createdAfter para recuperar somente os relatórios criados após uma determinada data. Omita o parâmetro createdAfter na primeira vez que você recuperar relatórios.

      Cada vez que você recuperar e processar relatórios, armazene o carimbo de data/hora correspondente à data e hora de quando o relatório mais recente foi criado. Em seguida, atualize o valor do parâmetro createdAfter em cada chamada sucessiva para o método reports.list. Isso garante que você esteja recuperando apenas novos relatórios, incluindo novos relatórios com dados preenchidos, sempre que chamar a API.

      Por segurança, antes de recuperar um relatório, verifique também se o ID dele já não está listado no seu banco de dados.

    • Armazene o ID de cada relatório que você transferiu por download e processou. Você também pode armazenar informações adicionais, como a data e hora em que cada relatório foi gerado ou o startTime e endTime do relatório, que, juntos, identificam o período em que o relatório contém dados. Para relatórios que recuperam dados em massa do YouTube Analytics, cada trabalho provavelmente terá muitos relatórios, já que cada relatório contém dados de um período de 24 horas. Os jobs gerenciados pelo sistema que abrangem períodos mais longos têm menos relatórios.

      Use o ID do relatório para identificar os relatórios que você ainda precisa transferir por download e importar. No entanto, se dois novos relatórios tiverem os mesmos valores de propriedade startTime e endTime, importe apenas com o valor createTime mais recente.

Características do relatório

Os relatórios de API são arquivos .csv (valores separados por vírgula) com controle de versões com as seguintes características:

  • Cada relatório contém dados de um período exclusivo que dura das 0h (horário do Pacífico) na data de início até as 23h59 (horário do Pacífico) na data de término do relatório.

  • Os dados do relatório não são classificados.