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âmetrocreatedAfter
é 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âmetrostartTimeBefore
, 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
eendTime
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âmetrocreatedAfter
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étodoreports.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
eendTime
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
eendTime
, importe apenas com o valorcreateTime
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.