Важно: для запросов API к этому методу теперь требуется доступ к области https://www.googleapis.com/auth/youtube.readonly
.
Этот метод позволяет получать множество различных аналитических отчётов. В каждом запросе используются параметры запроса, указывающие идентификатор канала или владельца контента, дату начала, дату окончания и как минимум одну метрику. Вы также можете указать дополнительные параметры запроса, такие как параметры, фильтры и инструкции по сортировке.
- Метрики — это отдельные показатели активности пользователя, такие как просмотры видео или оценки (лайки и дизлайки).
- Параметры — это общие критерии, используемые для агрегирования данных, например, дата совершения пользователем действия или страна, в которой находились пользователи. В отчёте каждая строка данных содержит уникальную комбинацию значений параметров.
- Фильтры — это значения параметров, определяющие, какие данные будут извлечены. Например, вы можете извлечь данные по конкретной стране, конкретному видео или группе видео.
Примечание: отчеты владельцев контента доступны только партнерам YouTube по контенту, которые участвуют в партнерской программе YouTube .
Распространенные варианты использования
Запрос
HTTP-запрос
GET https://youtubeanalytics.googleapis.com/v2/reports
Все запросы к API YouTube Analytics должны быть авторизованы. В руководстве по авторизации объясняется, как использовать протокол OAuth 2.0 для получения токенов авторизации.
Запросы API YouTube Analytics используют следующие области авторизации:
Области применения | |
---|---|
https://www.googleapis.com/auth/yt-analytics.readonly | Просматривайте отчёты YouTube Analytics для вашего контента на YouTube. Эта область действия предоставляет доступ к показателям активности пользователей, таким как количество просмотров и оценок. |
https://www.googleapis.com/auth/yt-analytics-monetary.readonly | Просматривайте финансовые отчёты YouTube Analytics для вашего контента на YouTube. Эта область действия предоставляет доступ к показателям активности пользователей, а также к предполагаемым показателям дохода и эффективности рекламы. |
https://www.googleapis.com/auth/youtube | Управляйте своим аккаунтом YouTube. В API YouTube Analytics владельцы каналов используют эту область для управления группами и элементами групп YouTube Analytics. |
https://www.googleapis.com/auth/youtubepartner | Просмотр и управление ресурсами YouTube и связанным контентом на YouTube. В API YouTube Analytics владельцы контента используют эту область для управления группами и элементами групп YouTube Analytics. |
Параметры
В таблицах ниже перечислены обязательные и необязательные параметры запросов API для получения отчётов. Стандартные параметры запросов, перечисленные в таблице, также являются необязательными и поддерживаются многими API Google.
Параметры | ||
---|---|---|
Обязательные параметры | ||
endDate | string Конечная дата для получения данных YouTube Analytics . Значение должно быть указано в формате YYYY-MM-DD .Ответ API содержит данные до последнего дня, для которого все метрики в запросе доступны на момент запроса. Например, если в запросе указана конечная дата 5 июля 2017 г., а значения всех запрошенных метрик доступны только до 3 июля 2017 г., это будет последняя дата, данные для которой включены в ответ. (Это справедливо даже если данные для некоторых запрошенных метрик доступны на 4 июля 2017 г.) Примечание: в версии 1 API этот параметр назывался end-date . | |
ids | string Идентифицирует канал YouTube или владельца контента, для которого вы извлекаете данные YouTube Analytics .
| |
metrics | string Список метрик YouTube Analytics , разделенных запятыми, таких как views или likes,dislikes . См. документацию по отчётам по каналам или отчётам владельцев контента, чтобы узнать список доступных отчётов и метрик, доступных в каждом отчёте. (Документ «Метрики» содержит определения всех метрик.) | |
startDate | string Дата начала сбора данных YouTube Analytics . Значение должно быть указано в формате YYYY-MM-DD . Примечание: в версии 1 API этот параметр назывался start-date . | |
Дополнительные параметры | ||
currency | string Валюта, которую API будет использовать для указания следующих метрик предполагаемого дохода: estimateRevenue , estimateAdRevenue , estimateRedPartnerRevenue , grossRevenue , cpm , playbackBasedCpm . Значения, возвращаемые API для этих метрик, представляют собой оценки, рассчитанные с использованием ежедневно меняющихся обменных курсов. Если ни одна из этих метрик не запрошена, параметр игнорируется. Значение параметра — трёхбуквенный код валюты ISO 4217 из списка валют ниже. API возвращает ошибку, если указана неподдерживаемая валюта. Значение по умолчанию — USD . | |
dimensions | string Список параметров YouTube Analytics, разделенных запятыми, например, video или ageGroup,gender . Список доступных отчетов и параметров, используемых в этих отчетах, а также определения всех параметров см. в документации по отчетам по каналам или владельцам контента. (Документ «Параметры» содержит определения всех параметров.) | |
filters | string Список фильтров, которые следует применять при получении данных YouTube Analytics . В документации по отчётам по каналам и отчётам владельцев контента указаны параметры, которые можно использовать для фильтрации каждого отчёта, а документ «Параметры» описывает эти параметры. Если в запросе используется несколько фильтров, соедините их точкой с запятой ( ; ), и возвращаемая таблица результатов будет соответствовать обоим фильтрам. Например, значение параметра filters video==dMH0bHeiRNg;country==IT ограничивает набор результатов данными по заданному видео в Италии.Указание нескольких значений для фильтра API поддерживает возможность указания нескольких значений для фильтров video , playlist и channel . Для этого укажите отдельный список идентификаторов видео, плейлистов или каналов, по которым следует фильтровать ответ API. Например, значение параметра filters video==pd1FJh59zxQ,Zhawgd0REhA;country==IT ограничивает набор результатов данными по заданным видео в Италии. Значение параметра может указывать до 500 идентификаторов.При указании нескольких значений для одного фильтра вы также можете добавить этот фильтр в список измерений, указанных в запросе. Это справедливо, даже если фильтр не указан в списке поддерживаемых измерений для конкретного отчёта. Если вы добавите фильтр в список измерений, API также будет использовать значения фильтра для группировки результатов. Например, предположим, что вы получаете отчёт об источниках трафика канала, который агрегирует статистику просмотров на основе способа, которым зрители получили доступ к видеоконтенту канала. Также предположим, что параметр filters вашего запроса определяет список из 10 видео, для которых необходимо вернуть данные.
| |
includeHistoricalChannelData | boolean Примечание: этот параметр применяется только к отчетам владельцев контента . Указывает, должен ли ответ API включать данные о времени просмотра и просмотрах каналов за период до того, как каналы были связаны с владельцем контента. Значение параметра по умолчанию — false , что означает, что ответ API включает только данные о времени просмотра и просмотрах за период, когда каналы были связаны с владельцем контента.Важно помнить, что разные каналы могли быть связаны с владельцем контента в разные даты. Если запрос API извлекает данные по нескольким каналам, а значение параметра равно false , то ответ API содержит данные на основе даты связывания для каждого соответствующего канала. Если значение параметра равно true , то ответ API содержит данные, соответствующие датам, указанным в запросе API. Примечание: в версии 1 API этот параметр назывался include-historical-channel-data . | |
maxResults | integer Максимальное количество строк, включаемых в ответ. Примечание: в версии 1 API этот параметр назывался max-results . | |
sort | string Список параметров или метрик, разделённых запятыми, которые определяют порядок сортировки данных YouTube Analytics. По умолчанию сортировка по возрастанию. Префикс - задаёт порядок сортировки по убыванию. | |
startIndex | integer Индекс первой извлекаемой сущности, начинающийся с 1. (Значение по умолчанию — 1 ) Используйте этот параметр в качестве механизма пагинации вместе с параметром max-results . Примечание: в версии 1 API этот параметр назывался start-index . | |
Стандартные параметры | ||
access_token | Токен OAuth 2.0 для текущего пользователя.
| |
alt | Этот параметр не поддерживается в версии API 2, которая поддерживает только ответы JSON. Формат данных для ответа API.
| |
callback | Функция обратного вызова.
| |
prettyPrint | Возвращает ответ с отступами и переносами строк.
| |
quotaUser | Этот параметр поддерживался в версии API 1, которая теперь устарела. В версии API 2 этот параметр не поддерживается. | |
userIp | Этот параметр поддерживался в версии API 1, которая теперь устарела. В версии API 2 этот параметр не поддерживается. |
Текст запроса
Не отправляйте тело запроса при вызове этого метода.
Ответ
Как указано в определении параметра alt
, API может возвращать ответы в форматах JSON или CSV. Информация о теле ответа для каждого типа представлена ниже:
{ "kind": "youtubeAnalytics#resultTable", "columnHeaders": [ { "name": string, "dataType": string, "columnType": string }, ... more headers ... ], "rows": [ [ {value}, {value}, ... ] ] }
Характеристики | |
---|---|
kind | string Это значение определяет тип данных, включенных в ответ API. Для метода query значение свойства kind будет youtubeAnalytics#resultTable . Однако, если API добавляет поддержку других методов, ответы API для этих методов могут содержать другие значения свойства kind . |
columnHeaders[] | list Это значение определяет информацию о данных, возвращаемых в полях rows . Каждый элемент в списке columnHeaders определяет поле, возвращаемое в значении rows , которое содержит список данных, разделенных запятыми.Список columnHeaders начинается с измерений, указанных в запросе API, за которыми следуют метрики, указанные в запросе API. Порядок измерений и метрик соответствует порядку в запросе API.Например, если запрос API содержит параметры dimensions=ageGroup,gender&metrics=viewerPercentage , ответ API возвращает столбцы в следующем порядке: ageGroup , gender , viewerPercentage . |
columnHeaders[]. name | string Имя измерения или метрики. |
columnHeaders[]. columnType | string Тип столбца ( DIMENSION или METRIC ). |
columnHeaders[]. dataType | string Тип данных в столбце ( STRING , INTEGER , FLOAT и т. д.). |
rows[] | list Список содержит все строки таблицы результатов. Каждый элемент списка представляет собой массив, содержащий данные, разделённые запятыми, соответствующие одной строке данных. Порядок полей данных, разделённых запятыми, будет соответствовать порядку столбцов, перечисленных в поле columnHeaders .Если для данного запроса данные недоступны, элемент rows будет исключен из ответа.Ответ на запрос с измерением day не будет содержать строк за самые последние дни. |
day, views, likes, ... "2012-01-01", 12.0, 3, ... "2012-01-02", 16.0, 2, ... "2012-01-03", 18.0, 8, ... ...
Примеры
Примечание: Приведённые ниже примеры кода могут не отображать все поддерживаемые языки программирования. Список поддерживаемых языков см. в документации клиентских библиотек .
JavaScript
В этом примере API YouTube Analytics вызывается для получения ежедневных просмотров и других показателей канала авторизованного пользователя за 2017 календарный год. В примере используется клиентская библиотека JavaScript API Google .Перед первым локальным запуском этого примера вам необходимо настроить учетные данные авторизации для вашего проекта:
- Создайте или выберите проект в консоли API Google .
- Включите API YouTube Analytics для вашего проекта.
- В верхней части страницы «Учётные данные» выберите вкладку «Экран согласия OAuth» . Выберите адрес электронной почты, введите название продукта, если оно ещё не задано, и нажмите кнопку «Сохранить».
- На странице «Учетные данные» нажмите кнопку «Создать учетные данные» и выберите «Идентификатор клиента Oauth» .
- Выберите тип приложения Веб-приложение.
- В поле «Авторизованные источники JavaScript» введите URL-адрес, с которого будет отображаться пример кода. Например, можно использовать
http://localhost:8000
илиhttp://yourserver.example.com
. Поле «Авторизованные URI перенаправления» можно оставить пустым. - Нажмите кнопку «Создать» , чтобы завершить создание учетных данных.
- Перед закрытием диалогового окна скопируйте идентификатор клиента, который вам нужно будет вставить в пример кода.
Затем сохраните пример в локальном файле. В примере найдите следующую строку и замените YOUR_CLIENT_ID на идентификатор клиента, полученный при настройке учётных данных для авторизации.
gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'});
Теперь вы готовы приступить к фактическому тестированию образца:
- Откройте локальный файл в веб-браузере и откройте консоль отладки в нём. Вы увидите страницу с двумя кнопками.
- Нажмите кнопку «Авторизовать и загрузить» , чтобы запустить процесс авторизации пользователя. Если вы авторизуете приложение для получения данных вашего канала, в консоли браузера должны появиться следующие строки:
Sign-in successful GAPI client loaded for API
- Если вместо строк, указанных выше, вы видите сообщение об ошибке, подтвердите, что вы загружаете скрипт с авторизованного URI перенаправления, который вы настроили для своего проекта, и что вы вставили свой идентификатор клиента в код, как описано выше.
- Нажмите кнопку «Выполнить» , чтобы вызвать API. Вы увидите объект
response
, выведенный на консоль браузера. В этом объекте свойствоresult
соответствует объекту, содержащему данные API.
<script src="https://apis.google.com/js/api.js"></script> <script> function authenticate() { return gapi.auth2.getAuthInstance() .signIn({scope: "https://www.googleapis.com/auth/yt-analytics.readonly"}) .then(function() { console.log("Sign-in successful"); }, function(err) { console.error("Error signing in", err); }); } function loadClient() { return gapi.client.load("https://youtubeanalytics.googleapis.com/$discovery/rest?version=v2") .then(function() { console.log("GAPI client loaded for API"); }, function(err) { console.error("Error loading GAPI client for API", err); }); } // Make sure the client is loaded and sign-in is complete before calling this method. function execute() { return gapi.client.youtubeAnalytics.reports.query({ "ids": "channel==MINE", "startDate": "2017-01-01", "endDate": "2017-12-31", "metrics": "views,estimatedMinutesWatched,averageViewDuration,averageViewPercentage,subscribersGained", "dimensions": "day", "sort": "day" }) .then(function(response) { // Handle the results here (response.result has the parsed body). console.log("Response", response); }, function(err) { console.error("Execute error", err); }); } gapi.load("client:auth2", function() { gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'}); }); </script> <button onclick="authenticate().then(loadClient)">authorize and load</button> <button onclick="execute()">execute</button>
Питон
В этом примере API YouTube Analytics вызывается для получения ежедневных просмотров и других показателей канала авторизованного пользователя за 2017 календарный год. В примере используется клиентская библиотека Python API Google .Перед первым локальным запуском этого примера вам необходимо настроить учетные данные авторизации для вашего проекта:
- Создайте или выберите проект в консоли API Google .
- Включите API YouTube Analytics для вашего проекта.
- В верхней части страницы «Учётные данные» выберите вкладку «Экран согласия OAuth» . Выберите адрес электронной почты, введите название продукта, если оно ещё не задано, и нажмите кнопку «Сохранить».
- На странице «Учетные данные» нажмите кнопку «Создать учетные данные» и выберите «Идентификатор клиента Oauth» .
- Выберите тип приложения Другое , введите имя «YouTube Analytics API Quickstart» и нажмите кнопку Создать.
- Нажмите кнопку «ОК» , чтобы закрыть появившееся диалоговое окно.
- Нажмите кнопку (Загрузить JSON) справа от идентификатора клиента.
- Переместите загруженный файл в ваш рабочий каталог.
Вам также необходимо установить клиентскую библиотеку Google API для Python и некоторые дополнительные библиотеки:
pip install --upgrade google-api-python-client pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2
Теперь вы готовы приступить к фактическому тестированию образца:
- Скопируйте приведенный ниже пример кода в свой рабочий каталог.
- В примере обновите значение переменной
CLIENT_SECRETS_FILE
так, чтобы оно соответствовало расположению файла, который вы загрузили после настройки учетных данных авторизации. - Запустите пример кода в окне терминала:
python yt_analytics_v2.py
- Пройдите процедуру авторизации. Процесс авторизации может автоматически загрузиться в вашем браузере, или вам может потребоваться скопировать URL-адрес авторизации в окно браузера. В конце процесса авторизации, при необходимости, вставьте код авторизации, отображаемый в браузере, в окно терминала и нажмите [return].
- Запрос API выполняется, и ответ JSON выводится в окно терминала.
# -*- coding: utf-8 -*- import os import google.oauth2.credentials import google_auth_oauthlib.flow from googleapiclient.discovery import build from googleapiclient.errors import HttpError from google_auth_oauthlib.flow import InstalledAppFlow SCOPES = ['https://www.googleapis.com/auth/yt-analytics.readonly'] API_SERVICE_NAME = 'youtubeAnalytics' API_VERSION = 'v2' CLIENT_SECRETS_FILE = 'YOUR_CLIENT_SECRET_FILE.json' def get_service(): flow = InstalledAppFlow.from_client_secrets_file(CLIENT_SECRETS_FILE, SCOPES) credentials = flow.run_console() return build(API_SERVICE_NAME, API_VERSION, credentials = credentials) def execute_api_request(client_library_function, **kwargs): response = client_library_function( **kwargs ).execute() print(response) if __name__ == '__main__': # Disable OAuthlib's HTTPs verification when running locally. # *DO NOT* leave this option enabled when running in production. os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1' youtubeAnalytics = get_service() execute_api_request( youtubeAnalytics.reports().query, ids='channel==MINE', startDate='2017-01-01', endDate='2017-12-31', metrics='estimatedMinutesWatched,views,likes,subscribersGained' dimensions='day', sort='day' )
Попробуйте!
Используйте APIs Explorer для вызова этого API и просмотра запроса и ответа API.