Google TV Video Discovery REST API позволяет партнерам отправлять неперсонализированные рекомендации на устройства Google TV и Android TV со своих бэкенд-серверов. Отправка кандидатов из серверной части позволяет обновлять каталог партнера и рекомендации по текущим программам на этих устройствах без необходимости открывать приложение партнера.
Партнеры отправляют кандидатов в фиды рекомендаций. Google создает фид для партнера и настраивает страны или регионы и языки телевизоров, для которых он будет показываться. Фид может содержать фильмы, сериалы и телепередачи.
Если вы хотите публиковать персональные рекомендации с устройства пользователя, прочитайте статью Как интегрировать рекомендации на устройстве с помощью Engage SDK.
Требования
Прежде чем интегрировать REST API, убедитесь, что у вас есть:
- Проект Google Cloud, из которого будут отправляться запросы к API.
- Аккаунт Google Workspace, связанный с вашей организацией.
- Идентификатор партнера и идентификаторы фидов рекомендаций, предоставленные представителем Google TV во время регистрации. Подробнее о том, как используются эти идентификаторы, рассказывается в статье Фиды рекомендаций.
Получить доступ
Доступ к Google TV Video Discovery REST API предоставляется только зарегистрированным медиапартнерам Google TV. Каждый вызывающий абонент проходит аутентификацию с помощью сервисного аккаунта Google Cloud, который сопоставлен на сервере ровно с одним идентификатором партнера.
Чтобы запросить и настроить доступ к API, выполните следующие действия:
- Создайте аккаунт Google Workspace. Следуйте инструкциям на странице службы поддержки Google Workspace, чтобы настроить аккаунт для своей организации.
- Найдите идентификатор клиента Google Workspace. Найдите свой идентификатор клиента (например,
C0123abcd), следуя инструкциям в статье Как найти идентификатор клиента. - Создайте проект Google Cloud и сервисный аккаунт. В консоли Google Cloud в организации Google Workspace создайте проект Google Cloud и сервисный аккаунт для бэкенд-сервера.
- Запросите регистрацию партнера. Предоставьте идентификатор клиента Google Workspace, идентификатор проекта Google Cloud и адрес электронной почты сервисного аккаунта (или уникальный цифровой идентификатор) представителю партнера Google TV, а также укажите страны или регионы и языки телевизоров, для которых вы хотите отправлять кандидатов. Представитель партнера Google TV уведомит вас, когда сопоставит организацию Google Workspace, проект и сервисный аккаунт с вашим идентификатором партнера, и предоставит идентификаторы фидов рекомендаций, созданных для вашего партнера.
- Включите API и создайте учетные данные. После того как представитель подтвердит, что доступ предоставлен, включите Google TV Video Discovery API (
tvvideodiscovery.googleapis.com) в проекте Google Cloud и сгенерируйте учетные данные OAuth 2.0 для сервисного аккаунта. Выполните аутентификацию запросов. Запросите токены доступа OAuth 2.0, используя следующую область действия OAuth, и передавайте токен в HTTP-заголовке
Authorization: Bearerпри каждом вызове:https://www.googleapis.com/auth/tvvideodiscovery
Ограничение частоты запросов
Для запросов к replaceCandidates действуют следующие ограничения на частоту запросов в рамках проекта и на полезную нагрузку в рамках запроса:
| Ограничение | Значение |
|---|---|
| Количество запросов в минуту на облачный проект Google Cloud | 5 |
| Количество запросов в день на проект Google Cloud | 100 |
RecommendationCandidate элементов на запрос |
1–25 |
Запросы к тестовому фиду товаров учитываются в той же квоте, что и запросы к соответствующему рабочему фиду товаров.
Фиды рекомендаций
API организует кандидатов в фиды рекомендаций. Фид идентифицируется по названию ресурса в следующем формате:
partners/{partner}/recommendationsFeeds/{recommendationsFeed}
Партнеры
{partner} – идентификатор партнера, который Google назначает вам при регистрации. Сервисный аккаунт, который вы используете для аутентификации, сопоставляется только с одним идентификатором партнера.
Запросы, в которых указан любой другой партнер, возвращают ошибку 403 PERMISSION_DENIED.
Идентификаторы фидов
{recommendationsFeed} – это идентификатор фида, который Google создает для вас во время регистрации. Создавать фиды с помощью API нельзя.
Каждый фид предназначен для определенной аудитории, которую Google настраивает при создании фида:
- Страны или регионы, в которых показываются кандидаты из фида.
- Языки телевизоров. Языки, которые целевые пользователи установили на своих телевизорах. Это не язык текста, который вы отправляете. Если вы хотите добавить текст на нескольких языках, ознакомьтесь с этой статьей
LocalizedString.
Google решает, где на устройствах Google TV и Android TV будут показываться кандидаты из фида. Кандидаты отправляются во все фиды одинаково.
Тестовые фиды
У каждого фида есть соответствующий тестовый фид с названием {recommendationsFeed}-staging. Тестовый фид доступен только тестовым аккаунтам из белого списка. Используйте его, чтобы проверить интеграцию, прежде чем отправлять вакансии в рабочий фид.
Для тестовых фидов используются те же конечные точки, учетные данные, проверка запросов и квоты, что и для рабочих. Различается только аудитория.
Замена
Фид – это единица замены. Каждый вызов replaceCandidates заменяет всех кандидатов, ранее сохраненных для этого фида, и не затрагивает другие фиды.
Замена кандидатов на рекомендации
Используйте метод partners.recommendationsFeeds.replaceCandidates, чтобы отправить полный список кандидатов на рекомендации для одного фида.
HTTP-запрос
POST https://tvvideodiscovery.googleapis.com/v1/{name=partners/*/recommendationsFeeds/*}:replaceCandidates
Путь URL содержит название ресурса фида, кандидаты которого заменяются. Тело запроса содержит все поля, которые не являются частью пути URL.
Параметры пути
| Параметр | Описание |
|---|---|
name |
Обязательно. Название ресурса фида в формате partners/{partner}/recommendationsFeeds/{recommendationsFeed}. {partner} – идентификатор партнера, с которым сопоставлен ваш сервисный аккаунт. {recommendationsFeed} должен быть идентификатором фида, который Google создал для этого партнера, или идентификатором фида с суффиксом -staging. |
ReplaceCandidatesRequest
Тело запроса JSON имеет следующую структуру:
| Поле | Тип | Обязательное поле | Описание |
|---|---|---|---|
recommendation_candidates |
array of RecommendationCandidate |
Да | Список, содержащий от 1 до 25 объектов RecommendationCandidate. Эти кандидаты заменяют текущих кандидатов фида. |
Схемы-кандидаты
Каждый элемент в recommendation_candidates – это объект RecommendationCandidate, который содержит одну полезную нагрузку типа candidate, необязательные причины рекомендации и необязательные периоды доступности.
RecommendationCandidate
Объект RecommendationCandidate содержит ровно одно поле полезной нагрузки типа медиа, необязательные причины рекомендаций и необязательные интервалы доступности.
Объединенное поле candidate_type
Поле candidate_type обязательно. Задайте одно из следующих полей. Поля являются взаимоисключающими, и кандидат, который не устанавливает ни одного или более одного, отклоняется. В JSON нет ключа candidate_type. Задайте выбранное поле непосредственно в объекте RecommendationCandidate.
| Поле | Тип | Описание |
|---|---|---|
movie_candidate |
MovieCandidate |
Фильм по запросу (см. MovieCandidate). |
tv_show_candidate |
TvShowCandidate |
Телешоу на уровне шоу (см. TvShowCandidate). |
live_tv_program_candidate |
LiveTvProgramCandidate |
Запланированная телетрансляция или трансляция через интернет (см. LiveTvProgramCandidate). |
Контекст и доступность
Оба поля необязательны.
| Поле | Тип | Обязательное поле | Описание |
|---|---|---|---|
recommendation_contexts |
array of RecommendationContext |
Нет | Причина, по которой рекомендуется кандидат, и срок действия каждой причины (см. RecommendationContext). |
availability_intervals |
array of Interval |
Нет | Временные окна, в течение которых может быть показан кандидат (см. Interval). Каждое окно начинается в start_time (включительно) и заканчивается в end_time (не включительно). Если значение не задано, кандидат может быть выбран в течение всего времени хранения. Кандидат, у которого все окна в прошлом, никогда не показывается. |
MovieCandidate
Объект MovieCandidate представляет фильм по запросу:
| Поле | Тип | Обязательное поле | Описание |
|---|---|---|---|
title |
LocalizedString |
Да | Название фильма (см. LocalizedString). Каждое значение содержит от 1 до 100 кодовых точек Unicode и показывается в том виде, в котором оно было отправлено. |
description |
LocalizedString |
Да | Краткое описание фильма (см. LocalizedString). Каждое значение содержит от 1 до 400 кодовых точек Unicode. |
localized_media_images |
array of LocalizedMediaImage |
Да | Изображения обложек с соотношением сторон 16:9, по одному на каждый язык (см. LocalizedMediaImage). Должно быть хотя бы одно изображение. Предоставьте файл с максимально возможным разрешением. Рекомендуется 1920 x 1080 пикселей. |
localized_provider_playback_uris |
array of LocalizedProviderPlaybackUri |
Да | Ссылки на контент для каждой платформы и языка (см. LocalizedProviderPlaybackUri). Хотя бы в одной записи должно быть указано PLATFORM_ANDROID_TV. |
release_date |
Date |
Да | Дата выпуска фильма (см. Date). |
external_entity_ids |
array of ExternalEntityId |
Нет | Внешние идентификаторы каталога для сопоставления объектов (см. ExternalEntityId). Не более одной записи на тип идентификатора. |
duration |
string (Duration) |
Нет | Продолжительность фильма (см. Duration). Например, "7200s" для двух часов. |
content_ratings |
array of ContentRating |
Нет | Официальные возрастные ограничения (см. ContentRating). |
TvShowCandidate
Объект TvShowCandidate представляет телешоу на уровне шоу. На устройствах Google TV и устройствах Android TV показывается карточка сериала. Ссылка на контент определяет, где начнется воспроизведение: на странице сериала или на странице определенной серии.
| Поле | Тип | Обязательное поле | Описание |
|---|---|---|---|
title |
LocalizedString |
Да | Название телешоу (см. LocalizedString). Каждое значение содержит от 1 до 100 кодовых точек Unicode и показывается в том виде, в котором было отправлено. |
description |
LocalizedString |
Да | Краткое описание телешоу (см. LocalizedString). Каждое значение должно содержать от 1 до 400 кодовых точек Unicode. |
localized_media_images |
array of LocalizedMediaImage |
Да | Изображения обложек с соотношением сторон 16:9, по одному на каждый язык (см. LocalizedMediaImage). Должно быть хотя бы одно изображение. Предоставьте файл с максимально возможным разрешением. Рекомендуется 1920 x 1080 пикселей. |
localized_provider_playback_uris |
array of LocalizedProviderPlaybackUri |
Да | Ссылки на контент для каждой платформы и языка (см. LocalizedProviderPlaybackUri). Хотя бы в одной записи должно быть указано PLATFORM_ANDROID_TV. uri может указывать на страницу подкаста или на выпуск. |
first_episode_air_date |
Date |
Да | Дата выхода первой серии (см. Date). |
external_entity_ids |
array of ExternalEntityId |
Нет | Внешние идентификаторы каталога для сопоставления объектов (см. ExternalEntityId). Не более одной записи на тип идентификатора. |
season_count |
integer (int32) |
Нет | Количество сезонов, доступных в вашем сервисе. |
content_ratings |
array of ContentRating |
Нет | Официальные возрастные ограничения (см. ContentRating). |
LiveTvProgramCandidate
Объект LiveTvProgramCandidate представляет собой запланированную телетрансляцию или трансляцию мероприятия. Окно трансляции является частью кандидата и не зависит от параметров availability_intervals родительского кандидата, которые определяют, когда может быть показана карточка.
| Поле | Тип | Обязательное поле | Описание |
|---|---|---|---|
title |
LocalizedString |
Да | Название программы онлайн-телевидения (см. LocalizedString). Каждое значение содержит от 1 до 100 кодовых точек Unicode и показывается в том виде, в котором было отправлено. |
description |
LocalizedString |
Да | Краткое описание телепрограммы (см. LocalizedString). Каждое значение должно содержать от 1 до 400 кодовых точек Unicode. |
localized_media_images |
array of LocalizedMediaImage |
Да | Изображения обложек с соотношением сторон 16:9, по одному на каждый язык (см. LocalizedMediaImage). Должно быть хотя бы одно изображение. Предоставьте файл с максимально возможным разрешением. Рекомендуется 1920 x 1080 пикселей. |
localized_provider_playback_uris |
array of LocalizedProviderPlaybackUri |
Да | Ссылки на контент для каждой платформы и языка (см. LocalizedProviderPlaybackUri). Хотя бы в одной записи должно быть указано PLATFORM_ANDROID_TV. |
broadcast_interval |
Interval |
Да | Время начала и окончания трансляции программы (см. Interval). Необходимо указать оба значения (start_time и end_time). |
external_entity_ids |
array of ExternalEntityId |
Нет | Внешние идентификаторы каталога для сопоставления объектов (см. ExternalEntityId). Не более одной записи на тип идентификатора. |
content_ratings |
array of ContentRating |
Нет | Официальные возрастные ограничения (см. ContentRating). |
Поддерживаемые схемы
Полезные нагрузки кандидатов ссылаются на следующие общие объекты: локализованный текст, ссылки на контент, изображения, внешние идентификаторы, причины рекомендаций, интервалы показа, возрастные ограничения и известные типы даты и времени.
LocalizedString
Объект LocalizedString содержит один и тот же текст на одном или нескольких языках.
Каждое значение помечается тегом языка, чтобы устройства Google TV и Android TV могли показывать текст, соответствующий языку устройства пользователя:
| Поле | Тип | Обязательное поле | Описание |
|---|---|---|---|
values |
array of LocalizedText |
Да | Текст на каждом из указанных языков (см. LocalizedText). Должно быть указано хотя бы одно значение. |
LocalizedText
Объект LocalizedText – это текст на одном языке:
| Поле | Тип | Обязательное поле | Описание |
|---|---|---|---|
text |
string |
Да | Текст на языке, указанном в language_code. |
language_code |
string |
Да | Код языка по стандарту BCP-47 для text, например "en-US" или "sr-Latn". |
LocalizedMediaImage
Объект LocalizedMediaImage связывает изображение с языком текста на нем:
| Поле | Тип | Обязательное поле | Описание |
|---|---|---|---|
language_code |
string |
Да | Код языка текста на изображении по стандарту BCP-47, например "en-US" или "sr-Latn". |
image |
MediaImage |
Да | Изображение с соотношением сторон 16:9 (см. MediaImage). Предоставьте изображение с максимально возможным разрешением. Рекомендуется 1920 x 1080 пикселей. |
LocalizedProviderPlaybackUri
Объект LocalizedProviderPlaybackUri связывает ссылку на контент с языком контента, который она открывает, и приложением, которое его открывает:
| Поле | Тип | Обязательное поле | Описание |
|---|---|---|---|
playback_uri |
PlaybackUri |
Да | Ссылка на контент и платформы, к которым она относится (см. PlaybackUri). |
language_code |
string |
Да | Код языка по стандарту BCP-47 для контента, который открывается по ссылке, например "en-US" или "sr-Latn". |
package_name |
string |
Да | Название пакета приложения Android, используемое для открытия ссылки на контент (например, "com.example.tvapp"). |
PlaybackUri
Объект PlaybackUri определяет ссылку на контент и целевые платформы:
| Поле | Тип | Обязательное поле | Описание |
|---|---|---|---|
uri |
string |
Да | URI ссылки на контент, которая запускает воспроизведение кандидата в вашем приложении. |
platforms |
array of string (enum) |
Да | Платформы, для которых можно использовать ссылку на контент. Допустимые значения: PLATFORM_UNSPECIFIED, PLATFORM_ANDROID_TV, PLATFORM_ANDROID, PLATFORM_IOS. Добавьте PLATFORM_ANDROID_TV для устройств Google TV и Android TV. |
MediaImage
Объект MediaImage указывает URL изображения, его размеры в пикселях и текст для специальных возможностей:
| Поле | Тип | Обязательное поле | Описание |
|---|---|---|---|
url |
string |
Да | Общедоступный URL изображения по протоколу HTTPS. |
width |
integer |
Да | Ширина изображения в пикселях без изменений (максимальная). |
height |
integer |
Да | Максимальная высота изображения в пикселях. |
accessibility_text |
string |
Да | Альтернативный текст, описывающий изображение. |
ExternalEntityId
Объект ExternalEntityId сопоставляет кандидата с идентификатором во внешнем каталоге. Задайте только одно из следующих полей для каждой записи и добавьте не более одной записи для каждого типа идентификатора в список external_entity_ids кандидата:
| Поле | Тип | Обязательное поле | Описание |
|---|---|---|---|
tms_root_id |
string |
Любое из перечисленных: | Корневой идентификатор Gracenote TMS. Идентифицирует название фильма, сериала или серии. |
tms_id |
string |
Любое из перечисленных: | Идентификатор варианта Gracenote TMS. Определяет издание или список трансляций. |
data_feed_element_id |
string |
Любое из перечисленных: | Идентификатор объекта из фида данных Media Actions. Это значение не связано с сегментом {recommendationsFeed} названия ресурса. |
RecommendationContext
Объект RecommendationContext объясняет, почему рекомендуется кандидат и как долго действует это объяснение:
| Поле | Тип | Обязательное поле | Описание |
|---|---|---|---|
recommendation_reason |
RecommendationReason |
Нет | Причина рекомендации (см. RecommendationReason). |
validity_interval |
Interval |
Нет | Временное окно, в течение которого применяется этот контекст (см. Interval). Например, кандидат считается новым только в течение ограниченного количества дней. Если значение не задано, контекст применяется до тех пор, пока хранится кандидат. |
RecommendationReason
Объект RecommendationReason содержит одну причину. Задайте только одно из следующих полей:
| Поле | Тип | Обязательное поле | Описание |
|---|---|---|---|
top_on_partner |
object |
Любое из перечисленных: | Кандидат – это один из лучших элементов в вашем сервисе. Содержит одно поле rank с положительным целым числом (например, {"rank": 1} для "Топ-1 у партнера"). |
popular_on_partner |
object |
Любое из перечисленных: | Кандидат популярен в вашем сервисе. Передайте пустой объект ({}). |
new_on_partner |
object |
Любое из перечисленных: | Кандидат – новый пользователь вашего сервиса. Передайте пустой объект ({}). |
generic |
object |
Любое из перечисленных: | Прочие причины. Содержит одно поле LocalizedString generic_reason (см. LocalizedString). Каждое значение содержит от 1 до 100 кодовых точек Unicode. |
ContentRating
Объект ContentRating представляет официальное возрастное ограничение, присвоенное рейтинговым агентством.
| Поле | Тип | Обязательное поле | Описание |
|---|---|---|---|
rating_system |
string |
Да | Агентство или система, присвоившая возрастной рейтинг, например "MPAA", "BBFC" или "CBFC". |
rating_value |
string |
Да | Оценка, определенная rating_system, например "PG-13" или "U/A 13+". |
Timestamp
Timestamp кодируется в JSON как строка RFC 3339 в формате UTC с суффиксом Z, например "2026-10-01T18:00:00Z". Допускаются дробные значения секунд, например "2026-10-01T18:00:00.500Z".
Duration
Значение Duration кодируется в JSON как строка, содержащая количество секунд, за которым следует суффикс s, например "7200s" для 2 часов. Допускаются доли секунды, например "5400.5s".
Date
Date – это календарная дата без часового пояса. Он закодирован в JSON как объект со следующими полями:
| Поле | Тип | Обязательное поле | Описание |
|---|---|---|---|
year |
integer |
Да | Год, например 2025. |
month |
integer |
Нет | Месяц года, от 1 до 12. Укажите значение 0 или опустите его, если месяц неизвестен. |
day |
integer |
Нет | День месяца от 1 до 31, действительный для указанного года и месяца. Если день неизвестен, укажите 0 или не указывайте ничего. Требуется month. |
Например, {"year": 2025, "month": 1, "day": 17} означает 17 января 2025 г., {"year": 2025, "month": 1} – январь 2025 г. с неизвестным днем, а {"year": 2025} – дату в 2025 г. с неизвестными месяцем и днем.
Interval
Interval – это полуоткрытое временное окно, которое начинается в start_time (включительно) и заканчивается в end_time (не включительно). Время T находится внутри интервала, когда start_time <= T и T < end_time.
| Поле | Тип | Обязательное поле | Описание |
|---|---|---|---|
start_time |
string (Timestamp) |
Да | Время начала интервала (см. Timestamp), например "2026-10-01T18:00:00Z". |
end_time |
string (Timestamp) |
Да | Время окончания интервала не включается (см. Timestamp), например "2026-10-01T21:00:00Z". Должно быть позже start_time. |
Пример запроса
В следующем примере кандидаты фида in-en-cricket партнера example-partner заменяются тремя кандидатами (фильмом, сериалом и телепрограммой). В фильме есть текст на двух языках:
curl -X POST \
"https://tvvideodiscovery.googleapis.com/v1/partners/example-partner/recommendationsFeeds/in-en-cricket:replaceCandidates" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{
"recommendation_candidates": [
{
"movie_candidate": {
"title": {
"values": [
{
"text": "Example Action Movie",
"language_code": "en-US"
},
{
"text": "Película de acción de ejemplo",
"language_code": "es-419"
}
]
},
"description": {
"values": [
{
"text": "An example action movie synopsis.",
"language_code": "en-US"
},
{
"text": "Sinopsis de una película de acción de ejemplo.",
"language_code": "es-419"
}
]
},
"localized_media_images": [
{
"language_code": "en-US",
"image": {
"url": "https://www.example.com/images/movie-1001-16x9-en.jpg",
"width": 1920,
"height": 1080,
"accessibility_text": "Artwork for Example Action Movie"
}
},
{
"language_code": "es-419",
"image": {
"url": "https://www.example.com/images/movie-1001-16x9-es.jpg",
"width": 1920,
"height": 1080,
"accessibility_text": "Imagen de Película de acción de ejemplo"
}
}
],
"localized_provider_playback_uris": [
{
"playback_uri": {
"uri": "https://www.example.com/watch/movie-1001?lang=en",
"platforms": ["PLATFORM_ANDROID_TV", "PLATFORM_ANDROID"]
},
"language_code": "en-US",
"package_name": "com.example.tvapp"
},
{
"playback_uri": {
"uri": "https://www.example.com/watch/movie-1001?lang=es",
"platforms": ["PLATFORM_ANDROID_TV", "PLATFORM_ANDROID"]
},
"language_code": "es-419",
"package_name": "com.example.tvapp"
}
],
"release_date": {
"year": 2025,
"month": 11,
"day": 14
},
"external_entity_ids": [
{
"tms_root_id": "MV001234560000"
}
],
"duration": "7200s",
"content_ratings": [
{
"rating_system": "MPAA",
"rating_value": "PG-13"
}
]
},
"recommendation_contexts": [
{
"recommendation_reason": {
"top_on_partner": {
"rank": 1
}
}
}
],
"availability_intervals": [
{
"start_time": "2026-11-01T00:00:00Z",
"end_time": "2026-12-01T00:00:00Z"
}
]
},
{
"tv_show_candidate": {
"title": {
"values": [
{
"text": "Example Drama Series",
"language_code": "en-US"
}
]
},
"description": {
"values": [
{
"text": "An example drama series synopsis.",
"language_code": "en-US"
}
]
},
"localized_media_images": [
{
"language_code": "en-US",
"image": {
"url": "https://www.example.com/images/show-2002-16x9.jpg",
"width": 1920,
"height": 1080,
"accessibility_text": "Artwork for Example Drama Series"
}
}
],
"localized_provider_playback_uris": [
{
"playback_uri": {
"uri": "https://www.example.com/watch/show-2002",
"platforms": ["PLATFORM_ANDROID_TV"]
},
"language_code": "en-US",
"package_name": "com.example.tvapp"
}
],
"first_episode_air_date": {
"year": 2024,
"month": 3,
"day": 8
},
"external_entity_ids": [
{
"data_feed_element_id": "show-2002"
}
],
"season_count": 3,
"content_ratings": [
{
"rating_system": "TV_PG",
"rating_value": "TV-14"
}
]
},
"recommendation_contexts": [
{
"recommendation_reason": {
"new_on_partner": {}
},
"validity_interval": {
"start_time": "2026-11-01T00:00:00Z",
"end_time": "2026-11-15T00:00:00Z"
}
}
],
"availability_intervals": [
{
"start_time": "2026-11-01T00:00:00Z",
"end_time": "2026-12-01T00:00:00Z"
}
]
},
{
"live_tv_program_candidate": {
"title": {
"values": [
{
"text": "Championship Live Broadcast",
"language_code": "en-US"
}
]
},
"description": {
"values": [
{
"text": "Live coverage of the championship match.",
"language_code": "en-US"
}
]
},
"localized_media_images": [
{
"language_code": "en-US",
"image": {
"url": "https://www.example.com/images/live-prog-500-16x9.jpg",
"width": 1920,
"height": 1080,
"accessibility_text": "Artwork for Championship Live Broadcast"
}
}
],
"localized_provider_playback_uris": [
{
"playback_uri": {
"uri": "https://www.example.com/live/sports-1",
"platforms": ["PLATFORM_ANDROID_TV"]
},
"language_code": "en-US",
"package_name": "com.example.tvapp"
}
],
"broadcast_interval": {
"start_time": "2026-11-15T18:00:00Z",
"end_time": "2026-11-15T21:00:00Z"
},
"external_entity_ids": [
{
"tms_id": "EP012345670001"
}
],
"content_ratings": [
{
"rating_system": "TV_PG",
"rating_value": "TV-PG"
}
]
},
"recommendation_contexts": [
{
"recommendation_reason": {
"generic": {
"generic_reason": {
"values": [
{
"text": "Live this weekend",
"language_code": "en-US"
}
]
}
}
}
}
],
"availability_intervals": [
{
"start_time": "2026-11-14T18:00:00Z",
"end_time": "2026-11-15T21:00:00Z"
}
]
}
]
}'
Ответы и замена
В этом разделе описывается HTTP-ответ, возвращаемый методом replaceCandidates, и то, как каждый вызов обновляет сохраненных кандидатов.
ReplaceCandidatesResponse
Если запрос выполнен успешно, API возвращает HTTP 200 OK с телом ReplaceCandidatesResponse:
| Поле | Тип | Описание |
|---|---|---|
replaced_candidates_count |
integer (int32) |
Количество замененных кандидатов. |
Для примера запроса выше ответ будет следующим:
{
"replaced_candidates_count": 3
}
Замена
Чтобы правильно настроить интеграцию, важно понимать, как replaceCandidates обновляет сохраненные данные кандидатов.
- Полная замена фида. Каждый вызов полностью заменяет ранее сохраненный список кандидатов для фида, указанного в пути URL. Всегда отправляйте полный набор активных кандидатов для этого фида.
- Другие фиды останутся без изменений. Фиды, в которые вы не отправляете кандидатов, остаются неизменными. Например, замена кандидатов в одном фиде не влияет на сохраненных кандидатов в других фидах, а замена кандидатов в
{recommendationsFeed}-stagingне влияет на{recommendationsFeed}. - Один вызов на фид. Чтобы обновить несколько фидов, выполните по одному вызову для каждого из них. Вызовы независимы: если один из них не удастся, в других фидах новые кандидаты сохранятся, и вам нужно будет повторить только неудавшийся вызов.
- Повторно отправляйте активные фиды не реже чем раз в 30 дней. Даже если каталог фида не изменился, отправляйте каждый активный фид не реже одного раза в 30 дней (или по регулярному ежедневному или еженедельному расписанию со случайным джиттером), чтобы ваши кандидаты оставались активными и не истекали. Если вы зададите значение
availability_intervalsend_time, которое наступит нескоро, это не заменит периодическую повторную отправку. - Атомарное выполнение. API применяет запрос атомарно. Если хотя бы один кандидат не пройдет проверку, API отклонит весь запрос, а в фиде останутся предыдущие кандидаты.