YouTube автоматически генерирует набор отчетов о доходах от рекламы для владельцев контента, имеющих доступ к соответствующим отчетам в Creator Studio . Эти отчеты предназначены для обеспечения программного доступа к данным, которые также доступны в отчетах, загружаемых вручную и открываемых в меню «Отчеты» в YouTube Creator Studio.
Примечание: API предоставляет доступ к другому набору отчетов, чем Creator Studio, хотя отчеты содержат схожие данные. Отчеты, созданные через API, могут иметь другие поля и использовать другие названия полей, чем отчеты Creator Studio.
Поскольку YouTube автоматически генерирует отчеты, управляемые системой, процесс получения этих отчетов отличается от процесса получения отчетов по массовым данным YouTube Analytics, доступных через API.
Получение отчетов
Следующие шаги описывают, как получать отчеты, управляемые системой, через API.
Шаг 1: Получение учетных данных авторизации
Все запросы к API отчетов YouTube должны быть авторизованы. В руководстве по авторизации объясняется, как использовать протокол OAuth 2.0 для получения токенов авторизации.
Для запросов к API отчетов YouTube используются следующие области авторизации:
| Объем | Описание |
|---|---|
| https://www.googleapis.com/auth/yt-analytics.readonly | Просматривайте отчеты YouTube Analytics по вашему контенту на YouTube. Этот раздел предоставляет доступ к показателям активности пользователей, таким как количество просмотров и оценок. |
| https://www.googleapis.com/auth/yt-analytics-monetary.readonly | Просматривайте финансовые отчеты YouTube Analytics по вашему контенту на YouTube. Этот раздел предоставляет доступ к показателям активности пользователей, а также к прогнозируемым показателям дохода и эффективности рекламы. |
Шаг 2: Получите идентификатор задания для нужного отчета.
Вызовите метод jobs.list , чтобы получить список заданий, управляемых системой. Установите параметр includeSystemManaged в true .
Свойство reportTypeId в каждом возвращаемом ресурсе Job определяет тип управляемого системой отчета, связанного с этим заданием. Вашему приложению потребуется значение свойства id из того же ресурса на следующем шаге.
В документе «Отчеты» перечислены доступные отчеты, их идентификаторы типов отчетов и содержащиеся в них поля. Вы также можете использовать метод reportTypes.list для получения списка поддерживаемых типов отчетов.
Шаг 3: Получите URL-адрес для скачивания отчета.
Вызовите метод jobs.reports.list , чтобы получить список отчетов, созданных для задания. В запросе установите параметр jobId равным идентификатору задания для отчета, который вы хотите получить.
Вы можете отфильтровать список отчетов, используя любой или все из следующих параметров:
Используйте параметр
createdAfter, чтобы указать, что API должен возвращать только отчеты, созданные после указанного времени. Этот параметр можно использовать для того, чтобы гарантировать, что API будет возвращать только те отчеты, которые вы еще не обработали.Параметр
startTimeBeforeуказывает, что ответ API должен содержать отчеты только в том случае, если самые ранние данные в отчете относятся к периоду до указанной даты. В то время как параметрcreatedAfterотносится ко времени создания отчета, эта дата относится к данным в отчете.Параметр
startTimeAtOrAfterуказывает, что ответ API должен содержать отчеты только в том случае, если самые ранние данные в отчете относятся к указанной дате или позже. Как и параметрstartTimeBefore, значение этого параметра соответствует данным в отчете, а не времени его создания.
В ответе API содержится список ресурсов Report для данного задания. Каждый ресурс ссылается на отчет, содержащий данные за уникальный период.
- Свойства
startTimeиendTimeресурса определяют период времени, который охватывают данные отчета. - Свойство
downloadUrlресурса определяет URL-адрес, с которого можно получить отчет. - Свойство
createTimeресурса указывает дату и время создания отчета. Ваше приложение должно сохранить это значение и использовать его для определения того, изменились ли ранее загруженные отчеты.
Шаг 4: Скачайте отчет
Для получения отчета отправьте HTTP GET-запрос по адресу downloadUrl полученному на шаге 4.
Обработка отчетов
Передовые методы
Приложения, использующие API отчетов YouTube, всегда должны следовать этим рекомендациям:
Используйте строку заголовка отчета, чтобы определить порядок столбцов отчета. Например, не следует предполагать, что количество просмотров будет первым показателем, возвращаемым в отчете, только потому, что это первый показатель, указанный в описании отчета. Вместо этого используйте строку заголовка отчета, чтобы определить, в каком столбце содержатся эти данные.
Сохраняйте записи о загруженных отчетах, чтобы избежать повторной обработки одного и того же отчета. Ниже приведен список нескольких способов, как это сделать.
При вызове метода
reports.listиспользуйте параметр createdAfter , чтобы получать только отчеты, созданные после определенной даты. (При первом получении отчетов параметрcreatedAfterследует опустить.)Каждый раз, когда вы получаете и успешно обрабатываете отчеты, сохраняйте метку времени, соответствующую дате и времени создания самого нового из этих отчетов. Затем обновляйте значение параметра
createdAfterпри каждом последующем вызове методаreports.list, чтобы гарантировать, что при каждом обращении к API вы получаете только новые отчеты, включая новые отчеты с заполненными данными.В качестве меры предосторожности, перед получением отчета также убедитесь, что идентификатор отчета еще не указан в вашей базе данных.
Сохраните идентификатор каждого загруженного и обработанного отчета. Вы также можете сохранить дополнительную информацию, такую как дата и время создания каждого отчета, а также
startTimeиendTimeотчета, которые вместе определяют период, за который отчет содержит данные. Для отчетов, извлекающих большие объемы данных для YouTube Analytics, каждое задание, вероятно, будет содержать много отчетов, поскольку каждый отчет содержит данные за 24-часовой период. Системные задания, охватывающие более длительные периоды времени, будут содержать меньше отчетов.Используйте идентификатор отчета, чтобы определить отчеты, которые вам еще нужно загрузить и импортировать. Однако, если два новых отчета имеют одинаковые значения свойств
startTimeиendTime, импортируйте только тот отчет, у которого значениеcreateTimeбольше.
Характеристики отчета
Отчеты API представляют собой версионированные файлы .csv (значения, разделенные запятыми), обладающие следующими характеристиками:
Каждый отчет содержит данные за уникальный период, начинающийся в 00:00 по тихоокеанскому времени в день начала отчета и заканчивающийся в 23:59 по тихоокеанскому времени в день окончания отчета.
Данные в отчете не отсортированы.