YouTube Reporting API - Get Bulk Data Reports

O YouTube gera automaticamente um conjunto de relatórios de receita de publicidade gerenciados pelo sistema para proprietários de conteúdo que têm acesso aos relatórios correspondentes no Estúdio de Criação. Esses relatórios foram criados para fornecer acesso programático a dados que também estão disponíveis em relatórios para download manual acessíveis no menu "Relatórios" do YouTube Studio.

Observação:a API oferece acesso a um conjunto diferente de relatórios do YouTube Studio, mas eles contêm 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 para recuperar esses relatórios é diferente do processo para os relatórios de dados em massa do YouTube Analytics disponíveis pela API.

Como recuperar relatórios

As etapas a seguir explicam como recuperar relatórios gerenciados pelo sistema usando a API.

Etapa 1: extrair 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. Esse escopo dá acesso a métricas de atividade do usuário e a métricas estimadas de receita e performance de anúncios.

Etapa 2: recuperar o ID do job 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 vai precisar do valor da propriedade id do mesmo recurso na etapa a seguir.

O documento Relatórios lista os relatórios disponíveis, os IDs dos tipos 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órios compatíveis.

Etapa 3: extrair 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 a ID do job do relatório que você quer recuperar.

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

  • Use o parâmetro createdAfter para indicar que a API só deve retornar relatórios criados após um horário especificado. Esse parâmetro pode ser usado para garantir que a API retorne apenas relatórios que você ainda não processou.

  • Use o parâmetro startTimeBefore para indicar que a resposta da API só deve conter relatórios se os dados mais antigos estiverem antes da data especificada. Enquanto o parâmetro createdAfter se refere ao momento em que o relatório foi criado, essa data se refere aos dados no relatório.

  • Use o parâmetro startTimeAtOrAfter para indicar que a resposta da API só deve conter relatórios se os dados mais antigos estiverem na data especificada ou depois dela. Assim como o parâmetro startTimeBefore, esse valor corresponde aos dados do relatório, não ao momento em que ele 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 que os dados do relatório abrangem.
  • A propriedade downloadUrl do recurso identifica o URL de onde o relatório pode ser buscado.
  • A propriedade createTime do recurso especifica a data e a hora em que o relatório foi gerado. O aplicativo precisa armazenar esse valor e usá-lo para determinar se os relatórios baixados anteriormente mudaram.

Etapa 4: faça o download do relatório

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

Relatórios de processamento

Práticas recomendadas

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

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

  • Mantenha um registro dos relatórios baixados 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 apenas os relatórios criados após uma determinada data. Omita o parâmetro createdAfter na primeira vez que você recuperar relatórios.

      Sempre que você recuperar e processar relatórios, armazene o carimbo de data/hora correspondente à data e hora em que o mais recente desses relatórios foi criado. Em seguida, atualize o valor do parâmetro createdAfter em cada chamada sucessiva ao método reports.list para garantir que você só recupere relatórios novos, incluindo aqueles com dados preenchidos, sempre que chamar a API.

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

    • Armazene o ID de cada relatório que você baixou e processou. Também é possível armazenar outras informações, como a data e a hora em que cada relatório foi gerado ou o startTime e o 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 job provavelmente terá muitos relatórios, já que cada um deles contém dados de um período de 24 horas. Os jobs gerenciados pelo sistema que abrangem períodos mais longos terão menos relatórios.

      Use o ID para identificar os relatórios que ainda precisam ser baixados e importados. No entanto, se dois novos relatórios tiverem os mesmos valores de propriedade startTime e endTime, importe apenas o relatório com o valor createTime mais recente.

Características do relatório

Os relatórios da API são arquivos .csv (valores separados por vírgula) versionados com as seguintes características:

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

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