Integrar recomendações usando a API REST

A API REST de descoberta de vídeos do Google TV permite que os parceiros enviem candidatos a recomendações não personalizadas para dispositivos Google TV e dispositivos Android TV usando os servidores de back-end deles. O envio de candidatos do back-end mantém as recomendações de catálogo e programação ao vivo de um parceiro atualizadas nesses dispositivos sem que os usuários precisem abrir o app do parceiro.

Os parceiros enviam candidatos para feeds de recomendações. O Google cria cada feed para o parceiro e configura os países ou regiões e os idiomas do dispositivo de TV em que o feed é exibido. Um feed pode conter filmes, programas de TV e programas de TV ao vivo.

Se você quiser publicar recomendações personalizadas do dispositivo do usuário, consulte Integrar recomendações no dispositivo usando o SDK Engage.

Pré-requisitos

Antes de fazer a integração com a API REST, verifique se você tem o seguinte:

  • Um projeto na nuvem do Google Cloud para fazer solicitações de API.
  • Uma conta do Google Workspace associada à sua organização.
  • Seu ID de parceiro e os IDs do feed de recomendações, fornecidos pelo representante de parceiros do Google TV durante a integração. Consulte Feeds de recomendações para saber como esses IDs são usados.

Quero acessar

O acesso à API REST de descoberta de vídeos do Google TV é restrito a parceiros de mídia registrados do Google TV. Cada autor da chamada é autenticado usando uma conta de serviço do Google Cloud que é mapeada no servidor para exatamente um ID de parceiro.

Para solicitar e configurar o acesso à API, siga estas etapas:

  1. Crie uma conta do Google Workspace. Siga as instruções na página de suporte do Google Workspace para configurar uma conta para sua organização.
  2. Localize seu ID de cliente do Google Workspace. Encontre seu ID de cliente (por exemplo, C0123abcd) seguindo as etapas em Encontrar seu ID de cliente.
  3. Crie um projeto na nuvem e uma conta de serviço do Google Cloud. No console do Google Cloud, na organização do Google Workspace, crie um projeto do Google Cloud e uma conta de serviço para o servidor de back-end.
  4. Solicite a integração do parceiro. Informe seu ID de cliente do Google Workspace, ID do projeto do Google Cloud e endereço de e-mail da conta de serviço (ou ID numérico exclusivo) ao representante do parceiro do Google TV, junto com os países ou regiões e os idiomas do dispositivo de TV para os quais você quer enviar candidatos. O representante do parceiro do Google TV vai notificar você depois de mapear a organização, o projeto e a conta de serviço do Google Workspace para seu ID de parceiro e vai fornecer os IDs de feed de recomendações criados para seu parceiro.
  5. Ative a API e gere credenciais. Depois que o representante confirmar que o acesso foi concedido, ative a API Google TV Video Discovery (tvvideodiscovery.googleapis.com) no seu projeto na nuvem do Google Cloud e gere credenciais do OAuth 2.0 para sua conta de serviço.
  6. Autentique suas solicitações. Solicite tokens de acesso do OAuth 2.0 usando o seguinte escopo do OAuth e transmita o token no cabeçalho HTTP Authorization: Bearer em cada chamada:

    https://www.googleapis.com/auth/tvvideodiscovery
    

Limites de taxas

As solicitações para replaceCandidates estão sujeitas aos seguintes limites de taxa por projeto e limites de payload por solicitação:

Limite Valor
Solicitações por minuto por projeto do Google Cloud 5
Solicitações por dia por projeto do Google Cloud 100
RecommendationCandidate itens por solicitação 1 a 25

As solicitações para um feed de teste são contabilizadas na mesma cota que as solicitações para o feed de produção correspondente.

Feeds de recomendações

A API organiza os candidatos a recomendação em feeds de recomendações. Um feed é identificado por um nome de recurso com o seguinte formato:

partners/{partner}/recommendationsFeeds/{recommendationsFeed}

Parceiros

{partner} é o ID do parceiro que o Google atribui a você durante a integração. A conta de serviço usada para autenticação é mapeada para exatamente um ID de parceiro. As solicitações que nomeiam qualquer outro parceiro falham com 403 PERMISSION_DENIED.

IDs de feed

{recommendationsFeed} é um ID de feed que o Google cria para você durante a integração. Não é possível criar feeds com a API.

Cada feed segmenta um público-alvo que o Google configura ao criar o feed:

  • Países ou regiões: onde os candidatos do feed são mostrados.
  • Idiomas do dispositivo de TV: os idiomas que os usuários segmentados definiram no dispositivo de TV. Esse não é o idioma do texto que você envia. Para fornecer texto em mais de um idioma, consulte LocalizedString.

O Google decide onde os candidatos de um feed aparecem nos dispositivos Google TV e Android TV. Você envia candidatos para todos os feeds da mesma forma.

Feeds de preparo

Cada feed tem um feed de preparo correspondente chamado {recommendationsFeed}-staging. Um feed de preparo é veiculado apenas para contas de teste em uma lista de permissões. Use-o para validar sua integração antes de enviar candidatos ao feed de produção.

Os feeds de preparo usam o mesmo endpoint, as mesmas credenciais, a mesma validação de solicitação e a mesma cota dos feeds de produção. Apenas o público é diferente.

Substituição

O feed é a unidade de substituição. Cada chamada replaceCandidates substitui todos os candidatos armazenados anteriormente para esse feed e deixa todos os outros feeds intocados.

Substituir candidatos à recomendação

Use o método partners.recommendationsFeeds.replaceCandidates para enviar a lista completa de candidatos à recomendação de um feed.

Solicitação HTTP

POST https://tvvideodiscovery.googleapis.com/v1/{name=partners/*/recommendationsFeeds/*}:replaceCandidates

O caminho do URL contém o nome do recurso do feed em que os candidatos são substituídos. O corpo da solicitação contém todos os campos que não fazem parte do caminho do URL.

Parâmetros de caminho

Parâmetro Descrição
name Obrigatório. O nome do recurso do feed, no formato partners/{partner}/recommendationsFeeds/{recommendationsFeed}. {partner} precisa ser o ID do parceiro ao qual sua conta de serviço está mapeada. {recommendationsFeed} precisa ser um ID de feed que o Google criou para esse parceiro ou esse ID de feed com o sufixo -staging.

ReplaceCandidatesRequest

O corpo da solicitação JSON tem a seguinte estrutura:

Campo Tipo Obrigatório Descrição
recommendation_candidates array of RecommendationCandidate Sim Uma lista de 1 a 25 itens RecommendationCandidate. Esses candidatos substituem os atuais do feed.

Esquemas candidatos

Cada item em recommendation_candidates é um objeto RecommendationCandidate que contém um payload do tipo candidato, motivos de recomendação opcionais e períodos de disponibilidade de exibição opcionais.

RecommendationCandidate

Um objeto RecommendationCandidate contém exatamente um campo de payload de tipo de mídia, motivos de recomendação opcionais e intervalos de disponibilidade opcionais.

Campo de união candidate_type

candidate_type é obrigatório: defina exatamente um dos campos a seguir. Os campos são mutuamente exclusivos, e um candidato que não define nenhum ou mais de um é rejeitado. Não há chave candidate_type no JSON. Defina o campo escolhido diretamente no objeto RecommendationCandidate.

Campo Tipo Descrição
movie_candidate MovieCandidate Um filme on demand (consulte MovieCandidate).
tv_show_candidate TvShowCandidate Uma série de TV no nível do programa (consulte TvShowCandidate).
live_tv_program_candidate LiveTvProgramCandidate Uma transmissão de TV ao vivo programada ou um evento transmitido (consulte LiveTvProgramCandidate).

Contexto e disponibilidade

Os dois campos são opcionais:

Campo Tipo Obrigatório Descrição
recommendation_contexts array of RecommendationContext Não Por que o candidato é recomendado e por quanto tempo cada motivo se aplica (consulte RecommendationContext).
availability_intervals array of Interval Não Janelas de tempo em que o candidato pode ser mostrado (consulte Interval). Cada janela começa em start_time (inclusive) e termina em end_time (exclusive). Se não for definido, o candidato vai se qualificar enquanto estiver armazenado. Um candidato com todas as janelas no passado nunca é mostrado.

MovieCandidate

O objeto MovieCandidate representa um filme on demand:

Campo Tipo Obrigatório Descrição
title LocalizedString Sim Título do filme (consulte LocalizedString). Cada valor tem de 1 a 100 pontos de código Unicode e é mostrado como enviado.
description LocalizedString Sim Breve descrição do filme (consulte LocalizedString). Cada valor tem de 1 a 400 pontos de código Unicode.
localized_media_images array of LocalizedMediaImage Sim Imagens de arte em 16:9, uma entrada por idioma (consulte LocalizedMediaImage). É necessário incluir pelo menos uma imagem. Forneça a maior fonte disponível. Recomendamos 1920 x 1080 pixels.
localized_provider_playback_uris array of LocalizedProviderPlaybackUri Sim Links diretos por plataforma e por idioma (consulte LocalizedProviderPlaybackUri). Pelo menos uma entrada precisa listar PLATFORM_ANDROID_TV.
release_date Date Sim Data de lançamento do filme (consulte Date).
external_entity_ids array of ExternalEntityId Não Identificadores de catálogo externo para correspondência de entidades (consulte ExternalEntityId). No máximo uma entrada por tipo de identificador.
duration string (Duration) Não A duração do filme (consulte Duration). Por exemplo, "7200s" para 2 horas.
content_ratings array of ContentRating Não Classificações oficiais de conteúdo (consulte ContentRating).

TvShowCandidate

O objeto TvShowCandidate representa uma série de TV no nível da série. Os dispositivos Google TV e Android TV mostram um card para o programa. Use o link direto para decidir se a reprodução começa na página do programa ou em um episódio específico.

Campo Tipo Obrigatório Descrição
title LocalizedString Sim Título da série de TV (consulte LocalizedString). Cada valor tem de 1 a 100 pontos de código Unicode e é mostrado como enviado.
description LocalizedString Sim Breve descrição do programa de TV (consulte LocalizedString). Cada valor tem de 1 a 400 pontos de código Unicode.
localized_media_images array of LocalizedMediaImage Sim Imagens de arte em 16:9, uma entrada por idioma (consulte LocalizedMediaImage). É necessário incluir pelo menos uma imagem. Forneça a maior fonte disponível. Recomendamos 1920 x 1080 pixels.
localized_provider_playback_uris array of LocalizedProviderPlaybackUri Sim Links diretos por plataforma e por idioma (consulte LocalizedProviderPlaybackUri). Pelo menos uma entrada precisa listar PLATFORM_ANDROID_TV. O uri pode apontar para a página do programa ou para um episódio.
first_episode_air_date Date Sim Data de estreia do primeiro episódio (consulte Date).
external_entity_ids array of ExternalEntityId Não Identificadores de catálogo externo para correspondência de entidades (consulte ExternalEntityId). No máximo uma entrada por tipo de identificador.
season_count integer (int32) Não Número de temporadas disponíveis no seu serviço.
content_ratings array of ContentRating Não Classificações oficiais de conteúdo (consulte ContentRating).

LiveTvProgramCandidate

O objeto LiveTvProgramCandidate representa uma transmissão de TV ao vivo programada ou um evento transmitido. A janela de transmissão faz parte do candidato e é separada do availability_intervals do candidato pai, que controla quando o card pode ser mostrado.

Campo Tipo Obrigatório Descrição
title LocalizedString Sim Título do programa de TV ao vivo (consulte LocalizedString). Cada valor tem de 1 a 100 pontos de código Unicode e é mostrado como enviado.
description LocalizedString Sim Breve descrição do programa de TV ao vivo (consulte LocalizedString). Cada valor tem de 1 a 400 pontos de código Unicode.
localized_media_images array of LocalizedMediaImage Sim Imagens de arte em 16:9, uma entrada por idioma (consulte LocalizedMediaImage). É necessário incluir pelo menos uma imagem. Forneça a maior fonte disponível. Recomendamos 1920 x 1080 pixels.
localized_provider_playback_uris array of LocalizedProviderPlaybackUri Sim Links diretos por plataforma e por idioma (consulte LocalizedProviderPlaybackUri). Pelo menos uma entrada precisa listar PLATFORM_ANDROID_TV.
broadcast_interval Interval Sim Início e fim da transmissão do programa (consulte Interval). start_time e end_time são obrigatórios.
external_entity_ids array of ExternalEntityId Não Identificadores de catálogo externo para correspondência de entidades (consulte ExternalEntityId). No máximo uma entrada por tipo de identificador.
content_ratings array of ContentRating Não Classificações oficiais de conteúdo (consulte ContentRating).

Esquemas de suporte

Os payloads candidatos fazem referência aos seguintes objetos compartilhados para texto localizado, links diretos, arte, identificadores externos, motivos de recomendação, intervalos de exibição, classificações de conteúdo e tipos de data e hora conhecidos.

LocalizedString

O objeto LocalizedString carrega o mesmo texto em um ou mais idiomas. Cada valor é marcado com o idioma para que os dispositivos Google TV e Android TV possam mostrar o texto que corresponde ao idioma do dispositivo de TV do usuário:

Campo Tipo Obrigatório Descrição
values array of LocalizedText Sim O texto em cada idioma que você fornecer (consulte LocalizedText). Precisa conter pelo menos um valor.

LocalizedText

O objeto LocalizedText é um texto em um único idioma:

Campo Tipo Obrigatório Descrição
text string Sim O texto no idioma fornecido por language_code.
language_code string Sim Código de idioma BCP-47 de text, como "en-US" ou "sr-Latn".

LocalizedMediaImage

O objeto LocalizedMediaImage associa uma imagem ao idioma de qualquer texto nela:

Campo Tipo Obrigatório Descrição
language_code string Sim Código de idioma BCP-47 do texto na imagem, como "en-US" ou "sr-Latn".
image MediaImage Sim Uma imagem de 16:9 (consulte MediaImage). Forneça a maior fonte disponível. Recomendamos 1920 x 1080 pixels.

LocalizedProviderPlaybackUri

O objeto LocalizedProviderPlaybackUri associa um link direto ao idioma do conteúdo que ele abre e ao app que o abre:

Campo Tipo Obrigatório Descrição
playback_uri PlaybackUri Sim O link direto e as plataformas em que ele se aplica (consulte PlaybackUri).
language_code string Sim Código de idioma BCP-47 do conteúdo que o link direto abre, como "en-US" ou "sr-Latn".
package_name string Sim Nome do pacote de aplicativo Android usado para abrir o link direto (por exemplo, "com.example.tvapp").

PlaybackUri

O objeto PlaybackUri define um link direto e as plataformas de destino:

Campo Tipo Obrigatório Descrição
uri string Sim URI do link direto que inicia a reprodução do candidato no seu app.
platforms array of string (enum) Sim Plataformas em que este link direto é válido. Valores permitidos: PLATFORM_UNSPECIFIED, PLATFORM_ANDROID_TV, PLATFORM_ANDROID, PLATFORM_IOS. Inclua PLATFORM_ANDROID_TV para dispositivos Google TV e Android TV.

MediaImage

O objeto MediaImage especifica um URL de imagem, as dimensões em pixels e o texto de acessibilidade:

Campo Tipo Obrigatório Descrição
url string Sim URL HTTPS de acesso público da imagem.
width integer Sim Largura da imagem não modificada (máxima) em pixels.
height integer Sim Altura máxima da imagem não modificada em pixels.
accessibility_text string Sim Texto de acessibilidade (alternativo) que descreve a imagem.

ExternalEntityId

O objeto ExternalEntityId mapeia um candidato para um identificador em um catálogo externo. Defina exatamente um dos campos a seguir por entrada e inclua no máximo uma entrada por tipo de identificador na lista external_entity_ids de um candidato:

Campo Tipo Obrigatório Descrição
tms_root_id string Uma ID raiz do TMS da Gracenote. Identifica um título: um filme, um programa ou um episódio.
tms_id string Uma ID da variante do TMS da Gracenote. Identifica uma edição ou uma listagem de transmissão.
data_feed_element_id string Uma ID da entidade do seu feed de dados de ações de mídia. Esse valor não está relacionado ao segmento {recommendationsFeed} do nome do recurso.

RecommendationContext

O objeto RecommendationContext explica por que um candidato é recomendado e por quanto tempo essa explicação se aplica:

Campo Tipo Obrigatório Descrição
recommendation_reason RecommendationReason Não Por que o candidato é recomendado (consulte RecommendationReason).
validity_interval Interval Não Janela de tempo em que esse contexto se aplica (consulte Interval). Por exemplo, um candidato é novo apenas por um número limitado de dias. Se não for definido, o contexto será aplicado enquanto o candidato estiver armazenado.

RecommendationReason

O objeto RecommendationReason carrega um motivo. Defina exatamente um dos seguintes campos:

Campo Tipo Obrigatório Descrição
top_on_partner object Uma O candidato é um item de classificação superior no seu serviço. Contém um único campo de número inteiro positivo rank (por exemplo, {"rank": 1} para "Top 1 no parceiro").
popular_on_partner object Uma O candidato é popular no seu serviço. Transmita um objeto vazio ({}).
new_on_partner object Uma O candidato é novo no seu serviço. Transmita um objeto vazio ({}).
generic object Uma Um motivo personalizado. Contém um único campo LocalizedString generic_reason (consulte LocalizedString). Cada valor tem de 1 a 100 pontos de código Unicode.

ContentRating

O objeto ContentRating representa uma classificação de conteúdo oficial atribuída por uma agência de classificação:

Campo Tipo Obrigatório Descrição
rating_system string Sim Agência ou sistema de classificação, por exemplo, "MPAA", "BBFC" ou "CBFC".
rating_value string Sim Classificação conforme definido por rating_system, por exemplo, "PG-13" ou "U/A 13+".

Timestamp

Um Timestamp é codificado em JSON como uma string RFC 3339 em UTC com um sufixo Z, por exemplo, "2026-10-01T18:00:00Z". Frações de segundos são permitidas, por exemplo, "2026-10-01T18:00:00.500Z".

Duration

Um Duration é codificado em JSON como uma string que contém o número de segundos seguido pelo sufixo s, por exemplo, "7200s" para 2 horas. Segundos fracionários são permitidos, por exemplo, "5400.5s".

Date

Um Date é uma data de calendário sem fuso horário. Ele é codificado em JSON como um objeto com os seguintes campos:

Campo Tipo Obrigatório Descrição
year integer Sim Ano da data, por exemplo, 2025.
month integer Não Mês do ano, de 1 a 12. Defina como 0 ou omita se o mês não for conhecido.
day integer Não Dia do mês, de 1 a 31, válido para o ano e o mês informados. Defina como 0 ou omita se o dia não for conhecido. Requer month.

Por exemplo, {"year": 2025, "month": 1, "day": 17} representa 17 de janeiro de 2025, {"year": 2025, "month": 1} representa janeiro de 2025 com um dia desconhecido e {"year": 2025} representa uma data em 2025 com um mês e dia desconhecidos.

Interval

Um Interval é uma janela de tempo semiaberta que começa em start_time (inclusive) e termina em end_time (exclusive). Um horário T está dentro do intervalo quando start_time <= T e T < end_time.

Campo Tipo Obrigatório Descrição
start_time string (Timestamp) Sim Início inclusivo da janela (consulte Timestamp), por exemplo, "2026-10-01T18:00:00Z".
end_time string (Timestamp) Sim Fim exclusivo da janela (consulte Timestamp), por exemplo, "2026-10-01T21:00:00Z". Precisa ser posterior a start_time.

Exemplo de solicitação

O exemplo a seguir substitui os candidatos do feed in-en-cricket do parceiro example-partner por três candidatos (um filme, um programa de TV e um programa de TV ao vivo). O filme tem texto em dois idiomas:

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"
          }
        ]
      }
    ]
  }'

Comportamento de resposta e substituição

Nesta seção, descrevemos a resposta HTTP retornada por replaceCandidates e como cada chamada atualiza os candidatos armazenados.

ReplaceCandidatesResponse

Se a solicitação for bem-sucedida, a API vai retornar HTTP 200 OK com um corpo ReplaceCandidatesResponse:

Campo Tipo Descrição
replaced_candidates_count integer (int32) Número de candidatos substituídos.

Para o exemplo de solicitação anterior, a resposta é:

{
  "replaced_candidates_count": 3
}

Comportamento de substituição

Entender como o replaceCandidates atualiza os candidatos armazenados é essencial para projetar sua integração:

  • Substituição completa por feed. Cada chamada substitui completamente a lista de candidatos armazenada anteriormente para o feed nomeado no caminho do URL. Sempre envie o conjunto completo de candidatos ativos para esse feed.
  • Os outros feeds permanecem inalterados. Os feeds para os quais você não envia candidatos permanecem inalterados até que você faça isso. Por exemplo, substituir os candidatos de um feed não modifica os candidatos armazenados para nenhum outro feed, e substituir os candidatos de {recommendationsFeed}-staging não modifica {recommendationsFeed}.
  • Uma chamada por feed. Para atualizar vários feeds, faça uma chamada por feed. As chamadas são independentes: se uma falhar, os outros feeds vão manter os novos candidatos, e você vai tentar novamente apenas a chamada que falhou.
  • Reenvie os feeds ativos pelo menos a cada 30 dias. Mesmo que o catálogo de um feed não tenha mudado, reenvie cada feed ativo pelo menos uma vez a cada 30 dias (ou em uma programação diária ou semanal regular com jitter aleatório) para que os candidatos permaneçam ativos e não expirem. Definir um end_time availability_intervals muito distante no futuro não substitui o reenvio periódico.
  • Execução atômica. A API aplica a solicitação de forma atômica. Se algum candidato não for validado, a API vai rejeitar toda a solicitação, e o feed vai manter os candidatos anteriores.