Integração pela API¶

Um sistema externo pode criar streams e canais, atribuir assinaturas e obter endereços para uma aplicação do espectador. Os dois exemplos abaixo vão da criação de um stream até a obtenção de uma URL de reprodução para um assinante.

Abrir a referência da API¶

A referência está incorporada na sua instalação da Catena. Abra-a pelo console ou substitua https://catena.example.com pelo endereço da sua instalação:

Central API — https://catena.example.com/central/api-v4/docs/: configuração de streams e gestão do cluster.
Catena API — https://catena.example.com/catena/api-v1/docs/: canais, pacotes e assinantes.
Catena TV API — https://catena.example.com/catena/api-v1/docs/tv/: entrada do espectador e canais acessíveis.
Playback API — https://catena.example.com/central/api-v4/docs/playback/: reprodução de mídia.

Cada página oferece busca e Download OpenAPI JSON. O esquema corresponde à compilação instalada. As páginas de referência abrem sem autenticação quando o prefixo da API está exposto; as requisições de gestão exigem autenticação.

Entidades e autenticação¶

Stream armazena as configurações de transmissão. Um canal armazena o título e o número da vitrine, faz referência a um stream por stream_name e pertence a pacotes.
Credenciais do operador autenticam as requisições às APIs do central e da Catena. Os exemplos usam HTTP Basic; envie a senha por HTTPS.
Token do dispositivo é retornado quando um assinante entra pela TV API. Envie-o nas requisições seguintes como Authorization: Bearer …. O assinante também tem um playback_token separado, que a TV API aceita para identificar o assinante.
Ticket de reprodução já está incluído na playback_url retornada pela TV API. Não é necessário passar ao reprodutor o token do dispositivo nem a senha do operador.

Antes de começar¶

Antes de começar, prepare:

Bash — para executar os exemplos em uma sessão.
curl — para enviar requisições HTTP.
jq — para criar e ler JSON.
Uma conta de operador com permissão para alterar as configurações.

Execute os dois exemplos na mesma sessão do Bash: o segundo usa variáveis do primeiro. Os comandos criam registros de teste na sua instalação; use um ambiente de teste. A entrada de senhas fica oculta e as senhas não são escritas nos comandos.

Criar um stream e um canal¶

Defina BASE e API_USER para a sua instalação. O exemplo cria um stream desativado sem fonte (enabled: false), para verificar as operações da API sem iniciar uma transmissão. If-None-Match: * impede a substituição de um stream existente com o mesmo nome.

set -euo pipefail

BASE='https://catena.example.com'
API_USER='admin'
read -r -s -p 'Operator password: ' API_PASSWORD
printf '\n'

BASE="${BASE%/}"
STREAM="api-example-$(date +%s)"

curl -fsS -u "$API_USER:$API_PASSWORD" \
  -X PUT "$BASE/central/api-v4/streams/configs/$STREAM" \
  -H 'Content-Type: application/json' \
  -H 'If-None-Match: *' \
  -d '{"title":"Integration example","enabled":false}'

CHANNEL=$(
  jq -n --arg stream "$STREAM" \
    '{title:"Example channel",number:1,stream_name:$stream}' |
  curl -fsS -u "$API_USER:$API_PASSWORD" \
    -X POST "$BASE/catena/api-v1/channels" \
    -H 'Content-Type: application/json' --data-binary @-
)
CHANNEL_ID=$(printf '%s' "$CHANNEL" | jq -er '.id')

CHANNEL=$(
  curl -fsS -u "$API_USER:$API_PASSWORD" \
    "$BASE/catena/api-v1/channels/$CHANNEL_ID"
)
VERSION=$(printf '%s' "$CHANNEL" | jq -er '.version')

curl -fsS -u "$API_USER:$API_PASSWORD" \
  -X PATCH "$BASE/catena/api-v1/channels/$CHANNEL_ID" \
  -H 'Content-Type: application/json' \
  -H "If-Match: \"$VERSION\"" \
  -d '{"title":"Updated example channel"}' | jq .

A resposta de criação do canal contém seu id. Antes de editá-lo, leia o canal e obtenha sua version: para este recurso, o ETag é essa versão entre aspas. PATCH envia apenas o novo título; a referência ao stream é preservada.

Atribuir uma assinatura e obter uma URL¶

Continue na mesma sessão. Digite uma senha de pelo menos oito caracteres para o assinante de teste. Crie um pacote que exija assinatura (free: false), adicione o canal ao pacote e assine o pacote para o assinante. Em seguida, entre como espectador. O nome do pacote deve conter de 2 a 20 caracteres: letras latinas, dígitos, hífens ou sublinhados.

read -r -s -p 'Subscriber password: ' SUB_PASSWORD
printf '\n'

LOGIN="api-$(date +%s)"

PACKAGE=$(
  jq -n --arg name "$LOGIN" '{name:$name,free:false}' |
  curl -fsS -u "$API_USER:$API_PASSWORD" \
    -X POST "$BASE/catena/api-v1/packages" \
    -H 'Content-Type: application/json' --data-binary @-
)
PACKAGE_ID=$(printf '%s' "$PACKAGE" | jq -er '.id')

jq -n --arg p "$PACKAGE_ID" --arg c "$CHANNEL_ID" \
  '{package_id:$p,channel_id:$c}' |
curl -fsS -u "$API_USER:$API_PASSWORD" \
  -X POST "$BASE/catena/api-v1/package-channels" \
  -H 'Content-Type: application/json' --data-binary @-

SUBSCRIBER=$(
  curl -fsS -u "$API_USER:$API_PASSWORD" \
    -X POST "$BASE/catena/api-v1/subscribers" \
    -H 'Content-Type: application/json' \
    -d '{"name":"Integration example"}'
)
SUBSCRIBER_ID=$(printf '%s' "$SUBSCRIBER" | jq -er '.id')

jq -n --arg login "$LOGIN" --arg password "$SUB_PASSWORD" \
  '{login:$login,password:$password}' |
curl -fsS -u "$API_USER:$API_PASSWORD" \
  -X PATCH "$BASE/catena/api-v1/subscribers/$SUBSCRIBER_ID/credentials" \
  -H 'Content-Type: application/json' --data-binary @- >/dev/null

jq -n --arg s "$SUBSCRIBER_ID" --arg p "$PACKAGE_ID" \
  '{subscriber_id:$s,package_id:$p}' |
curl -fsS -u "$API_USER:$API_PASSWORD" \
  -X POST "$BASE/catena/api-v1/subscriptions" \
  -H 'Content-Type: application/json' --data-binary @-

SESSION=$(
  jq -n --arg login "$LOGIN" --arg password "$SUB_PASSWORD" \
    '{login:$login,password:$password,device_name:"Example app"}' |
  curl -fsS -X POST "$BASE/playback/tv/login" \
    -H 'Content-Type: application/json' --data-binary @-
)
DEVICE_TOKEN=$(printf '%s' "$SESSION" | jq -er '.token')

curl -fsS "$BASE/playback/tv/channels" \
  -H "Authorization: Bearer $DEVICE_TOKEN" |
jq --arg id "$CHANNEL_ID" \
  '.channels[] | select(.id == $id) | {title,playback_url}'

A última requisição mostra o título do canal e playback_url, um caminho a partir da raiz da instalação que já inclui o ticket. Acrescente BASE antes do caminho para obter a URL absoluta. Consulte /playback/tv/channels novamente para obter um ticket atualizado. GET /playback/tv/channels/{channel_id}/play, com autenticação do espectador, retorna 307 e um cabeçalho Location com a URL de reprodução.

Requisitos de reprodução¶

Obter uma URL confirma que o assinante tem acesso ao canal. Para assistir ao vídeo, configure a fonte do stream, ative o stream e verifique sua atribuição a um streamer. Este exemplo mantém o stream desativado. As configurações de acesso ao vídeo estão em proteção da reprodução e tickets da Catena.

Tratar erros¶

401 — verifique as credenciais do operador ou o token do espectador. As APIs de gestão e TV usam credenciais diferentes.
412 — o registro mudou. Leia-o novamente e revise os valores atuais antes de enviar outro PATCH com a nova versão.
422 — verifique error.errors: cada item contém um path para o campo inválido e um message. Por exemplo, uma string em vez de um inteiro em number retorna o caminho ["number"].

Um canal aparece para o assinante se pertencer a um pacote que ele assina ou a um pacote gratuito. Neste exemplo, o canal não aparece antes da atribuição da assinatura. Consulte as regras de acesso do assinante.

Excluir os registros de teste¶

Após a verificação, execute estes comandos na mesma sessão. Eles excluem os registros criados nos exemplos; as assinaturas e os vínculos entre o pacote e o canal são removidos em cascata.

curl -fsS -u "$API_USER:$API_PASSWORD" \
  -X DELETE "$BASE/catena/api-v1/subscribers/$SUBSCRIBER_ID"
curl -fsS -u "$API_USER:$API_PASSWORD" \
  -X DELETE "$BASE/catena/api-v1/packages/$PACKAGE_ID"
curl -fsS -u "$API_USER:$API_PASSWORD" \
  -X DELETE "$BASE/catena/api-v1/channels/$CHANNEL_ID"
curl -fsS -u "$API_USER:$API_PASSWORD" \
  -X DELETE "$BASE/central/api-v4/streams/configs/$STREAM"