YouTube Reporting API - System-Managed Reports

YouTube автоматически создает набор управляемых системой отчетов о доходах от рекламы для владельцев контента, у которых есть доступ к соответствующим отчетам в Creator Studio . Эти отчеты предназначены для обеспечения программного доступа к данным, которые также доступны в отчетах, которые можно загрузить вручную и которые доступны в меню «Отчеты» в YouTube Creator Studio.

Примечание. API предоставляет доступ к другому набору отчетов, чем Creator Studio, хотя отчеты содержат схожие данные. Отчеты API могут иметь другие поля, а также использовать другие имена полей, чем отчеты Creator Studio.

Поскольку YouTube автоматически создает отчеты, управляемые системой, процесс получения этих отчетов отличается от процесса получения отчетов по массовым данным YouTube Analytics, доступных через API.

Получение отчетов

Следующие шаги объясняют, как получить отчеты, управляемые системой, через API.

Шаг 1. Получите учетные данные для авторизации

Все запросы API отчетов YouTube должны быть авторизованы. Руководство по авторизации объясняет, как использовать протокол OAuth 2.0 для получения токенов авторизации.

Запросы YouTube Reporting API используют следующие области авторизации:

Шаг 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 используйте параметр createAfter , чтобы получать только отчеты, созданные после определенной даты. (Пропустите параметр createdAfter при первом получении отчетов.)

    Каждый раз, когда вы получаете и успешно обрабатываете отчеты, сохраняйте временную метку, соответствующую дате и времени создания самого нового из этих отчетов. Затем обновите значение параметра createdAfter при каждом последующем вызове метода reports.list , чтобы гарантировать получение только новых отчетов, включая новые отчеты с заполненными данными, при каждом вызове API.

    В целях безопасности перед получением отчета также убедитесь, что идентификатор отчета еще не указан в вашей базе данных.

  • Сохраните идентификатор для каждого отчета, который вы скачали и обработали. Вы также можете хранить дополнительную информацию, например дату и время создания каждого отчета или startTime и endTime отчета, которые вместе определяют период, за который отчет содержит данные. В отчетах, которые извлекают большие объемы данных для YouTube Analytics, каждое задание, скорее всего, будет содержать множество отчетов, поскольку каждый отчет содержит данные за 24-часовой период. Задания, управляемые системой и охватывающие более длительные периоды времени, будут иметь меньше отчетов.

    Используйте идентификатор отчета, чтобы определить отчеты, которые вам еще нужно загрузить и импортировать. Однако если два новых отчета имеют одинаковые значения свойств startTime и endTime , импортируйте отчет только с новым значением createTime .

Характеристики отчета

Отчеты API представляют собой файлы .csv с указанием версий (значения, разделенные запятыми), которые имеют следующие характеристики:

• Каждый отчет содержит данные за уникальный период, продолжающийся с 00:00 по тихоокеанскому времени в дату начала отчета до 23:59 по тихоокеанскому времени в дату окончания отчета.

• Данные отчета не отсортированы.