Как интегрировать рекомендации с помощью REST API

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, выполните следующие действия:

  1. Создайте аккаунт Google Workspace. Следуйте инструкциям на странице службы поддержки Google Workspace, чтобы настроить аккаунт для своей организации.
  2. Найдите идентификатор клиента Google Workspace. Найдите свой идентификатор клиента (например, C0123abcd), следуя инструкциям в статье Как найти идентификатор клиента.
  3. Создайте проект Google Cloud и сервисный аккаунт. В консоли Google Cloud в организации Google Workspace создайте проект Google Cloud и сервисный аккаунт для бэкенд-сервера.
  4. Запросите регистрацию партнера. Предоставьте идентификатор клиента Google Workspace, идентификатор проекта Google Cloud и адрес электронной почты сервисного аккаунта (или уникальный цифровой идентификатор) представителю партнера Google TV, а также укажите страны или регионы и языки телевизоров, для которых вы хотите отправлять кандидатов. Представитель партнера Google TV уведомит вас, когда сопоставит организацию Google Workspace, проект и сервисный аккаунт с вашим идентификатором партнера, и предоставит идентификаторы фидов рекомендаций, созданных для вашего партнера.
  5. Включите API и создайте учетные данные. После того как представитель подтвердит, что доступ предоставлен, включите Google TV Video Discovery API (tvvideodiscovery.googleapis.com) в проекте Google Cloud и сгенерируйте учетные данные OAuth 2.0 для сервисного аккаунта.
  6. Выполните аутентификацию запросов. Запросите токены доступа 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_intervals end_time, которое наступит нескоро, это не заменит периодическую повторную отправку.
  • Атомарное выполнение. API применяет запрос атомарно. Если хотя бы один кандидат не пройдет проверку, API отклонит весь запрос, а в фиде останутся предыдущие кандидаты.