Integración mediante API¶

Un sistema externo puede crear streams y canales, asignar suscripciones y obtener direcciones para una aplicación del espectador. Los dos ejemplos siguientes van desde la creación de un stream hasta la obtención de una URL de reproducción para un suscriptor.

Abrir la referencia de la API¶

La referencia está incorporada en su instalación de Catena. Ábrala desde la consola o sustituya https://catena.example.com por la dirección de su instalación:

Central API — https://catena.example.com/central/api-v4/docs/: configuración de streams y gestión del clúster.
Catena API — https://catena.example.com/catena/api-v1/docs/: canales, paquetes y suscriptores.
Catena TV API — https://catena.example.com/catena/api-v1/docs/tv/: inicio de sesión del espectador y canales accesibles.
Playback API — https://catena.example.com/central/api-v4/docs/playback/: reproducción de medios.

Cada página ofrece búsqueda y Download OpenAPI JSON. El esquema corresponde a la compilación instalada. Las páginas de referencia se abren sin autenticación si su prefijo de API está expuesto; las solicitudes de gestión requieren autenticación.

Entidades y autenticación¶

Stream almacena la configuración de emisión. Un canal almacena el título y el número de la vitrina, hace referencia a un stream mediante stream_name y pertenece a paquetes.
Credenciales del operador autentican las solicitudes a las API de Central y Catena. Los ejemplos usan HTTP Basic; envíe la contraseña mediante HTTPS.
Token del dispositivo se devuelve cuando un suscriptor inicia sesión mediante la TV API. Envíelo en las solicitudes siguientes como Authorization: Bearer …. El suscriptor también tiene un playback_token independiente, que la TV API acepta para identificar al suscriptor.
Ticket de reproducción ya está incluido en la playback_url devuelta por la TV API. No necesita pasar al reproductor el token del dispositivo ni la contraseña del operador.

Antes de empezar¶

Antes de empezar, prepare:

Bash — para ejecutar los ejemplos en una sesión.
curl — para enviar solicitudes HTTP.
jq — para crear y leer JSON.
Una cuenta de operador con permiso para cambiar la configuración.

Ejecute ambos ejemplos en la misma sesión de Bash: el segundo utiliza variables del primero. Los comandos crean registros de prueba en su instalación; utilice un entorno de pruebas. La entrada de contraseñas está oculta y las contraseñas no se escriben en los comandos.

Crear un stream y un canal¶

Configure BASE y API_USER para su instalación. El ejemplo crea un stream desactivado sin fuente (enabled: false), para comprobar las operaciones de la API sin iniciar una emisión. If-None-Match: * impide sobrescribir un stream existente con el mismo nombre.

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 .

La respuesta de creación del canal contiene su id. Antes de editarlo, lea el canal y obtenga su version: para este recurso, el ETag es esa versión entre comillas. PATCH envía solo el nuevo título; se conserva la referencia al stream.

Asignar una suscripción y obtener una URL¶

Continúe en la misma sesión. Introduzca una contraseña de al menos ocho caracteres para el suscriptor de prueba. Cree un paquete que requiera suscripción (free: false), añada el canal al paquete y suscriba al suscriptor. Después, inicie sesión como espectador. El nombre del paquete debe contener entre 2 y 20 caracteres: letras latinas, dígitos, guiones o guiones bajos.

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

La última solicitud muestra el título del canal y playback_url, una ruta desde la raíz de la instalación que ya incluye el ticket. Anteponiendo BASE se obtiene la URL absoluta. Solicite de nuevo /playback/tv/channels para obtener un ticket actualizado. GET /playback/tv/channels/{channel_id}/play, con autenticación del espectador, devuelve 307 y una cabecera Location con la URL de reproducción.

Requisitos de reproducción¶

Obtener una URL confirma que el suscriptor tiene acceso al canal. Para ver el vídeo, configure la fuente del stream, active el stream y compruebe su asignación a un streamer. Este ejemplo deja el stream desactivado. La configuración de acceso al vídeo se describe en protección de la reproducción y tickets de Catena.

Gestionar errores¶

401 — compruebe las credenciales del operador o el token del espectador. Las API de gestión y TV utilizan credenciales distintas.
412 — el registro ha cambiado. Léalo de nuevo y revise los valores actuales antes de enviar otro PATCH con la nueva versión.
422 — revise error.errors: cada elemento contiene un path al campo incorrecto y un message. Por ejemplo, una cadena en lugar de un entero en number devuelve la ruta ["number"].

Un canal aparece para un suscriptor si pertenece a un paquete al que está suscrito o a un paquete gratuito. En este ejemplo, el canal no aparece antes de asignar la suscripción. Consulte las reglas de acceso del suscriptor.

Eliminar los registros de prueba¶

Tras la comprobación, ejecute estos comandos en la misma sesión. Eliminan los registros creados en los ejemplos; las suscripciones y los vínculos entre el paquete y el canal se eliminan en cascada.

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"