Referencia de la Video API REST de Vonage

Utiliza la API REST de OpenTok para crear sesiones de OpenTok, gestionar archivos y gestionar retransmisiones en directo. La SDK de servidor de OpenTok (para Java, .NET, Node.js, PHP, Pythony Rubí) implementan muchos de los métodos de la API REST.

La API REST incluye métodos para lo siguiente:

Creación de sesiones, señalización y moderación

Archivado

Interconexión SIP

Retransmisiones en directo

Subtítulos en directo

Experiencia con Composer

Conector de audio

Gestión de cuentas

El SDK de OpenTok Envolver la API REST de OpenTok para facilitar la realización de llamadas a la plataforma OpenTok.

Autenticación

Las llamadas a la API REST deben autenticarse mediante un encabezado HTTP personalizado — X-OPENTOK-AUTH — junto con un Token web JSON. Crea el token JWT con las siguientes reclamaciones:

{
	"iss": "your_api_key",
	"ist": "project",
	"iat": current_timestamp_in_seconds,
	"exp": expire_timestamp_in_seconds,
	"jti": "jwt_nonce"
}

Conjunto iss a tu clave API de OpenTok. Para la mayoría de las llamadas a la API REST, utiliza la clave API del proyecto específico de tu Account. Esta se encuentra en la página «Proyecto» de tu Account de la Video API. Sin embargo, los siguientes métodos REST están restringidos a los administradores registrados de la cuenta de OpenTok. Para utilizar estos métodos, debes configurar iss a la a nivel de cuenta Clave API, a la que solo tienen acceso los administradores de la cuenta. (véase Gestión de cuentas):

Para obtener la clave y el secreto de la API a nivel de Account, inicia sesión en tu Account de la Video APIpulse Configuración de la cuenta en el menú de la izquierda y, a continuación, en la sección API REST de OpenTokpulse Ver claves de la cuenta.

Para la mayoría de las llamadas a la API REST, configura ist a "project". Sin embargo, en los siguientes casos Gestión de cuentas Métodos REST, conjunto ist a "account":

Conjunto iat a la marca de tiempo de época Unix actual (cuando se creó el token), en segundos.

Conjunto exp hasta la hora de caducidad del token. Por motivos de seguridad, te recomendamos que utilices una hora de caducidad cercana a la hora de creación del token (por ejemplo, 3 minutos después de su creación) y que crees un nuevo token para cada llamada a la API REST. El intervalo máximo permitido para la hora de caducidad es de 5 minutos.

Conjunto jti a un identificador único para el JWT. Esto es opcional. Consulta el Especificación de token web JSON Para más información.

Utiliza tu clave secreta de la API de OpenTok como clave secreta del JWT y fírmalo con el algoritmo de cifrado HMAC-SHA256. Para la mayoría de las llamadas a la API REST, utiliza la clave secreta de la API correspondiente al proyecto específico de tu Account. Esta se encuentra en la página «Proyecto» de tu Account Account de la Video API. Sin embargo, los siguientes métodos REST están restringidos a los administradores registrados de la cuenta de OpenTok. Para utilizar estos métodos, debes utilizar el a nivel de cuenta API clave y secreto (que solo está disponible para los administradores de la cuenta) como clave secreta del JWT (véase Gestión de cuentas):

Por ejemplo, el siguiente código en Python crea un token que se puede utilizar en una llamada a la API REST de OpenTok:

import jwt # See https://pypi.python.org/pypi/PyJWT
import time
import uuid
print jwt.encode({"iss": "my-OpenTok-API-key",
  "iat": int(time.time()),
  "exp": int(time.time()) + 180,
  "ist": "project",
  "jti": str(uuid.uuid4())},
  'my-OpenTok-API-secret',
  algorithm='HS256')

Sustituye el my-OpenTok-API-key y my-OpenTok-API-secret con la clave API y el secreto API de OpenTok.

Nota: Antes de utilizar los tokens web JSON, las llamadas a la API REST de OpenTok se autenticaban mediante un encabezado HTTP personalizado: X-TB-PARTNER-AUTH con el valor establecido como tu clave API de OpenTok y tu secreto API concatenados con dos puntos:

X-TB-PARTNER-AUTH: <api_key>:<partner_secret>

Sin embargo, esta forma de autenticación (mediante X-TB-PARTNER-AUTH) es en desuso, y ahora deberías utilizar tokens web JSON para la autenticación. (El uso de este método de autenticación, que ha quedado obsoleto, dejará de estar disponible en julio de 2017.)

Crear una sesión

Generar una nueva sesión.

URL del recurso:

https://api.opentok.com/session/create

Verbo de recurso:

PUBLICAR

Propiedades del encabezado POST

Las llamadas a la API deben autenticarse mediante un encabezado HTTP personalizado — X-OPENTOK-AUTH — junto con un token web JSON (JWT). Véase Autenticación.

Fije el Content-Type encabezado a application/x-www-form-urlencoded:

Content-Type:application/x-www-form-urlencoded

Fije el Accept encabezado a application/json:

Accept:application/json

Parámetros POST

archiveName

El nombre que se utilizará para los archivos en las sesiones archivadas automáticamente. Al configurar esta opción, el archiveMode La opción debe configurarse en always o se producirá un error. La longitud del nombre del archivo comprimido puede ser de hasta 80 caracteres. Debido a limitaciones de codificación, los siguientes caracteres especiales se sustituyen por dos puntos (:): ~, -, _. Si no se especifica un nombre y el archiveMode la opción está configurada en always, el nombre del archivo estará vacío.

archiveResolution

La resolución de los archivos en una sesión con archivado automático. Los valores válidos son «480x640», «640x480» (el valor por defecto), «720x1280», «1280x720», «1080x1920» y «1920x1080». Al configurar esta opción, el archiveMode La opción debe configurarse en always o se producirá un error.

location

La dirección IP que utilizará la Video API de Vonage para ubicar la sesión en su red global. Si no se proporciona ninguna indicación de ubicación (lo cual se recomienda), la sesión utilizará un servidor multimedia en función de la ubicación del primer cliente que se conecte a la sesión. Indica una referencia de ubicación solo si conoces la región geográfica general (y una dirección IP representativa) y crees que el primer cliente que se conecte podría no encontrarse en esa región. Especifica una dirección IP que sea representativa de la ubicación geográfica de la sesión.

p2p.preference

Establecer en enabled Si prefieres que los clientes intenten enviar flujos de audio y vídeo directamente a otros clientes, configura esta opción en disabled para sesiones que utilicen el OpenTok Media Router. (Opcional; la configuración predeterminada es disabled -- la sesión utiliza el OpenTok Media Router.)

El OpenTok Media Router ofrece las siguientes ventajas:

  • El OpenTok Media Router puede reducir el consumo de ancho de banda en sesiones con varios participantes. (Cuando la propiedad p2p.preference está configurada en enabledcada cliente debe enviar un flujo de audio-vídeo independiente a cada cliente que se suscriba a él).
  • El OpenTok Media Router puede mejorar la calidad de la experiencia del usuario mediante recuperación de audio y vídeo. Gracias a estas características, si la conexión de un cliente se deteriora hasta tal punto que no permite la reproducción del vídeo de una transmisión a la que está suscrito, el vídeo se interrumpe en ese cliente (sin que ello afecte al resto de clientes) y el cliente solo recibe el audio. Si la conexión del cliente mejora, el vídeo vuelve a mostrarse.
  • El OpenTok Media Router es compatible con el función de archivo, que te permite grabar, guardar y recuperar sesiones de OpenTok.

Con el p2p.preference Si esta propiedad se establece en «enabled», la sesión intentará transmitir los flujos directamente entre los clientes. Si los clientes no pueden conectarse debido a restricciones del cortafuegos, la sesión utiliza el servidor TURN de OpenTok para retransmitir los flujos de audio y vídeo.

Ejemplos de solicitudes

POST /session/create HTTP/1.1
Host: https://api.opentok.com
X-OPENTOK-AUTH: json_web_token
Accept:application/json

location=10.1.200.30&p2p.preference=disabled

El siguiente ejemplo de línea de comandos crea una sesión que utiliza OpenTok Media Router y especifica una sugerencia de ubicación:

export TB_url=https://api.opentok.com/session/create
json_web_token="jwt_string" # replace with a JSON web token (see "Authentication")
datastr="location=10.1.200.30"
curl \
   -X POST \
   -H "Content-Type:application/x-www-form-urlencoded" \
   -H "Accept:application/json" \
   -H "X-OPENTOK-AUTH:$json_web_token" \
   -d $datastr \
   $TB_url

El siguiente ejemplo de línea de comandos crea una sesión que intenta transmitir flujos directamente entre clientes (sin utilizar el OpenTok Media Router):

export TB_url=https://api.opentok.com/session/create
json_web_token="jwt_string" # replace with a JSON web token (see "Authentication")
datastr="p2p.preference=enabled"
curl \
   -X POST \
   -H "Content-Type:application/x-www-form-urlencoded" \
   -H "Accept:application/json" \
   -H "X-OPENTOK-AUTH:$json_web_token" \
   -d $datastr \
   $TB_url

El siguiente ejemplo de línea de comandos crea una sesión que se archiva automáticamente:

export TB_url=https://api.opentok.com/session/create
json_web_token="jwt_string" # replace with a JSON web token (see "Authentication")
datastr="archiveMode=always"
curl \
   -X POST \
   -H "Content-Type:application/x-www-form-urlencoded" \
   -H "Accept:application/json" \
   -H "X-OPENTOK-AUTH:$json_web_token" \
   -d $datastr \
   $TB_url

Ejemplo de respuesta

La respuesta consiste en datos JSON con el siguiente formato:

[
  {
    "session_id": "the session ID",
    "project_id": "your OpenTok API key",
    "create_dt": "The creation date",
    "media_server_url": "The URL of the OpenTok media router used by the session -- ignore this"
  }
]

Ten en cuenta que, si no incluyes el encabezado «Accept:application/json», el formato de la respuesta será XML. Esta versión XML de la llamada a la API está en desuso.

La respuesta HTTP tendrá un código de estado 403 si se introduce una clave de la API de OpenTok o un token JWT no válido.

La respuesta HTTP presenta un código de estado 500 debido a un error del servidor de OpenTok.

Envío de una señal desde el servidor de tu aplicación a los clientes conectados

Utiliza la API REST de Signal para enviar señales a todos los participantes de una sesión activa de OpenTok o a un cliente concreto conectado a dicha sesión. Las señales enviadas desde el servidor tienen un from parámetro de la señal recibida en los controladores de los clientes conectados a la sesión. En el caso de una señal enviada por un participante de la sesión, el from En esta propiedad se establece el ID de conexión del cliente que envió la señal, pero en este caso no hay ninguna conexión asociada.

En los dos ejemplos de señal que se muestran a continuación, el cuerpo de la solicitud se utilizará para reenviar tanto el type y data campos. Estos se corresponden con los parámetros de tipo y de datos que se pasan a los controladores de recepción de señales del cliente.

type

Cadena. La longitud máxima es de 128 bytes y solo debe contener letras (A-Z y a-z), Numbers (0-9), «-», «_» y «~».

data

Cadena. La longitud máxima es de 8 kb.

Notificar a todos los clientes conectados a la sesión

Envía una solicitud HTTP POST al signal Recurso de la sesión:

SESSION_ID=SOMESESSIONID API_KEY=123456 JWT=jwt_token # replace with a JSON web token (see "Authentication") DATA='{"type":"foo","data":"bar"}' curl -v \ -H "Content-Type: application/json" \ -X POST \ -H "X-OPENTOK-AUTH:${JWT}" \ -d "${DATA}" \ https://api.opentok.com/v2/project/${API_KEY}/session/${SESSION_ID}/signal

Nota: Anteriormente, esta URL REST utilizaba /partner (que ahora está en desuso) en lugar de /project.

Identificar a un cliente concreto conectado a la sesión

Envía una solicitud HTTP POST al signal recurso de un ID de conexión específico, perteneciente a la sesión:

SESSION_ID=SOMESESSIONID CONNECTION_ID=SOMECONNECTIONID API_KEY=123456 JWT=jwt_token # replace with a JSON web token (see "Authentication") DATA='{"type":"foo","data":"bar"}' curl -v \ -H "Content-Type: application/json" \ -X POST \ -H "X-OPENTOK-AUTH:${API_KEY}:${API_SECRET}" \ -d "${DATA}" \ https://api.opentok.com/v2/project/${API_KEY}/session/${SESSION_ID}/connection/${CONNECTION_ID}/signal

Respuestas ante errores de señalización

Los errores se devuelven en la respuesta como códigos de estado HTTP:

  • 400 — Una de las propiedades más destacadas — data, type, sessionId o connectionId — no es válido.
  • 403 — No estás autorizado a enviar la señal. Comprueba tus credenciales de autenticación.
  • 404 — El cliente especificado por el connectionId La propiedad no está vinculada a la sesión.
  • 413 — La cadena de tipo supera la longitud máxima (128 bytes) o la cadena de datos supera el tamaño máximo (8 kB).

En caso de error, el cuerpo de la respuesta tendrá este aspecto:

{
  "code" : 400,
  "message" : "One of the signal properties — data, type, sessionId or connectionId — is invalid."
}

Forzar la desconexión de un punto final de cliente de una sesión

Tu servidor de aplicaciones puede desconectar a un cliente de una sesión de OpenTok enviando una solicitud HTTP DELETE al recurso correspondiente a la conexión de ese cliente:

SESSION_ID=SOMESESSIONID CONNECTION_ID=SOMECONNECTIONID API_KEY=123456 JWT=jwt_token # replace with a JSON web token (see "Authentication") curl -v \ -X DELETE \ -H "X-OPENTOK-AUTH:${JWT}" \ https://api.opentok.com/v2/project/${API_KEY}/session/${SESSION_ID}/connection/${CONNECTION_ID}

Nota: Anteriormente, esta URL REST utilizaba /partner (que ahora está en desuso) en lugar de /project.

Respuestas de error

Los errores se devuelven en la respuesta como códigos de estado HTTP:

  • 400 — Uno de los argumentos — sessionId o connectionId — no es válido.
  • 403 — No estás autorizado a utilizar la función «forceDisconnect»; comprueba tus credenciales de autenticación.
  • 404 — El cliente especificado por el connectionId La propiedad no está vinculada a la sesión.

En caso de error, el cuerpo de la respuesta tendrá este aspecto:

{
  "code" : 404,
  "message" : "Connection not found."
}

Obtener información sobre la transmisión

Utiliza este método para obtener información sobre una transmisión de OpenTok (o sobre todas las transmisiones de una sesión).

Por ejemplo, puedes llamar a este método para obtener información sobre las clases de diseño utilizadas por una transmisión de OpenTok. Las clases de diseño definen cómo se muestra la transmisión en el diseño de una transmisión en directo. Para obtener más información, consulta Asignación de clases de diseño de retransmisiones en directo a las retransmisiones de OpenTok streams.

Solicitud HTTP GET a session/stream

Para obtener información sobre la clase de diseño de un flujo concreto, envía una solicitud HTTP GET a la siguiente URL:

https://api.opentok.com/v2/project/<apiKey>/session/<sessionId>/stream/<streamId>

  • Sustituir <apiKey> con tu clave API de OpenTok.

  • Sustituir <sessionId> con el ID de sesión.

  • Sustituir <streamId> con el ID de la transmisión.

Para obtener información sobre las clases de diseño de todas las secuencias de una sesión, envía una solicitud HTTP GET a la siguiente URL (sin incluir el identificador de la secuencia al final):

https://api.opentok.com/v2/project/<apiKey>/session/<sessionId>/stream/

Propiedades del encabezado GET

Autentifica esta llamada a la API utilizando un encabezado HTTP personalizado — X-OPENTOK-AUTH — configurado como un token web JSON. Véase Autenticación.

Respuesta

Al obtener información sobre la clase de diseño de una sola secuencia, los datos JSON de la respuesta incluyen un layoutClassList matriz:

{
  "id": "8b732909-0a06-46a2-8ea8-074e64d43422",
  "videoType": "camera",
  "name": "",
  "layoutClassList": ["full"]
}
  • El layoutClassList es una matriz de las clases de diseño para el flujo.
  • El id es el ID del flujo.
  • El videoType La propiedad está configurada como «camera», «screen» o «custom». Un vídeo «screen» utiliza la función de compartir pantalla del editor como fuente de vídeo; un vídeo «custom» lo publica un cliente web utilizando un elemento VideoTrack de HTML como fuente de vídeo.
  • El name es el nombre del flujo (si se estableció uno cuando el cliente publicó el flujo).

Al obtener información sobre la clase de diseño de varias secuencias, los datos JSON de la respuesta incluyen un items propiedad, que es un array que contiene información sobre la disposición de los flujos en la sesión:

{
  "count": 2
  "items": [
    {
      "id": "8b732909-0a06-46a2-8ea8-074e64d43422",
      "videoType": "camera",
      "name": "",
      "layoutClassList": ["full"]
    },
    ...
  ]
}

La respuesta HTTP tendrá uno de los siguientes códigos de estado:

  • 200 — Éxito.
  • 400 — Solicitud no válida. Esta respuesta puede indicar que los datos de tu solicitud no son un JSON válido. O bien, puede indicar que no has facilitado un ID de sesión o que has facilitado un ID de flujo no válido.
  • 403 — Has introducido una clave de la API de OpenTok o un token JWT no válido.
  • 404 — La sesión existe, pero aún no se le ha añadido ninguna transmisión.
  • 408 — Has introducido un ID de flujo no válido.
  • 500 — Error del servidor de OpenTok.

Ejemplo

El siguiente ejemplo de línea de comandos recupera información sobre la clase de diseño de un flujo concreto:

api_key=12345
json_web_token="jwt_string" # replace with a JSON web token (see "Authentication")
session_id=23435236235235235235
stream_id=88ff99fc203a5bc
curl -i \
  -X GET \
  -H X-OPENTOK-AUTH:json_web_token \
  https://api.opentok.com/v2/project/$api_key/session/$session_id/stream/$stream_id
  • Establezca el valor de api_key a tu clave API de OpenTok.
  • Establezca el valor de json_web_token a un token web JSON (véase «Autenticación»).
  • Fije el session_id valor a la sesión.
  • Fije el stream_id valor al identificador del flujo.

El siguiente ejemplo de línea de comandos recupera la información sobre las clases de diseño de todas las secuencias de una sesión:

api_key=12345
json_web_token="jwt_string" # replace with a JSON web token (see "Authentication")
session_id=23435236235235235235
curl -i \
  -X GET \
  -H X-OPENTOK-AUTH:json_web_token \
  https://api.opentok.com/v2/project/$api_key/session/$session_id/stream/
  • Establezca el valor de api_key a tu clave API de OpenTok.
  • Establezca el valor de json_web_token a un token web JSON (véase «Autenticación»).
  • Fije el session_id valor a la sesión.

Forzar el silencio de una sola transmisión en el audio publicado

Puedes utilizar la API REST de OpenTok para obligar al emisor de una transmisión concreta a silenciar su audio.

POST a session/stream/mute

Envía una solicitud HTTP POST a la siguiente URL:

https://api.opentok.com/v2/project/<api_key>/session/<session_id>/stream/<stream_id>/mute

Sustituir <api_key> con la clave API del proyecto OpenTok (consulta la página del proyecto de tu Account de la Video API). Sustituye <session_id> con el ID de la sesión que contiene la transmisión. Sustituye <stream_id> con el ID de la transmisión.

Propiedades del encabezado POST

Autentifica esta llamada a la API utilizando un encabezado HTTP personalizado — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Establece este encabezado con un token JWT (véase Autenticación).

Respuesta HTTP

La respuesta HTTP tendrá uno de los siguientes códigos de estado:

  • 200 — Éxito. Los datos de la respuesta son un Detalles del proyecto Objeto.

  • 400 — Solicitud no válida.

  • 403 — Error de autenticación.

  • 404 — No encontrado. No se ha encontrado la sesión o la transmisión.

  • 500 — Error del servidor de OpenTok.

Ejemplo

SESSION_ID=2_MX40NzIwMzJ-fjE2MzM0NzE4NjY4OTfn4 STREAM_ID=eac2b8fb-b6da-40e7-9d31-d1b04edc2270 API_KEY=123456 API_SECRET=ABCDEF1234567890 JWT=jwt_token curl -v \ -X POST \ -H "X-OPENTOK-AUTH:JSON_WEB_TOKEN" \ https://api.opentok.com/v2/project/${API_KEY}/session/${SESSION_ID}/stream/${STREAM_ID}/mute

Forzar el silenciamiento del audio publicado en las transmisiones de una sesión

Puedes utilizar la API REST de OpenTok para forzar que todas las transmisiones (excepto una lista opcional de transmisiones) de una sesión silencien el audio publicado. También puedes utilizar este método para desactivar el estado de silencio forzado de una sesión (véase más abajo).

POST a session/mute

Envía una solicitud HTTP POST a la siguiente URL:

https://api.opentok.com/v2/project/<api_key>/session/<session_id>/mute

Sustituir <api_key> con la clave API del proyecto OpenTok (consulta la página del proyecto de tu Account de la Video API). Sustituye <session_id> con el ID de sesión.

Propiedades del encabezado POST

Fije el Content-Type encabezado a application/json.

Autentifica esta llamada a la API utilizando un encabezado HTTP personalizado — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Establece este encabezado con un token JWT (véase Autenticación).

Datos POST

Incluye un objeto JSON con el siguiente formato como contenido del cuerpo de la solicitud:

{
  "active": true,
  "excludedStreamIds": [
    "excludedStreamId1",
    "excludedStreamId2"
  ]
}

Los datos JSON incluyen las siguientes propiedades:

  • active (Booleano, obligatorio) — Indica si se deben silenciar las transmisiones de la sesión (true) y activar el modo de silencio de la sesión, o desactivar el modo de silencio de la sesión (false). Con la función de silencio activada (true), todas las transmisiones actuales y futuras publicadas en la sesión (a excepción de las transmisiones de la excludedStreamIds matriz) se silencian. Cuando se invoca este método con el active con el valor false, las transmisiones futuras que se publiquen en la sesión no se silenciarán (pero las transmisiones que ya estén silenciadas seguirán siendosilenciadas).

  • excludedStreamIds (Matriz de cadenas, opcional) — Los identificadores de las transmisiones que no deben silenciarse. Se trata de una propiedad opcional. Si se omite esta propiedad, todas las transmisiones de la sesión se silenciarán. Esta propiedad solo se aplica cuando el active se establece en true. Cuando el active se establece en false, se ignora.

    Los elementos del excludedStreamIds El array contiene los ID de las transmisiones (cadenas de caracteres) que deseas excluir para que no se silencien.

    Si no deseas incluir una lista de flujos excluidos, no incluyas ningún contenido en el cuerpo.

Respuesta HTTP

La respuesta HTTP tendrá uno de los siguientes códigos de estado:

  • 200 — Éxito. Los datos de la respuesta son un Detalles del proyecto Objeto.

  • 400 — Solicitud no válida. Esta respuesta puede indicar que los datos de tu solicitud no cumplen con el formato JSON válido.

  • 403 — Error de autenticación.

  • 404 — No encontrado. No se ha encontrado la sesión.

  • 500 — Error del servidor de OpenTok.

Ejemplo

Lo siguiente obliga a todas las transmisiones (excepto a una lista opcional de transmisiones) de una sesión a silenciar el audio publicado:

SESSION_ID=2_MX40NzIwMzJ-fjE2MzM0NzE4NjY4OTfn4 DATA='{"excludedStreamIds": ["eac2b8fb-b6da-40e7-9d31-d1b04edc2270", "9c18b42f-ee38-4b38-99bb-d37b2eca9741 "], "active": true}' API_KEY=123456 API_SECRET=ABCDEF1234567890 JWT=jwt_token curl -v \ -H "Content-Type: application/json" \ -X POST \ -H "X-OPENTOK-AUTH:JSON_WEB_TOKEN" \ -d "${DATA}" \ https://api.opentok.com/v2/project/${API_KEY}/session/${SESSION_ID}/mute

Para desactivar el estado de silencio de la sesión (y evitar que se silencien las transmisiones futuras), vuelve a llamar al método con el active con el valor false:

SESSION_ID=SOME_SESSION_ID DATA='{"active": false}' API_KEY=123456 API_SECRET=ABCDEF1234567890 curl -v \ -H "Content-Type: application/json" \ -X POST \ -H "X-OPENTOK-AUTH:JSON_WEB_TOKEN" \ https://api.opentok.com/v2/project/${API_KEY}/session/${SESSION_ID}/mute

Listado de conexiones en una sesión

Utiliza este método para obtener una lista de las conexiones de una sesión de OpenTok asociada a un proyecto.

Solicitud HTTP GET a la sesión/conexión

Envía una solicitud HTTP GET a la siguiente URL:

https://api.opentok.com/v2/project/<api_key>/session/<sessionId>/connection

Sustituir <api_key> con tu clave API de OpenTok. Consulta la página del proyecto en tu Account de la Video API.

Sustituir <sessionId> con el ID de la sesión que contiene las conexiones.

Puedes añadir parámetros de consulta opcionales para filtrar los resultados:

  • offset (entero, opcional): El índice, contado a partir de cero, de la primera conexión que se va a devolver. El valor por defecto es 0 (la conexión más antigua).
  • count (entero, opcional): El número máximo de conexiones que se van a devolver. El valor por defecto es 50; el máximo es 1000.

Por ejemplo, la siguiente llamada recupera 20 conexiones a partir de la posición 400:

https://api.opentok.com/v2/project/<api_key>/session/<sessionId>/connection?offset=400&count=20

Propiedades del encabezado GET

Las llamadas a la API deben autenticarse mediante un encabezado HTTP personalizado — X-OPENTOK-AUTH — junto con un token web JSON (JWT). Véase Autenticación.

Respuesta

Los datos sin procesar de la respuesta HTTP, con código de estado 200, son un mensaje codificado en JSON con el siguiente formato:

{
  "count": 3,
  "projectId" : "<api_key>",
  "sessionId" : "<sessionId>",
  "items": [{
      "connectionId": "<connection_id_1>",
      "createdAt": 1747655658197,
      "connectionState": "Connected"
    },{
      "connectionId": "<connection_id_2>",
      "createdAt": 1747655658227,
      "connectionState": "Connected"
    },{
      "connectionId": "<connection_id_3>",
      "createdAt": 1747655658258,
      "connectionState": "Connecting"
    }
  ]
}

El objeto JSON incluye las siguientes propiedades:

  • count — El número total de conexiones en la sesión.
  • projectId — Tu clave de API de OpenTok.
  • sessionId — El identificador de sesión.
  • elementos: una matriz de objetos que definen cada conexión recuperada. Las conexiones se enumeran de la más antigua a la más reciente en el conjunto de resultados.

Cada objeto del array «items» representa una conexión y tiene las siguientes propiedades:

  • connectionId — El identificador de la conexión.
  • connectionState — El estado de la conexión:
    • «Conectando»: la conexión aún se encuentra en fase de creación y no está completamente establecida.
    • «Conectado»: la conexión está totalmente establecida y conectada a la sesión.
  • createdAt — La marca de tiempo correspondiente al momento en que se creó la conexión, expresada en milisegundos desde la época Unix (1 de enero de 1970, 00:00:00 UTC).

La respuesta HTTP tendrá uno de los siguientes códigos de estado:

  • 200 — Éxito. Los datos de la respuesta contienen la lista de conexiones de una sesión de OpenTok.
  • 400 — Solicitud no válida. Esta respuesta puede indicar que algún parámetro de tu consulta no es válido.
  • 403 — Error de autenticación.
  • 404 — No se ha encontrado la sesión.
  • 500 — Error del servidor de OpenTok.

Ejemplo

En los siguientes ejemplos:

  • Establece el valor de API_KEY con tu clave API de OpenTok.
  • Establece el valor de JWT en un token web JSON válido (véase Autenticación).
  • Establece el valor de SESSION_ID con tu ID de sesión de OpenTok.

El siguiente ejemplo de línea de comandos recupera las primeras 50 conexiones de la sesión:

API_KEY=123456 SESSION_ID=SOMESESSIONID JWT=jwt_token # replace with a JSON web token (see "Authentication") curl \ -i \ -X GET \ -H "X-OPENTOK-AUTH:${JWT}" \ https://api.opentok.com/v2/project/${API_KEY}/session/${SESSION_ID}/connection

El siguiente ejemplo de línea de comandos recupera la primera conexión creada en la sesión:

API_KEY=123456 SESSION_ID=SOMESESSIONID JWT=jwt_token # replace with a JSON web token (see "Authentication") curl \ -i \ -X GET \ -H "X-OPENTOK-AUTH:${JWT}" \ https://api.opentok.com/v2/project/${API_KEY}/session/${SESSION_ID}/connection?offset=0&count=1

El siguiente ejemplo de línea de comandos recupera dos conexiones, empezando por la quinta conexión creada en la sesión:

API_KEY=123456 SESSION_ID=SOMESESSIONID JWT=jwt_token # replace with a JSON web token (see "Authentication") curl \ -i \ -X GET \ -H "X-OPENTOK-AUTH:${JWT}" \ https://api.opentok.com/v2/project/${API_KEY}/session/${SESSION_ID}/connection?offset=5&count=2

En el siguiente ejemplo no se recuperan conexiones, ya que el desplazamiento es mayor que el número de conexiones de la sesión:

API_KEY=123456 SESSION_ID=SOMESESSIONID JWT=jwt_token # replace with a JSON web token (see "Authentication") curl \ -i \ -X GET \ -H "X-OPENTOK-AUTH:${JWT}" \ https://api.opentok.com/v2/project/${API_KEY}/session/${SESSION_ID}/connection?offset=500&count=100

Migración de una sesión

Utiliza este método para migrar una sesión a otro servidor cuando sea necesario. La migración solo es posible si no hay ninguna migración en curso para esa sesión y si la sesión no se ha creado ni migrado recientemente. (Consulta el Rotación de servidores y migración de sesiones (Guía para desarrolladores.)

Nota: Cuando se inicie la migración, todas las conexiones que cuenten con la capacidad «migrate» se migrarán al nuevo servidor. Las conexiones que no cuenten con la capacidad «migrate» se cerrarán como parte del proceso de migración. (Véase Permitir la migración de sesiones en los clientes.)

URL del recurso:

https://api.opentok.com/v2/project/<api_key>/session/<sessionId>/migrate

Sustituir <api_key> con la clave API del proyecto OpenTok (consulta la página del proyecto de tu Account de la Video API). Sustituye <session_id> con el ID de la sesión que se va a migrar a otro servidor.

Verbo de recurso:

PUBLICAR

Propiedades del encabezado POST

Fije el Content-Type encabezado a application/json.

Autentifica esta llamada a la API utilizando un encabezado HTTP personalizado — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Establece este encabezado con un token JWT (véase Autenticación).

Respuesta HTTP

En algunas respuestas de error, además del código de respuesta HTTP, el cuerpo de la respuesta incluye un code campo para indicar el motivo concreto del error. La respuesta HTTP tendrá uno de los siguientes códigos de estado:

  • 202 — Aceptada. La solicitud es válida y la sesión se migrará.

  • 400 — Solicitud no válida. Esta respuesta puede indicar que a la solicitud le falta alguna información.

  • 403 — Error de autenticación. Debido a un token no autorizado o no válido

  • 404 — No encontrado. No se ha encontrado la sesión.

  • 409 — Conflicto. La sesión no se puede migrar en este momento. Esto puede deberse a una de las siguientes razones:

    • código 15214: Ya se está llevando a cabo una migración para la sesión.
    • código 15215: La sesión se ha creado o migrado recientemente.

  • 500 — Error interno del servidor de OpenTok.

Solicitud de muestra

SESSION_ID=SOMESESSIONID API_KEY=123456 JWT=json_web_token curl -v \ -H "Content-Type: application/json" \ -X POST \ -H "X-OPENTOK-AUTH:${JWT}" \ https://api.opentok.com/v2/project/${API_KEY}/session/${SESSION_ID}/migrate
  • Establezca el valor de API_KEY a tu clave API de OpenTok.
  • Establezca el valor de JWT a un token web JSON (véase «Autenticación»).
  • Fije el SESSION_ID valor correspondiente al ID de la sesión que se va a migrar.

Ejemplo de respuesta

Respuesta de error de autenticación:

{
  "code":15215,
  "message":"Migration is not allowed shortly after session creation or a previous migration",
  "description":"Migration is not allowed shortly after session creation or a previous migration"
}

Iniciar una grabación de archivo

Para iniciar la grabación de un archivo de una sesión de OpenTok, envía una solicitud HTTP POST.

Para iniciar correctamente la grabación de un archivo, debe haber al menos un cliente conectado a la sesión.

Solo se pueden grabar archivos de sesiones que utilicen el OpenTok Media Router (con el modo multimedia configurado en «routed»); no se pueden archivar sesiones cuyo modo multimedia esté configurado en «relayed». (Véase El OpenTok Media Router y los modos multimedia.)

Para más información, consulte el Guía para desarrolladores sobre el archivado de OpenTok.

Solicitud HTTP POST al archivo

Envía una solicitud HTTP POST a la siguiente URL:

https://api.opentok.com/v2/project/<api_key>/archive

Sustituir <api_key> con tu clave API de OpenTok. Consulta la página del proyecto de tu Account de la Video API.

Nota: Anteriormente, esta URL REST utilizaba /partner (que ahora está en desuso) en lugar de /project.

Propiedades del encabezado POST

Las llamadas a la API deben autenticarse mediante un encabezado HTTP personalizado — X-OPENTOK-AUTH — junto con un token web JSON (JWT). Véase Autenticación.

Establece el encabezado «Content-type» en «application/json»:

Content-Type:application/json

Datos POST

Incluye un objeto JSON con el siguiente formato como datos POST:

{
    "sessionId" : "session_id",
    "hasAudio" : true,
    "hasVideo" : true,
    "layout" : {
      "type": "custom",
      "stylesheet": "the layout stylesheet (only used with type == custom)",
      "screenshareType": "the layout type to use when there is a screen-sharing stream (optional)"
    },
    "name" : "archive_name",
    "outputMode" : "composed",
    "resolution" : "640x480",
    "streamMode" : "auto"
}

El objeto JSON incluye las siguientes propiedades:

  • sessionId (Cadena) — (Obligatorio) El ID de la sesión de OpenTok que deseas empezar a archivar
  • hasAudio (Booleano) — (Opcional) Indica si el archivo grabará audio (verdadero, valor por defecto) o no (falso). Si se establecen ambos hasAudio y hasVideo Si se establece en «false», la llamada a este método da lugar a un error.
  • hasVideo (Booleano) — (Opcional) Indica si el archivo grabará vídeo (verdadero, valor por defecto) o no (falso). Si se configuran ambos hasAudio y hasVideo Si se establece en «false», la llamada a este método da lugar a un error.
  • layout (Objeto) — Opcional. Indícalo para asignar el tipo de estructura inicial del archivo. Esto solo se aplica a archivos organizados. Este objeto tiene tres propiedades: type, stylesheety screenshareType, que son cadenas de caracteres. Los valores válidos para el layout Las propiedades son "bestFit" (ajuste óptimo), "custom" (personalizado), "horizontalPresentation" (presentación horizontal), "pip" (imagen en imagen) y "verticalPresentation" (presentación vertical)). Si se especifica un "custom" tipo de diseño, establezca el stylesheet propiedad del layout objeto a la hoja de estilo. (Para otros tipos de diseño, no establezcas un stylesheet propiedad.) Establece el screenshareType propiedad del tipo de diseño que se utilizará cuando haya una transmisión compartida de pantalla en la sesión. (Esta propiedad es opcional.) Ten en cuenta que si configuras la screenshareType propiedad, debes configurar la type a "bestFit" y dejar la propiedad stylesheet Propiedad sin definir. Si no se especifica un tipo de diseño inicial, el archivo utiliza el tipo de diseño más adecuado. Para obtener más información, consulte Personalización del diseño de vídeo para los archivos compuestos.
  • maxBitrate (opcional) — La tasa de bits máxima de vídeo para el archivo, en bits por segundo. El valor mínimo es 100 000 y el máximo, 6 000 000. Esta opción solo es válida para archivos compuestos. Establece la tasa de bits máxima de vídeo para controlar el tamaño del archivo compuesto. Esta tasa de bits máxima se aplica únicamente a la tasa de bits de vídeo. Si el archivo de salida contiene audio, esos bits quedarán excluidos del límite. Cuando establezcas la maxBitrate propiedad, el archivo utiliza una velocidad de bits constante. No es posible configurar a la vez la maxBitrate y la propiedad quantizationParameter propiedades: si lo haces, se producirá un error.
  • multiArchiveTag (Cadena) — (Opcional) Configura esta opción para permitir la grabación simultánea de varios archivos de la misma sesión. Asigna una cadena única a cada archivo simultáneo de una sesión en curso. También debes configurar esta opción cuando inicies manualmente un archivo en una sesión que esté archivado automáticamente. Si no se especifica un multiArchiveTag, solo se puede grabar un archivo a la vez en una sesión determinada. Véase Archivos simultáneos.
  • name (Cadena) — (Opcional) El nombre del archivo (para tu propia identificación). La longitud máxima del nombre del archivo es de 255 caracteres.
  • quantizationParameter (Número) — (Opcional) El parámetro de cuantificación (QP) para un archivo compuesto, que ajusta el equilibrio entre la calidad del vídeo y el tamaño del archivo. Al establecer el parámetro de cuantificación, el archivo utiliza una tasa de bits variable y una cuantificación de compresión constante, lo que da como resultado un nivel de calidad uniforme en los cambios de escena. Los valores válidos oscilan entre 15 y 40; los valores comprendidos entre 20 y 30 producen resultados razonables sin una gran diferencia perceptible en la calidad. Los valores de QP más bajos producen una cuantización de compresión de vídeo más fina, lo que se traduce en una mayor calidad de vídeo (conservando más detalles) y un tamaño de archivo mayor. Los valores de QP más altos producen una cuantización de compresión de vídeo más gruesa, lo que reduce la calidad de vídeo y da lugar a un tamaño de archivo menor. Solo se puede establecer un parámetro de cuantización para un archivo compuesto; al establecer quantizationParameter Si se intenta archivar una transmisión concreta, se produce un error. No es posible configurar tanto el quantizationParameter y la propiedad maxBitrate ya que, de lo contrario, se produce un error.
  • resolution (Cadena) — (Opcional) La resolución del archivo, que puede ser: "640x480" (paisaje SD, el valor predeterminado), "1280x720" (HD horizontal), "1920x1080" (FHD en horizontal), "480x640" (retrato en SD), "720x1280" (vertical en alta definición), o "1080x1920" (FHD vertical). Es posible que te interese utilizar una relación de aspecto vertical para los archivos que incluyan secuencias de vídeo procedentes de dispositivos móviles (que suelen utilizar la relación de aspecto vertical). Esta propiedad solo se aplica a los archivos compuestos. Si configuras esta propiedad y estableces la outputMode propiedad a "individual", la llamada al método REST da lugar a un error.
  • streamMode (Cadena) — (Opcional) Indica si las secuencias incluidas en el archivo se seleccionan automáticamente ("auto", que es el valor predeterminado) o manualmente ("manual"). Cuando las transmisiones se seleccionan automáticamente ("auto"), todas las transmisiones de la sesión pueden incluirse en el archivo. Cuando las transmisiones se seleccionan manualmente ("manual"), se especifican los flujos que se van a incluir mediante llamadas a este método REST. Puedes especificar si en el archivo se incluye el audio, el vídeo o ambos de una secuencia. En los archivos compuestos, tanto en modo automático como en modo manual, el generador de archivos incluye las secuencias en función de normas de priorización de flujos.

Los datos sin procesar de la respuesta HTTP, con código de estado 200, son un mensaje codificado en JSON con el siguiente formato:

{
  "createdAt" : 1384221730555,
  "duration" : 0,
  "hasAudio" : true,
  "hasVideo" : true,
  "id" : "b40ef09b-3811-4726-b508-e41a0f96c68f",
  "name" : "The archive name you supplied",
  "outputMode" : "composed",
  "projectId" : 234567,
  "reason" : "",
  "resolution" : "640x480",
  "sessionId" : "flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN",
  "size" : 0,
  "status" : "started",
  "streamMode" : "auto",
  "url" : null
}

El objeto JSON incluye las siguientes propiedades:

  • createdAt — La marca de tiempo correspondiente al momento en que el archivo comenzó a grabarse, expresada en milisegundos desde la época Unix (1 de enero de 1970, 00:00:00 UTC).
  • hasAudio — Si el archivo grabará audio (verdadero) o no (falso).
  • hasVideo — Si el archivo grabará vídeo (verdadero) o no (falso).
  • id — El identificador único del archivo. Guarda este valor para utilizarlo más adelante (por ejemplo, para detener la grabación).
  • multiArchiveTag — La etiqueta única para los archivos simultáneos (si se ha establecido alguna).
  • name — El nombre del archivo que has facilitado (esto es opcional).
  • outputMode — O bien "composed" o "individual". Véase Archivos de una sola fuente y archivos combinados.
  • projectId — Tu clave de API de OpenTok.
  • resolution — La resolución del archivo (ya sea «640x480», «1280x720», «1920x1080», «480x640», «720x1280» o «1080x1920»). Esta propiedad solo se establece para los archivos compuestos.
  • sessionId — El ID de la sesión de OpenTok que se está archivando.
  • status - Se establece en "started".
  • streamMode — Si las transmisiones incluidas en el archivo se seleccionan automáticamente ("auto", que es el valor predeterminado) o manualmente ("manual").
  • streams — Una matriz de objetos que corresponden a las secuencias que se están archivando en ese momento. Solo se establece para un archivo con el status ajustado a "started" y el streamMode ajustado a "manual". Cada objeto de la matriz incluye las siguientes propiedades:
    • streamId — El identificador de la secuencia incluida en el archivo.
    • hasAudio — Si el audio de la retransmisión se incluye en el archivo.
    • hasVideo — Si el vídeo de la retransmisión está incluido en el archivo.

La respuesta HTTP presenta un código de estado 400 en los siguientes casos:

  • No has introducido ningún ID de sesión o has introducido un ID de sesión no válido.
  • No hay ningún cliente conectado activamente a la sesión de OpenTok.
  • Has especificado un valor no válido resolution valor.
  • El outputMode se establece en "individual" y tú configuras el resolution propiedad y (que no es compatible con los archivos de transmisiones individuales).
  • Has especificado un valor no válido maxBitrate valor o si especificas un maxBitrate valor correspondiente a un archivo de transmisión concreto. (maxBitrate (solo es compatible con archivos compuestos.)
  • Has especificado un valor no válido quantizationParameter valor o si especificas un quantizationParameter valor correspondiente a un archivo de transmisión concreto. (quantizationParameter (solo es compatible con archivos compuestos.)
  • Se debe especificar tanto un maxBitrate y un quantizationParameter propiedad.

La respuesta HTTP tendrá un código de estado 403 si se introduce una clave de la API de OpenTok o un token JWT no válido.

La respuesta HTTP tiene un código de estado 404 si la sesión no existe o si, aunque exista, no hay ningún cliente conectado a ella.

La respuesta HTTP tendrá un código de estado 409 si intentas iniciar una grabación de una sesión que no utilice el OpenTok Media Router. O si intentas iniciar una grabación de una sesión que ya se está grabando sin haber configurado el multiArchiveTag opción. O si intentas iniciar un archivo simultáneo para una sesión sin establecer un multiArchiveTag valor.

La respuesta HTTP presenta un código de estado 500 debido a un error del servidor de OpenTok.

Ejemplo

El siguiente ejemplo de línea de comandos inicia la grabación de un archivo de una sesión de OpenTok:

api_key=12345
json_web_token="jwt_string" # replace with a JSON web token (see "Authentication")
session_id=2_MX40NzIwMzJ-flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN-MC45NDQ2MzE2NH4
name="Foo"
data='{"sessionId" : "'$session_id'", "name" : "'$name'"}'
curl \
     -i \
     -H "Content-Type: application/json" \
     -X POST \
     -d $data \
     -H "X-OPENTOK-AUTH:$json_web_token" \
     https://api.opentok.com/v2/project/$api_key/archive
  • Establezca el valor de api_key a tu clave API de OpenTok.
  • Establezca el valor de json_web_token a un token web JSON (véase Autenticación).
  • Fije el session_id introduce el ID de la sesión de OpenTok que deseas archivar.
  • Fije el name añade un valor al nombre del archivo (esto es opcional).

Detener una grabación de archivo

Para detener la grabación de un archivo, envía una solicitud HTTP POST.

Los archivos dejan de grabarse tras 4 horas (14 400 segundos), o 60 segundos después de que el último cliente se desconecte de la sesión, o 60 minutos después de que el último cliente deje de publicar. Sin embargo, archivos automáticos Continúa grabando en varios archivos consecutivos de hasta 4 horas de duración cada uno. Para obtener más información, consulta Duración del archivo

Al llamar a este método para archivos automáticos no tiene ningún efecto. Los archivos automáticos siguen grabando en varios archivos consecutivos de hasta 4 horas (14 400 segundos) de duración cada uno, hasta 60 segundos después de que el último cliente se desconecte de la sesión, o hasta 60 minutos después de que el último cliente deje de publicar una transmisión en la sesión.

Solicitud HTTP POST al archivo

Envía una solicitud HTTP POST a la siguiente URL:

https://api.opentok.com/v2/project/<api_key>/archive/<archive_id>/stop

Sustituir <api_key> con tu clave API de OpenTok. Consulta la página de tu proyecto en tu Account de la Video API.

Sustituir <archive_id> con el ID del archivo. Puedes obtener el ID del archivo a partir de la respuesta a la llamada a la API a empezar a grabar el archivo.

Nota: Anteriormente, esta URL REST utilizaba /partner (que ahora está en desuso) en lugar de /project.

Propiedades del encabezado POST

Las llamadas a la API deben autenticarse mediante un encabezado HTTP personalizado — X-OPENTOK-AUTH — junto con un token web JSON (JWT). Véase Autenticación.

Respuesta

Los datos sin procesar de la respuesta HTTP, con código de estado 200, son un mensaje codificado en JSON con el siguiente formato:

{
  "createdAt" : 1384221730555,
  "duration" : 60,
  "hasAudio" : true,
  "hasVideo" : true,
  "id" : "b40ef09b-3811-4726-b508-e41a0f96c68f",
  "multiArchiveTag": "archive-1234b"
  "name" : "The archive name you supplied",
  "outputMode": "composed"
  "projectId" : 234567,
  "reason" : "",
  "resolution" : "640x480",
  "sessionId" : "flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN",
  "size" : 0,
  "status" : "stopped",
  "streamMode" : "auto",
  "streams" : "[]",
  "url" : null
}

El objeto JSON incluye las siguientes propiedades:

  • createdAt — La marca de tiempo correspondiente al momento en que el archivo comenzó a grabarse, expresada en milisegundos desde la época Unix (1 de enero de 1970, 00:00:00 UTC).
  • hasAudio — Si el archivo grabará audio (verdadero) o no (falso).
  • hasVideo — Si el archivo grabará vídeo (verdadero) o no (falso).
  • id — El identificador único del archivo.
  • multiArchiveTag — La etiqueta única para los archivos simultáneos (si se ha establecido alguna).
  • outputMode — O bien "composed" o "individual". Véase Archivos de una sola fuente y archivos combinados.
  • projectId — Tu clave de API de OpenTok.
  • resolution — La resolución del archivo (ya sea «640x480», «1280x720», «1920x1080», «480x640», «720x1280» o «1080x1920»). Esta propiedad solo se establece para los archivos compuestos.
  • sessionId — El ID de la sesión de OpenTok que se ha archivado.
  • name — El nombre del archivo que has proporcionado (esto es opcional)
  • size — Cuando se detiene el archivo (y aún no se ha generado), el tamaño se establece en 0.
  • status - Se establece en "stopped".
  • streamMode — Si las transmisiones incluidas en el archivo se seleccionan automáticamente ("auto", que es el valor predeterminado) o manualmente ("manual").
  • streams — Una matriz de objetos que corresponden a las secuencias que se están archivando en ese momento. Solo se establece para un archivo con el status ajustado a "started" y el streamMode ajustado a "manual". Cada objeto de la matriz incluye las siguientes propiedades:
    • streamId — El identificador de la secuencia incluida en el archivo.
    • hasAudio — Si el audio de la retransmisión se incluye en el archivo.
    • hasVideo — Si el vídeo de la retransmisión está incluido en el archivo.

La respuesta HTTP tendrá un código de estado 400 si no se introduce un ID de sesión o si se introduce un ID de sesión no válido.

La respuesta HTTP tendrá un código de estado 403 si se introduce una clave de la API de OpenTok o un token JWT no válido.

La respuesta HTTP tendrá un código de estado 404 si se introduce un ID de archivo no válido.

La respuesta HTTP tendrá un código de estado 409 si intentas detener una grabación que no se está realizando.

La respuesta HTTP presenta un código de estado 500 debido a un error del servidor de OpenTok.

Ejemplo

El siguiente ejemplo de línea de comandos detiene la grabación de un archivo de una sesión de OpenTok:

api_key=123456
json_web_token="jwt_string" # replace with a JSON web token (see "Authentication")
id=b40ef09b-3811-4726-b508-e41a0f96c68f
curl \
     -i \
     -X POST \
     -H "X-OPENTOK-AUTH:$json_web_token" \
     https://api.opentok.com/v2/project/$api_key/archive/$id/stop
  • Establezca el valor de api_key a tu clave API de OpenTok.
  • Establezca el valor de json_web_token a un token web JSON (véase Autenticación).
  • Fije el id valor al ID del archivo. Puedes obtener el ID del archivo a partir de la respuesta a la llamada a la API a empezar a grabar el archivo.

Archivos de anuncios

Para obtener una lista de los archivos asociados a tu clave API, tanto los completados como los en curso, envía una solicitud HTTP GET.

Nota: Los registros archivados están disponibles durante un máximo de 12 meses.

Solicitud HTTP GET al archivo

Envía una solicitud HTTP GET a la siguiente URL:

https://api.opentok.com/v2/project/<api_key>/archive

Sustituir <api_key> con tu clave API de OpenTok. Consulta la página del proyecto en tu Account de la Video API.

Nota: Anteriormente, esta URL REST utilizaba /partner (que ahora está en desuso) en lugar de /project.

Puedes añadir parámetros de consulta para filtrar los resultados (son opcionales):

  • Establecer un offset Parámetros de consulta para especificar el desplazamiento en el índice del primer archivo. 0 es el desplazamiento del archivo iniciado más recientemente (excluyendo los archivos eliminados). 1 es el desplazamiento del archivo que se inició antes que el más reciente. El valor por defecto es 0.

  • Establecer un count Parámetro de consulta para limitar el número de archivos que se van a devolver. El número predeterminado de archivos devueltos es 50 (o menos, si hay menos de 50 archivos). El número máximo de archivos que devolverá la llamada es 1000.

  • Establecer un sessionId Parámetro de consulta para mostrar los archivos correspondientes a un ID de sesión específico. (Esto resulta útil a la hora de mostrar varios archivos para un archivada automáticamente sesión.)

Por ejemplo, la siguiente llamada especifica un count y offset valores:

https://api.opentok.com/v2/project/<api_key>/archive?offset=400&count=20

La siguiente llamada especifica un (falso) sessionId valor:

https://api.opentok.com/v2/project/<api_key>/archive?sessionId=2_MX4xMDB-flR1-QxNzIxNX4

Los archivos eliminados no se incluyen en los resultados de esta llamada a la API.

Sustituir <api_key> con tu clave API de OpenTok. Consulta la página del proyecto en tu Account de la Video API.

Propiedades del encabezado GET

Las llamadas a la API deben autenticarse mediante un encabezado HTTP personalizado — X-OPENTOK-AUTH — junto con un token web JSON (JWT). Véase Autenticación.

Respuesta

Los datos sin procesar de la respuesta HTTP, con código de estado 200, son un mensaje codificado en JSON con el siguiente formato:

{
  "count" : 2,
  "items" : [ {
    "createdAt" : 1384221730000,
    "duration" : 5049,
    "hasAudio" : true,
    "hasVideo" : true,
    "id" : "b40ef09b-3811-4726-b508-e41a0f96c68f",
    "multiArchiveTag": "archive-1234a",
    "name" : "Foo",
    "outputMode" : "composed",
    "projectId" : 123456,
    "reason" : "",
    "resolution" : "640x480",
    "sessionId" : "2_MX40NzIwMzJ-flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN-MC45NDQ2MzE2NH4",
    "size" : 247748791,
    "status" : "available",
    "streamMode" : "manual",
    "streams" : [],
    "url" : "https://example.com/archive.mp4"
  }, {
    "createdAt" : 1384221380000,
    "duration" : 328,
    "hasAudio" : true,
    "hasVideo" : true,
    "id" : "b40ef09b-3811-4726-b508-e41a0f96c68f",
    "multiArchiveTag": "archive-1234b",
    "name" : "Foo",
    "outputMode" : "composed",
    "projectId" : 123456,
    "reason" : "",
    "resolution" : "640x480",
    "sessionId" : "2_MX40NzIwMzJ-flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN-MC45NDQ2MzE2NH4",
    "size" : 18023312,
    "status" : "available",
    "streamMode" : "auto",
    "streams" : [],
    "url" : "https://example.com/archive.mp4"
  } ]

El objeto JSON incluye las siguientes propiedades:

  • count — El número total de archivos asociados a la clave API.
  • items — Una matriz de objetos que definen cada archivo recuperado. Los archivos se enumeran de más reciente a más antiguo en el conjunto de resultados.

Cada objeto del archivo (elemento) tiene las siguientes propiedades:

  • createdAt — La marca de tiempo correspondiente al momento en que el archivo comenzó a grabarse, expresada en milisegundos desde la época Unix (1 de enero de 1970, 00:00:00 UTC).
  • duration — La duración del archivo en segundos. En el caso de los archivos que se están grabando (con la propiedad «status» establecida en «started»), este valor se establece en 0.
  • hasAudio — Si el archivo grabará audio (verdadero) o no (falso).
  • hasVideo — Si el archivo grabará vídeo (verdadero) o no (falso).
  • id — El identificador único del archivo.
  • multiArchiveTag — La etiqueta única para los archivos simultáneos (si se ha establecido alguna).
  • name — El nombre del archivo que has proporcionado (esto es opcional)
  • outputMode — O bien "composed" o "individual". Véase Archivos de una sola fuente y archivos combinados.
  • projectId — Tu clave de API de OpenTok.
  • reason — Para los archivos con el estado "stopped"puede establecerse en "maximum duration exceeded", "maximum idle time exceeded", "session ended", "user initiated". Para los archivos con el estado "failed"puede establecerse en "failure".
  • sessionId — El ID de la sesión de OpenTok que se ha archivado.
  • status — El estado del archivo:

    • "available" — El archivo se puede descargar desde la nube de OpenTok.

    • "expired" — El archivo ya no está disponible para su descarga desde la nube de OpenTok.

    • "failed" — Se ha producido un error al guardar el archivo.

    • "paused" — Cuando se pausa un archivo, no se graba nada. El archivo se pausa si se da alguna de las siguientes condiciones:

      • Ningún cliente está publicando flujos en la sesión. En este caso, el tiempo de espera es de 60 minutos; transcurrido ese tiempo, el archivo se detiene y el estado del archivo cambia a "stopped".
      • Todos los clientes se desconectan de la sesión. Tras 60 segundos, el archivado se detiene y el estado del archivado cambia a "stopped".

      Si un cliente reanuda la publicación mientras el archivo se encuentra en estado «en pausa», la grabación del archivo se reanuda y el estado vuelve a ser "started".

    • "started" — El archivo se ha puesto en marcha y se está grabando.

    • "stopped" — El archivo dejó de grabar.

    • "uploaded" — El archivo se puede descargar desde el depósito de S3 que has especificado en tu Account de la Video API.

  • streamMode — Si las transmisiones incluidas en el archivo se seleccionan automáticamente ("auto", que es el valor predeterminado) o manualmente ("manual").
  • resolution — La resolución del archivo (ya sea «640x480», «1280x720», «1920x1080», «480x640», «720x1280» o «1080x1920»). Esta propiedad solo se establece para los archivos compuestos.
  • size — El tamaño del archivo comprimido. En el caso de los archivos comprimidos que aún no se han generado, este valor se establece en 0.
  • streamMode — Si todas las transmisiones están incluidas en el archivo ("auto") o seleccionas las transmisiones que quieres incluir en el archivo ("manual"). Véase Selección de flujos que se incluirán en un archivo.
  • streams — Una matriz de objetos que corresponden a las secuencias que se están archivando en ese momento. Solo se establece para un archivo con el status ajustado a "started" y el streamMode ajustado a "manual". Cada objeto de la matriz incluye las siguientes propiedades:
    • streamId — El identificador de la secuencia incluida en el archivo.
    • hasAudio — Si el audio de la retransmisión se incluye en el archivo.
    • hasVideo — Si el vídeo de la retransmisión está incluido en el archivo.
  • url — La URL de descarga del archivo comprimido disponible. Solo se establece para un archivo comprimido cuyo estado sea "available"; para otros archivos, (incluidos los archivos con el estado "uploaded") esta propiedad se establece en «null». La URL de descarga está ofuscada y el archivo solo está disponible en esa URL durante 10 minutos. Para generar una nueva URL, utiliza la API REST para recuperación de información de archivo o archivos de listados.

La respuesta HTTP tendrá un código de estado 403 si se introduce una clave de la API de OpenTok o un token JWT no válido.

La respuesta HTTP presenta un código de estado 500 debido a un error del servidor de OpenTok.

Ejemplo

El siguiente ejemplo de línea de comandos recupera información sobre todos los archivos:

api_key=12345
json_web_token="jwt_string" # replace with a JSON web token (see "Authentication")
curl \
    -i \
    -X GET \
    -H "X-OPENTOK-AUTH:$json_web_token" \
    https://api.opentok.com/v2/project/$api_key/archive
  • Establezca el valor de api_key a tu clave API de OpenTok.
  • Establezca el valor de json_web_token a un token web JSON (véase Autenticación).

Recuperación de información de archivo

Para obtener información sobre un archivo concreto, envía una solicitud HTTP GET.

Nota: Los registros archivados están disponibles durante un máximo de 12 meses.

También puedes consultar información sobre varios archivos. Consulta Archivos de anuncios.

Solicitud HTTP GET al archivo

Envía una solicitud HTTP GET a la siguiente URL:

https://api.opentok.com/v2/project/<api_key>/archive/<archive_id>
  • Sustituir <api_key> con tu clave API de OpenTok. Consulta la página del proyecto de tu Account de la Video API.
  • Sustituir <archive_id con el ID del archivo.

Nota: Anteriormente, esta URL REST utilizaba /partner (que ahora está en desuso) en lugar de /project.

Propiedades del encabezado GET

Las llamadas a la API deben autenticarse mediante un encabezado HTTP personalizado — X-OPENTOK-AUTH — junto con un token web JSON (JWT). Véase Autenticación.

Respuesta

Los datos sin procesar de la respuesta HTTP, con código de estado 200, son un mensaje codificado en JSON con el siguiente formato:

{
  "createdAt" : 1384221730000,
  "duration" : 5049,
  "hasAudio" : true,
  "hasVideo" : true,
  "id" : "b40ef09b-3811-4726-b508-e41a0f96c68f",
  "multiArchiveTag": "archive-1234b",
  "name" : "Foo",
  "outputMode" : "composed",
  "projectId" : 123456,
  "reason" : "",
  "resolution" : "640x480",
  "sessionId" : "2_MX40NzIwMzJ-flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN-MC45NDQ2MzE2NH4",
  "size" : 247748791,
  "status" : "available",
  "streamMode" : "auto",
  "streams" : []
  "url" : "https://example.com/archive.mp4"
}

El objeto JSON incluye las siguientes propiedades:

  • createdAt — La marca de tiempo correspondiente al momento en que el archivo comenzó a grabarse, expresada en milisegundos desde la época Unix (1 de enero de 1970, 00:00:00 UTC).
  • duration — La duración del archivo en segundos. En el caso de los archivos que se están grabando (con la propiedad «status» establecida en «started»), este valor se establece en 0.
  • hasAudio — Si el archivo grabará audio (verdadero) o no (falso).
  • hasVideo — Si el archivo grabará vídeo (verdadero) o no (falso).
  • id — El identificador único del archivo.
  • multiArchiveTag — La etiqueta única para los archivos simultáneos (si se ha establecido alguna).
  • name — El nombre del archivo que has proporcionado (esto es opcional)
  • outputMode — O bien "composed" o "individual". Véase Archivos de una sola fuente y archivos combinados.
  • projectId — Tu clave de API de OpenTok.
  • reason — Para los archivos con el estado "stopped"puede establecerse en "maximum duration exceeded", "maximum idle time exceeded", "session ended", "user initiated". Para los archivos con el estado "failed"puede establecerse en "failure".
  • resolution — La resolución del archivo (ya sea «640x480», «1280x720», «1920x1080», «480x640», «720x1280» o «1080x1920»). Esta propiedad solo se establece para los archivos compuestos.
  • sessionId — El ID de la sesión de OpenTok que se ha archivado.
  • status — El estado del archivo:

    • "available" — El archivo se puede descargar desde la nube de OpenTok.

    • "deleted" — Se ha eliminado el archivo.

    • "expired" — El archivo ya no está disponible para su descarga desde la nube de OpenTok.

    • "failed" — Se ha producido un error al guardar el archivo.

    • "paused" — Cuando se pausa un archivo, no se graba nada. El archivo se pausa si se da alguna de las siguientes condiciones:

      • Ningún cliente está publicando flujos en la sesión. En este caso, el tiempo de espera es de 60 minutos; transcurrido ese tiempo, el archivo se detiene y el estado del archivo cambia a "stopped".
      • Todos los clientes se desconectan de la sesión. Tras 60 segundos, el archivado se detiene y el estado del archivado cambia a "stopped".

      Si un cliente reanuda la publicación mientras el archivo se encuentra en el "paused" estado, la grabación de archivo se reanuda y el estado vuelve a ser "started".

    • "started" — El archivo se ha puesto en marcha y se está grabando.

    • "stopped" — El archivo dejó de grabar.

    • "uploaded" — El archivo se puede descargar desde el depósito de S3 que has especificado en tu Account de la Video API.

  • size — El tamaño del archivo comprimido. En el caso de los archivos comprimidos que aún no se han generado, este valor se establece en 0.
  • streamMode — Si todas las transmisiones están incluidas en el archivo ("auto") o seleccionas las transmisiones que quieres incluir en el archivo ("manual"). Véase Selección de flujos que se incluirán en un archivo.
  • streams — Una matriz de objetos que corresponden a las secuencias que se están archivando en ese momento. Solo se establece para un archivo cuyo estado sea "started" y el streamMode ajustado a "manual". Cada objeto de la matriz incluye las siguientes propiedades:
    • streamId — El identificador de la secuencia incluida en el archivo.
    • hasAudio — Si el audio de la retransmisión se incluye en el archivo.
    • hasVideo — Si el vídeo de la retransmisión está incluido en el archivo.
  • url — La URL de descarga del archivo comprimido disponible. Solo se establece para un archivo comprimido cuyo estado sea "available"; para otros archivos, (incluidos los archivos con el estado "uploaded") esta propiedad se establece en «null». La URL de descarga está ofuscada y el archivo solo está disponible en esa URL durante 10 minutos. Para generar una nueva URL, utiliza la API REST para recuperación de información de archivo o archivos de listados.

La respuesta HTTP tendrá un código de estado 400 si no se introduce un ID de sesión o si se introduce un ID de archivo no válido.

La respuesta HTTP tendrá un código de estado 403 si se introduce una clave de la API de OpenTok o un token JWT no válido.

La respuesta HTTP presenta un código de estado 500 debido a un error del servidor de OpenTok.

Ejemplo

El siguiente ejemplo de línea de comandos permite obtener información sobre un archivo:

api_key=12345
json_web_token="jwt_string" # replace with a JSON web token (see "Authentication")
id=23435236235235235235
curl \
    -i \
    -X GET \
    -H "X-OPENTOK-AUTH:$json_web_token" \
    https://api.opentok.com/v2/project/$api_key/archive/$archive
  • Establezca el valor de api_key a tu clave API de OpenTok.
  • Establezca el valor de json_web_token a un token web JSON (véase Autenticación).
  • Fije el id valor al identificador del archivo.

Borrar un archivo

Para eliminar un archivo, envía una solicitud HTTP DELETE.

Solo puedes eliminar un archivo que tenga el estado de "available" o "uploaded". Al eliminar un archivo, se elimina su entrada de la lista de archivos (véase Archivos de anuncios). Para un "available" archivo; además, elimina el archivo comprimido, por lo que ya no estará disponible para su descarga.

HTTP DELETE para archivar

Envía una solicitud HTTP DELETE a la siguiente URL:

https://api.opentok.com/v2/project/<api_key>/archive/<archive_id>

Sustituir <api_key> con tu clave API de OpenTok. Consulta la página del proyecto de tu Account de la Video API.

Sustituir <archive_id> con el ID del archivo.

Nota: Anteriormente, esta URL REST utilizaba /partner (que ahora está en desuso) en lugar de /project.

Propiedades del encabezado DELETE

Las llamadas a la API deben autenticarse mediante un encabezado HTTP personalizado — X-OPENTOK-AUTH — junto con un token web JSON (JWT). Véase Autenticación.

Respuesta

Una respuesta HTTP con el código de estado 204 indica que el archivo se ha eliminado.

La respuesta HTTP tendrá un código de estado 403 si se introduce una clave de la API de OpenTok no válida, un token JWT no válido o un ID de archivo no válido.

La respuesta HTTP tiene un código de estado 409 si el estado del archivo no es "uploaded", "available", o "deleted".

La respuesta HTTP presenta un código de estado 500 debido a un error del servidor de OpenTok.

Ejemplo

El siguiente ejemplo de línea de comandos elimina un archivo:

api_key=12345
json_web_token="jwt_string" # replace with a JSON web token (see "Authentication")
id=b40ef09b-3811-4726-b508-e41a0f96c68f
curl \
     -i \
     -X DELETE \
     -H "X-OPENTOK-AUTH:$json_web_token" \
     https://api.opentok.com/v2/project/$api_key/archive/$id
  • Establezca el valor de api_key a tu clave API de OpenTok.
  • Establezca el valor de json_web_token a un token web JSON (véase Autenticación).
  • Fije el id valor correspondiente al ID del archivo que se va a eliminar.

Configuración de un destino de carga para el archivado en S3 o Azure

En un proyecto de OpenTok, puedes configurar OpenTok para que suba los archivos completados a un depósito de Amazon S3 (o a un proveedor de almacenamiento compatible con S3) o a un contenedor de Windows Azure.

Nota: También puedes configurar un destino para la subida de archivos en tu Cuenta API de Video de Vonage página.

En el caso de Amazon S3, deberás conceder a Vonage permiso de solo carga en el bucket de Amazon S3. Si deseas utilizar un usuario de IAM de S3, asígnale la siguiente política de usuario:

{
 "Version": "2012-10-17",
 "Statement": [
   {
     "Sid": "Stmt1",
     "Effect": "Allow",
     "Resource": [ "arn:aws:s3:::<your-bucket-name>/*" ],
     "Action": [
       "s3:PutObject",
       "s3:ListBucket"
     ]
   },
   {
     "Sid": "Stmt2",
     "Effect": "Allow",
     "Resource": [ "arn:aws:s3:::*" ],
     "Action": [
       "s3:ListAllMyBuckets"
     ]
   }
 ]
}

Para configurar un destino de carga de archivos, envía una solicitud HTTP PUT.

Si estableces una ruta de subida, cada archivo comprimido completado se subirá como un archivo denominado archive.mp4 en la ruta /projectKey/archiveId/ del segmento de destino, donde projectKey es la clave API del proyecto, y archiveId es el identificador del archivo.

Si ya has configurado un destino de subida de archivos comprimidos para los archivos comprimidos de un proyecto, puedes enviar otra solicitud PUT para registrar un nuevo destino de subida.

Para más información sobre el archivado, consulte el programación de archivado guía.

HTTP PUT para archivar

Envía una solicitud HTTP PUT a la siguiente URL:

https://api.opentok.com/v2/project/<api_key>/archive/storage

Sustituir <api_key> con la clave API del proyecto OpenTok.

Propiedades del encabezado PUT

Autentifica esta llamada a la API utilizando un encabezado HTTP personalizado — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Establece este encabezado con un token JWT (véase Autenticación).

Fije el Content-type encabezado a application/json:

Content-Type:application/json

Datos PUT

En el caso de un bucket de Amazon S3, incluye un objeto JSON con el siguiente formato como datos de la solicitud PUT:

{
    "type": "s3",
    "config": {
        "accessKey":"myUsername",
        "secretKey":"myPassword",
        "bucket": "bucketName",
        "endpoint": "http://s3.cloudianhyperstore.com"
    },
    "fallback":"none"
}

El objeto JSON incluye las siguientes propiedades:

  • type - "s3" (para Amazon S3)

  • config — Configuración del Account de Amazon Web Services:

  • accessKey — La clave de acceso de Amazon Web Services

  • secretKey — La clave secreta de Amazon Web Services

  • bucket — El nombre del depósito de S3.

  • endpoint (opcional) — Un punto de acceso de S3. Es opcional. El punto de acceso predeterminado es http://s3.amazonaws.com (el punto final de Amazon S3). Especifica esto si deseas utilizar una solución de almacenamiento compatible con S3 (distinta de Amazon S3). Establece aquí la URL base del punto final, incluyendo el protocolo (http o https), por ejemplo: "https://s3.cloudianhyperstore.com" o "https://storage.googleapis.com". Admitimos Cloudian y Google Cloud Storage (al que se accede mediante la API de AWS S3) como soluciones de almacenamiento compatibles con S3. Otros servicios compatibles con S3 pueden presentar limitaciones en cuanto a sus funciones.

  • fallback — Configúralo en "opentok" para que el archivo esté disponible en el panel de control de OpenTok en caso de que falle la subida. Configúralo en "none" (o omite la propiedad) para evitar que los archivos de archivo se almacenen en la nube de OpenTok si la subida falla.

En el caso de un contenedor de Windows Azure, incluye un objeto JSON con el siguiente formato como datos de la solicitud PUT:

{
    "type": "azure",
    "config": {
        "accountName":"myAccountname",
        "accountKey":"myAccountKey",
        "container": "containerName",
        "domain": "domainName"
    },
    "fallback":"none"
}

El objeto JSON incluye las siguientes propiedades:

  • type - "azure" (para Microsoft Azure)

  • config — Configuración del Account de Windows Azure:

  • accountName — El nombre de la cuenta de Windows Azure

  • accountKey — La clave del Account de Windows Azure

  • container — El nombre del contenedor de Windows Azure.

  • domain (opcional) — El dominio de Windows Azure en el que se encuentra el contenedor.

  • fallback — Configúralo en "opentok" para que el archivo esté disponible en el panel de control de OpenTok en caso de que falle la subida. Configúralo en "none" (o omite la propiedad) para evitar que los archivos de archivo se almacenen en la nube de OpenTok si la subida falla.

Respuesta HTTP

La respuesta HTTP tendrá uno de los siguientes códigos de estado:

  • 200 — Éxito. El cuerpo de la respuesta coincide con los datos que has enviado.

  • 400 — Solicitud no válida. Esta respuesta puede indicar lo siguiente:

  • El tipo no está definido.

  • El tipo no es compatible (no es "s3" o "azure").

  • La configuración no está definida.

  • El valor de la configuración supera el límite de tamaño. Ciframos el parámetro de configuración al almacenarlo, y el tamaño cifrado debe ser de 2.048 caracteres o menos.

  • Los datos de tu solicitud contienen código JSON no válido.

    • 403 — Error de autenticación. Has introducido un token no válido en el X-OPENTOK-AUTH de cabeza.

Ejemplo

El siguiente ejemplo de línea de comandos configura un depósito de S3 para un proyecto:

token=123456789       # Change this to your JWT token
projectKey=55555      # Change this to the project API key
storage_type=s3
access_key=myUsername # Change this to your S3 access key
secret_key=myPassword # Change this to your S3 secret key
bucket=bucketName     # Change this to the bucket name
data='{"type": "$storage_type", "config": { "accessKey":"$access_key", "secretKey":"$secret_key", "bucket": "$bucket"}}'
curl \
     -i \
     -H "Content-Type: application/json" \
     -X PUT -H "X-TB-OPENTOK-AUTH:$token" -d "$data" \
     https://api.opentok.com/v2/project/$partnerKey/archive/storage

  • Establezca el valor de token a un token JWT válido de OpenTok.

  • Establezca el valor de projectKey a la clave API del proyecto.

  • Fije el storage_type valor a "s3".

  • Fije el access_key valor a la clave de acceso de tu Account de Amazon Web Services .

  • Fije el secret_key valor de la clave secreta de tu Account de Amazon Web Services .

  • Fije el bucket valor al nombre del bucket.

Eliminación de un destino de carga para el archivado

Si has configurado un destino de carga de archivos comprimidos para los archivos comprimidos de un proyecto, puedes eliminarlo.

Nota: También puedes eliminar un destino de carga de archivos en tu Cuenta API de Video de Vonage página.

HTTP DELETE para archivar

Envía una solicitud HTTP DELETE a la siguiente URL:

https://api.opentok.com/v2/project/<project_key>/archive/storage

Sustituir <project_key> con la clave API del proyecto.

Propiedades del encabezado DELETE

Autentifica esta llamada a la API utilizando un encabezado HTTP personalizado: X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Establece este encabezado con un token JWT (véase Autenticación).

Respuesta

La respuesta HTTP tendrá uno de los siguientes códigos de estado:

  • 204 — Éxito (sin contenido).

  • 403 — Error de autenticación. Has introducido un token no válido en el encabezado X-OPENTOK-AUTH.

  • 404 — No existe ningún destino para la subida.

### Ejemplo

El siguiente ejemplo de línea de comandos elimina un destino de carga de un proyecto:

token=123456789   # Change this to your JWT token
projectKey=55555  # Change this to the project key
curl \
     -i \
     -H "Content-Type: application/json" \
     -X DELETE -H "X-OPENTOK-AUTH:$token" \
     https://api.opentok.com/v2/project/$projectKey/archive/storage

  • Establezca el valor de token a un token JWT válido de OpenTok.

  • Establezca el valor de projectKey a la clave API del proyecto.

Cambiar dinámicamente el tipo de estructura de un archivo compuesto

Puedes cambiar dinámicamente el tipo de diseño de un archivo compuesto mientras se está grabando.

Para obtener más información sobre el archivado compuesto, consulta el Guía para desarrolladores sobre el archivado de OpenTok y Personalización del diseño de vídeo para composiciones archivos.

HTTP PUT para archivar

Envía una solicitud HTTP PUT a la siguiente URL:

https://api.opentok.com/v2/project/<apiKey>/archive/<archiveId>/layout

Sustituir <apiKey> con tu clave API de OpenTok.

Sustituir <archiveId> con el ID del archivo.

Propiedades del encabezado PUT

Fije el Content-Type encabezado a application/json.

Autentifica esta llamada a la API utilizando un encabezado HTTP personalizado — X-OPENTOK-AUTH — configurado como un token web JSON. Véase Autenticación.

Datos PUT

Incluye un objeto JSON con el siguiente formato como contenido del cuerpo de la solicitud:

{
  "type": "custom",
  "screenshareType": "optional layout type to use when there is a screen-sharing stream",
  "stylesheet": "the layout stylesheet (only used with type == custom)"
}

El objeto JSON incluye las siguientes propiedades:

  • tipo (Cadena) — El tipo de estructura del archivo. Los valores válidos son "bestFit" (ajuste óptimo), "custom" (personalizado), "horizontalPresentation" (presentación horizontal), "pip" (imagen en imagen), y "verticalPresentation" (presentación vertical). Si se especifica un "custom" tipo de diseño, establezca el stylesheet propiedad en la hoja de estilos. (Para otros tipos de diseño, no establezcas la stylesheet propiedad.) Para obtener más información, consulta Personalización del diseño de vídeo para los archivos compuestos.

    Al especificar un tipo de diseño distinto al de «Best Fit», asegúrate de aplicar las clases de diseño adecuadas a las transmisiones de la sesión de OpenTok (véase Asignación de clases de diseño de retransmisiones en directo a las retransmisiones de OpenTok streams).

  • hoja de estilo (Cadena) — Opcional. Indícalo solo si configuras el type propiedad a "custom". Ajuste el stylesheet propiedad en la hoja de estilos. (Para otros tipos de diseño, no establezcas la stylesheet propiedad.) Para obtener más información, consulte Definición de diseños personalizados.

  • tipo de pantalla compartida (Cadena) — Opcional. El tipo de diseño que se utilizará cuando haya una transmisión compartida de pantalla en la sesión. Ten en cuenta que, para utilizar esta propiedad, debes configurar la type a "bestFit" y dejar la propiedad stylesheet Propiedad no definida. Para obtener más información, consulta Tipos de diseño para pantalla compartida.

Respuesta

La respuesta HTTP tendrá uno de los siguientes códigos de estado:

  • 200 — Éxito.
  • 400 — Solicitud no válida. Esta respuesta puede indicar que los datos de tu solicitud no cumplen el formato JSON válido. También puede indicar que has introducido opciones de diseño no válidas.
  • 403 — Error de autenticación.
  • 500 — Error del servidor de OpenTok.

Ejemplo

curl -i \
   -X PUT \
   -H X-OPENTOK-AUTH:JWT_TOKEN \
   -H "Content-Type:application/json" \
   -D {\"type\":"verticalPresentation"} \
   https://api.opentok.com/v2/project/$apiKey/archive/$archiveId/layout

Modificación de las clases de diseño del archivo compuesto para una transmisión de OpenTok

Utiliza este método para cambiar las clases de diseño de una transmisión de OpenTok. Las clases de diseño definen cómo se muestra la transmisión en el diseño de un archivo compuesto de OpenTok. Para obtener más información, consulta Asignación de clases de diseño de retransmisiones en directo a las retransmisiones de OpenTok streams.

HTTP PUT para la transmisión

Envía una solicitud HTTP PUT a la siguiente URL:

https://api.opentok.com/v2/project/<apiKey>/session/<sessionId>/stream

Sustituir <apiKey> con tu clave API de OpenTok. Sustituye <sessionId> con el ID de sesión.

Propiedades del encabezado PUT

Fije el Content-Type encabezado a application/json.

Autentifica esta llamada a la API utilizando un encabezado HTTP personalizado — X-OPENTOK-AUTH — configurado como un token web JSON. Véase Autenticación.

Datos PUT

Incluye un objeto JSON con el siguiente formato como contenido del cuerpo de la solicitud:

{
  "items": [
    {
      "id": "8b732909-0a06-46a2-8ea8-074e64d43422",
      "layoutClassList": ["full"]
    }
  ]
}

El objeto JSON incluye un items matriz de objetos. Cada objeto define las clases de diseño que se deben asignar a un flujo y contiene las siguientes propiedades:

  • id (Cadena) — El identificador del flujo.
  • layoutClassList (Matriz) — Una matriz de clases de diseño (todas ellas cadenas) para el flujo.

Puedes actualizar la lista de clases de diseño para varias secuencias pasando varios objetos JSON en el items matriz.

Respuesta

La respuesta HTTP tendrá uno de los siguientes códigos de estado:

  • 200 — Éxito.
  • 400 — Solicitud no válida. Esta respuesta puede indicar que los datos de tu solicitud no cumplen el formato JSON válido. También puede indicar que has introducido opciones de diseño no válidas.
  • 403 — Error de autenticación.
  • 500 — Error del servidor de OpenTok.

Ejemplo

curl -i \
   -X PUT \
   -H X-OPENTOK-AUTH:JWT_TOKEN \
   -H "Content-Type:application/json" \
   -D {\"streamId\":STREAM_ID,\"layoutClassList\":[\"CLASS_NAME\"]} \
   https://api.opentok.com/v2/project/$apiKey/session/$sessionId

Selección de flujos que se incluirán en un archivo

Utiliza este método para modificar los flujos incluidos en un archivo compuesto que se haya iniciado con el comando streamMode ajustado a "manual" (véase Iniciar una grabación de archivo).

El generador de archivos incluye flujos añadidos basados en normas de priorización de flujos.

HTTP PATCH a archive/streams

Envía una solicitud HTTP PATCH a la siguiente URL:

https://api.opentok.com/v2/project/<apiKey>/archive/<archiveId>/streams

Sustituir <apiKey> con tu clave API de OpenTok. Sustituye <archiveId> con el ID del archivo.

Propiedades del encabezado PATCH

Fije el Content-Type encabezado a application/json.

Autentifica esta llamada a la API utilizando un encabezado HTTP personalizado — X-OPENTOK-AUTH — configurado como un token web JSON. Véase Autenticación.

Datos de PATCH

Para añadir un flujo al archivo, incluye un objeto JSON con el siguiente formato como contenido del cuerpo de la solicitud:

{
  "addStream": "12312312-3811-4726-b508-e41a0f96c68f",
  "hasAudio": true,
  "hasVideo": false
}

El objeto JSON contiene las siguientes propiedades:

  • addStream (Cadena) — El identificador del flujo.
  • hasAudio (Booleano, opcional) — Indica si el archivo resultante debe incluir el audio de la transmisión (true, el valor por defecto) o no (false).
  • hasVideo (Booleano, opcional) — Indica si el archivo resultante debe incluir el vídeo de la transmisión (true, el valor por defecto) o no (false).

Puedes llamar al método varias veces con addStream configurados con el mismo ID de transmisión, para activar o desactivar el audio o el vídeo de la transmisión en el archivo.

Si configuras ambos hasAudio y hasVideo a false, recibirás una respuesta de error.

Para evitar que una transmisión se incluya en el archivo, incluye un objeto JSON con el siguiente formato como contenido del cuerpo de la solicitud:

{
  "removeStream": "12312312-3811-4726-b508-e41a0f96c68f"
}

Fije el removeStream propiedad al ID del flujo.

Respuesta

La respuesta HTTP tendrá uno de los siguientes códigos de estado:

  • 204 — Éxito (sin contenido).
  • 400 — Solicitud no válida. Esta respuesta puede indicar que los datos proporcionados en tu solicitud no son un JSON válido, o que la solicitud no se ha podido completar porque el archivo se inició con streamMode ajustado a "auto", que no admite la manipulación de flujos.
  • 403 — Error de autenticación.
  • 404 — No se ha encontrado el archivo ni la transmisión.
  • 500 — Error del servidor de OpenTok.

Ejemplos

Cómo añadir una transmisión a un archivo:

curl -i \
   -X PATCH \
   -H X-OPENTOK-AUTH:$JWT_TOKEN \
   -H "Content-Type:application/json" \
   -D {\"addStream\":$STREAM_ID} \
   https://api.opentok.com/v2/project/$apiKey/archive/$ARCHIVE_ID/streams

Eliminar el vídeo de una retransmisión en un archivo (pero conservando el audio):

curl -i \
   -X PATCH \
   -H X-OPENTOK-AUTH:$JWT_TOKEN \
   -H "Content-Type:application/json" \
   -D {\"addStream\":\"$STREAM_ID\", \"hasAudio\":true, \"hasVideo\":false } \
   https://api.opentok.com/v2/project/$apiKey/archive/$ARCHIVE_ID/streams

Cómo eliminar una secuencia de un archivo:

curl -i \
   -X PATCH \
   -H X-OPENTOK-AUTH:$JWT_TOKEN \
   -H "Content-Type:application/json" \
   -D {\"removeStream\":\"$STREAM_ID\"} \
   https://api.opentok.com/v2/project/$apiKey/archive/$ARCHIVE_ID/streams

Iniciar una llamada SIP

Para conectar tu plataforma SIP a una sesión de OpenTok, envía una solicitud HTTP POST al dial método. El audio procedente de tu extremo de la llamada SIP se añade a la sesión de OpenTok como una transmisión de solo audio. El OpenTok Media Router mezcla el audio de otras transmisiones de la sesión y envía el audio mezclado a tu terminal SIP.

La llamada finaliza cuando tu servidor SIP envía un BYE mensaje (para finalizar la llamada). También puedes finalizar una llamada utilizando el método de la API REST de OpenTok para desconectar a un cliente de una sesión. La pasarela SIP de OpenTok finaliza automáticamente una llamada tras 5 minutos de inactividad (5 minutos sin recibir datos multimedia). Además, como medida de seguridad, la pasarela SIP de OpenTok cierra cualquier llamada SIP que dure más de 6 horas.

La función de interconexión SIP requiere que utilices una sesión de OpenTok que utilice el OpenTok Media Router (una sesión con el modo de medios configurado en «enrutado»).

Para más información, incluidos detalles técnicos y consideraciones de seguridad, consulte el Interconexión SIP de OpenTok guía del desarrollador.

Solicitud HTTP POST para marcar un número

Envía una solicitud HTTP POST a la siguiente URL:

https://api.opentok.com/v2/project/<api_key>/dial

Sustituir <api_key> con tu clave API de OpenTok. Consulta la página del proyecto de tu Account de la Video API.

Nota: Anteriormente, esta URL REST utilizaba /partner (que ahora está en desuso) en lugar de /project.

Propiedades del encabezado POST

Las llamadas a la API deben autenticarse mediante un encabezado HTTP personalizado — X-OPENTOK-AUTH — junto con un token web JSON (JWT). Véase Autenticación.

Establece el encabezado «Content-type» en «application/json»:

Content-Type:application/json

Datos POST

Incluye un objeto JSON con el siguiente formato como datos POST:

{
  "sessionId": "OpenTok session ID",
  "token": "A valid OpenTok token",
  "sip": {
    "uri": "sip:user@sip.partner.com;transport=tls",
    "from": "from@example.com",
    "headers": {
      "headerKey": "headerValue"
    },
    "auth": {
      "username": "username",
      "password": "password"
    },
    "secure": true|false,
    "video": true|false,
    "observeForceMute": true|false,
    "streams": ["stream-id-1", "stream-id-2"]
  }
}

El objeto JSON incluye las siguientes propiedades:

  • sessionId​ (obligatorio) — El identificador de sesión de OpenTok de la llamada SIP a la que se desea unirse.
  • token​ (obligatorio) — El token de OpenTok que se utilizará para el participante al que se llama. Puedes añadir un token data para determinar si el participante se encuentra en un terminal SIP o para obtener otros datos identificativos, como números de teléfono. (Las bibliotecas de cliente de OpenTok incluyen propiedades que permiten examinar los datos de conexión de un cliente conectado a una sesión.) Consulte la Creación de fichas guía del desarrollador.

  • SIP uri​ ​(obligatorio) — El URI SIP que se utilizará como destino de la llamada SIP iniciada desde OpenTok hacia tu plataforma SIP.

    Si el SIP ​uri​ contiene un ​transport=tls​ encabezado, la negociación entre Vonage y el terminal SIP se llevará a cabo de forma segura. Ten en cuenta que esto solo se aplicará a la propia negociación, y no a la transmisión de audio. Si también deseas que la transmisión de audio esté cifrada, configura el ​secure​ propiedad a ​true​.

    Este es un ejemplo de negociación de llamadas seguras:

    "sip:user@sip.partner.com;transport=tls"

    Este es un ejemplo de negociación de llamada insegura:

    "sip:user@sip.partner.com"

  • from ​(opcional): El número o la cadena que se enviará al número SIP final como identificador de la persona que llama. Debe ser una cadena con el formato from@example.comdonde from puede ser una cadena compuesta por caracteres de palabras (a-z, A-Z, 0-9) o por los caracteres _, +, !, %, `, ', ~, o -.

    Si from se establece en un número (por ejemplo, "<14155550101@example.com>"), aparecerá como el número de llamada entrante en los teléfonos de la red PSTN. Si from no está definido o tiene el valor de una cadena (por ejemplo, "<joe@example.com>"), +00000000 aparecerá como número de origen en los teléfonos de la red PSTN.

    Si from no está definido, o se establece en una cadena (por ejemplo, "<joe@example.com>"), es decir, un número desconocido o no autorizado, en la mayoría de los casos se convertirá en "Unknown" antes de que los proveedores de SIP reenvíen la solicitud a un operador para la terminación en la red PSTN. Dependiendo del proveedor, "Unknown" aparecerá como número de origen en los teléfonos de la red PSTN. En algunos casos, los operadores pueden rechazar esas llamadas por motivos de seguridad, para evitar problemas como la suplantación de números. En caso de que los operadores no rechacen la llamada, +00000000 aparecerá como número de origen en los teléfonos de la red PSTN.

    Un número se considera no reconocido cuando no cumple la norma E.164 o no es un Número virtual de Vonage si te conectas a la Voice API de Vonage, por ejemplo.

  • SIP headers​​ (opcional) — Este objeto define los encabezados personalizados que se añadirán al SIP ​INVITE​ solicitud iniciada desde OpenTok hacia tu plataforma SIP.

  • SIP auth​ (opcional) — Este objeto contiene el nombre de usuario y la contraseña que se utilizarán en el SIP INVITE​ Solicitud de autenticación HTTP Digest, si así lo exige tu plataforma SIP.

  • secure​ (opcional) — Un indicador booleano que indica si el contenido multimedia debe transmitirse cifrado (​true​) o no (​false​, el valor por defecto).

  • video (opcional) — Un indicador booleano que indica si la llamada SIP incluirá vídeo (​true​) o no (​false​, que es el valor predeterminado). Si se incluye vídeo, el vídeo del cliente SIP se incorpora a la transmisión de OpenTok que se envía a la sesión de OpenTok. El vídeo SIP tiene un límite de 480p a 800 kbps. El cliente SIP recibirá un único vídeo compuesto a partir de las transmisiones publicadas en la sesión de OpenTok.

  • observeForceMute (opcional) Un indicador booleano que indica si el punto final SIP respeta modulación de silenciamiento forzado (true) o no (falsepor defecto). Además, con observeForceMute ajustado a true, la persona que llama puede pulsar «*6» para activar o desactivar el silencio del audio publicado. Para que la función de activación/desactivación del silencio mediante «*6» funcione, la persona que llama a través de SIP debe negociar los tonos DTMF según RFC 2833 (dígitos RFC 2833/RFC 4733). La función de activación y desactivación del silencio no es compatible con SIP INFO ni con los tonos DTMF en banda. Se reproduce un mensaje (en inglés) para la persona que llama cuando esta activa o desactiva el silencio, o cuando se silencia el cliente SIP mediante una acción de silencio forzado.

  • streams (opcional) — Una matriz de identificadores de flujos que se incluirán en la llamada SIP. Si no se configura esta propiedad, se incluirán en la llamada todos los flujos de la sesión.

Respuesta

Los datos sin procesar de la respuesta HTTP, con código de estado 200, son un mensaje codificado en JSON con el siguiente formato:

{
	"id": "b0a5a8c7-dc38-459f-a48d-a7f2008da853",
	"connectionId": "e9f8c166-6c67-440d-994a-04fb6dfed007",
	"streamId": "482bce73-f882-40fd-8ca5-cb74ff416036",
}

El objeto JSON incluye las siguientes propiedades:

  • id - Un ID único para la llamada SIP.
  • connectionId — El identificador de conexión de OpenTok correspondiente a la conexión de la llamada SIP en la sesión de OpenTok. Puedes utilizar este identificador de conexión para finalizar la llamada SIP mediante la API REST de OpenTok.
  • streamId — El identificador de transmisión de OpenTok correspondiente a la transmisión de la llamada SIP en la sesión de OpenTok.

La respuesta HTTP presenta un código de estado 400 en los siguientes casos:

  • No has introducido ningún ID de sesión o has introducido un ID de sesión no válido.

La respuesta HTTP tendrá un código de estado 403 si se introduce una clave de la API de OpenTok no válida o un token web JSON no válido.

La respuesta HTTP tiene un código de estado 404 si la sesión no existe.

La respuesta HTTP tendrá un código de estado 409 si intentas iniciar una llamada SIP para una sesión que no utilice el OpenTok Media Router.

La respuesta HTTP presenta un código de estado 500 debido a un error del servidor de OpenTok.

Ejemplo

El siguiente ejemplo de línea de comandos conecta tu terminal SIP a una sesión de OpenTok:

api_key=12345
json_web_token="jwt_string" # replace with a JSON web token (see "Authentication")
session_id=2_MX40NzIwMzJ-flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN-MC45NDQ2MzE2NH4
sip_uri='sip:user@sip.partner.comwhen;transport=tls'
data='{\
  "sessionId" : "'$session_id'", \
  "token": "A valid OpenTok token", \
  "sip": { \
    "uri": "'$sip_uri'", \
    "auth": {
      "username": "username",
      "password": "password"
    }
  }
}'
curl \
  -i \
  -H "Content-Type: application/json" \
  -H "X-OPENTOK-AUTH:$json_web_token" \
	-d "$data" \
  https://api.opentok.com/v2/project/$api_key/dial
  • Establezca el valor de api_key a tu clave API de OpenTok.
  • Establezca el valor de json_web_token a un token web JSON (véase Autenticación).
  • Fije el session_id Introduce el ID de la sesión de OpenTok a la que deseas conectarte desde tu plataforma SIP.
  • Fije el sip_uri valor al URI SIP de tu terminal SIP.
  • Fije el token propiedad del data JSON a un token de conexión válido de OpenTok para el participante al que se llama (véase el Creación de fichas (Guía para desarrolladores).
  • Fije el username y password propiedades del data JSON con el nombre de usuario y la contraseña de tu terminal SIP. (Esto es opcional.)

Envío de dígitos DTMF a clientes SIP

Utiliza la API REST «play-dtmf» para enviar dígitos DTMF a todos los participantes de una sesión activa de OpenTok o a un cliente concreto conectado a dicha sesión.

Los eventos de telefonía se negocian a través de SDP y se transmiten como dígitos RFC4733/RFC2833 al punto final remoto.

Enviar dígitos DTMF a todos los clientes conectados a la sesión

Envía una solicitud HTTP POST a la siguiente URL:

https://api.opentok.com/v2/project/<api_key>/session/<session_id>/play-dtmf

Sustituir <api_key> con tu clave API de OpenTok. Consulta la página «Proyecto» de tu Account de la Video API. Sustituir <session_id> con el ID de la sesión a la que estás enviando la señal DTMF.

Los clientes que no admiten DTMF (como los clientes que no son SIP) ignoran el mensaje DTMF.

Propiedades del encabezado POST

Las llamadas a la API deben autenticarse mediante un encabezado HTTP personalizado — X-OPENTOK-AUTH — junto con un token web JSON (JWT). Véase Autenticación.

Fije el Content-type encabezado a application/json:

Content-Type:application/json

Datos POST

Incluye un objeto JSON con el siguiente formato como datos POST:

{ "digits": "1713" }

El objeto JSON incluye un digits propiedad. Se trata de la cadena de dígitos DTMF que se va a enviar. Puede incluir 0-9, «*», «#» y «p». A p indica una pausa de 500 ms (si necesitas añadir un retraso en el envío de los dígitos).

Respuesta

En una llamada correcta, la respuesta incluye un código de estado HTTP 200.

En caso de error, la respuesta incluye uno de los siguientes códigos de estado HTTP:

  • 400 — Una de las propiedades — digits o sessionId — no es válido.

  • 403 — Error de autenticación. Esto puede ocurrir si utilizas una clave de API de OpenTok no válida o un token web JSON no válido

  • 404 — La sesión indicada no existe.

En caso de error, el cuerpo de la respuesta será JSON con un code y message propiedad:

{ "code" : 400, "message" : "One of the properties digits or sessionId is invalid." }

Ejemplo

Lo siguiente envía una solicitud HTTP POST al play-dtmf Recurso de la sesión:

SESSION_ID=2_MX40NTMyODc3Mn5-fg API_KEY=123456 JWT=jwt_token # replace with a JSON web token (see "Authentication") DATA='{"digits":"1713"}' curl -v \ -H "Content-Type: application/json" \ -X POST \ -H "X-OPENTOK-AUTH:${JWT}" \ -d "${DATA}" \ https://api.opentok.com/v2/project/${API_KEY}/session/${SESSION_ID}/play-dtmf

Enviar tonos DTMF a un cliente concreto conectado a la sesión

Envía una solicitud HTTP POST a la siguiente URL:

https://api.opentok.com/v2/project/<api_key>/session/<session_id>/connection/<connection_id>/play-dtmf

Sustituir <api_key> con tu clave API de OpenTok. Consulta la página del proyecto de tu Account de la Video API. Sustituir <session_id> con el ID de la sesión a la que estás enviando la señal DTMF. Sustituye <connection_id> con el ID de conexión del cliente al que estás enviando la señal DTMF.

Puedes obtener el ID de conexión de un cliente SIP a partir de la respuesta de la llamada a la API REST a iniciar la llamada SIP.

Si envías dígitos DTMF a un cliente que no es compatible con DTMF (como un cliente que no sea SIP), el cliente ignorará la solicitud.

Propiedades del encabezado POST

Las llamadas a la API deben autenticarse mediante un encabezado HTTP personalizado — X-OPENTOK-AUTH — junto con un token web JSON (JWT). Véase Autenticación.

Fije el Content-type encabezado a application/json:

Content-Type:application/json

Datos POST

Incluye un objeto JSON con el siguiente formato como datos POST:

{ "digits": "1713" }

El objeto JSON incluye un digits propiedad. Se trata de la cadena de dígitos DTMF que se va a enviar. Puede incluir 0-9, «*», «#» y «p». A p indica una pausa de 500 ms (si necesitas añadir un retraso en el envío de los dígitos).

Respuesta

En una llamada correcta, la respuesta incluye un código de estado HTTP 200.

En caso de error, la respuesta incluye uno de los siguientes códigos de estado HTTP:

  • 400 — Una de las propiedades — digits o sessionId — no es válido.

  • 403 — Error de autenticación. Esto puede ocurrir si utilizas una clave de API de OpenTok no válida o un token web JSON no válido

  • 404 — La sesión indicada no existe o el cliente especificado por el connectionId La propiedad no está vinculada a la sesión.

En caso de error, el cuerpo de la respuesta será JSON con un code y message propiedad:

{ "code" : 400, "message" : "One of the properties digits, sessionId or connectionId is invalid." }

Ejemplo

Envía una solicitud HTTP POST al play-dtmf recurso con un ID de conexión específico perteneciente a la sesión:

SESSION_ID=2_MX40NTMyODc3Mn5-fg CONNECTION_ID=396edda0-fc30-41fd-8e63 API_KEY=123456 JWT=jwt_token # replace with a JSON web token (see "Authentication") DATA='{"digits":"1713"}' curl -v \ -H "Content-Type: application/json" \ -X POST \ -H "X-OPENTOK-AUTH:${API_KEY}:${API_SECRET}" \ -d "${DATA}" \ https://api.opentok.com/v2/project/${API_KEY}/session/${SESSION_ID}/connection/${CONNECTION_ID}/play-dtmf

Iniciar una retransmisión en directo

Utiliza este método para iniciar una retransmisión en directo de una sesión de OpenTok. De este modo, la sesión se retransmite mediante HLS (HTTP Live Streaming) o RTMP.

Para poder iniciar correctamente la retransmisión de una sesión, debe haber al menos un cliente conectado a ella.

La retransmisión en directo puede dirigirse a un punto final HLS y a un máximo de cinco servidores RTMP simultáneamente durante una sesión. Solo se puede iniciar la retransmisión en directo en sesiones que utilicen el OpenTok Media Router (con el modo multimedia configurado en «routed»); no es posible utilizar la retransmisión en directo en sesiones cuyo modo multimedia esté configurado en «relayed». (Véase El OpenTok Media Router y los modos multimedia.)

Para obtener más información sobre la retransmisión en directo con OpenTok, consulta el Guía para desarrolladores de retransmisiones.

HTTP POST para la difusión

Envía una solicitud HTTP POST a la siguiente URL:

https://api.opentok.com/v2/project/<apiKey>/broadcast

Sustituir <apiKey> con tu clave API de OpenTok.

Nota: Anteriormente, esta URL REST utilizaba /partner (que ahora está en desuso) en lugar de /project.

Propiedades del encabezado POST

Fije el Content-Type encabezado a application/json.

Autentifica esta llamada a la API utilizando un encabezado HTTP personalizado — X-OPENTOK-AUTH — establecido como un token web JSON. Véase Autenticación.

Datos POST

Incluye un objeto JSON con el siguiente formato como contenido del cuerpo de la solicitud:

{
  "sessionId": "<session-id>",
  "layout": {
    "type": "custom",
    "stylesheet": "the layout stylesheet (only used with type == custom)",
    "screenshareType": "optional layout type to use when there is a screen-sharing stream"
  },
  "maxBitrate": 1000000,
  "maxDuration": 5400,
  "outputs": {
    "hls": {
      "dvr": false,
      "lowLatency": false
    },
    "rtmp": [{
      "id": "foo",
      "serverUrl": "rtmps://myfooserver:443/myfooapp",
      "streamName": "myfoostream"
    },
    {
      "id": "bar",
      "serverUrl": "rtmp://mybarserver:443/mybarapp",
      "streamName": "mybarstream"
    }]
  },
  "hasAudio": true,
  "hasVideo": true,
  "resolution": "640x480",
  "streamMode" : "auto"
}

El objeto JSON incluye las siguientes propiedades:

  • sessionId (Cadena) — Establece este valor en el ID de la sesión de OpenTok que quieras retransmitir.

  • hasAudio (Booleano) — (Opcional) Indica si la retransmisión incluirá audio (verdadero, valor por defecto) o no (falso). Si se establecen ambos hasAudio y hasVideo Si se establece en «false», la llamada a este método da lugar a un error.

  • hasVideo (Booleano) — (Opcional) Indica si la retransmisión incluirá vídeo (verdadero, valor por defecto) o no (falso). Si se establecen ambos hasAudio y hasVideo Si se establece en «false», la llamada a este método da lugar a un error.

    Nota: al configurar hasVideo Si se establece en «false», la retransmisión incluirá vídeo con fotogramas negros de 160x120 en las transmisiones RTMP. Algunos destinos, como YouTube y Facebook, rechazan las transmisiones RTMP que solo contienen audio.

  • layout (Objeto) — Opcional. Indícalo para asignar el tipo de diseño inicial de la emisión. Este objeto tiene tres propiedades: type, stylesheety screenshareType, que son cadenas de caracteres. Los valores válidos para el layout Las propiedades son "bestFit" (ajuste óptimo), "custom" (personalizado), "horizontalPresentation" (presentación horizontal), "pip" (imagen en imagen) y "verticalPresentation" (presentación vertical)). Si se especifica un "custom" tipo de diseño, establezca el stylesheet propiedad del layout objeto a la hoja de estilo. (Para otros tipos de diseño, no establezcas un stylesheet propiedad.) Establece el screenshareType propiedad del tipo de diseño que se utilizará cuando haya una transmisión compartida de pantalla en la sesión. (Esta propiedad es opcional.) Ten en cuenta que si configuras la screenshareType propiedad, debes configurar la type a "bestFit" y dejar la propiedad stylesheet Propiedad sin definir. Si no se especifica un tipo de diseño inicial, la transmisión utiliza el tipo de diseño «Best Fit». Para obtener más información, consulta Configuración del diseño de vídeo para la función de retransmisión en directo de OpenTok.

  • multiBroadcastTag (Cadena) — (Opcional) Configura este parámetro para permitir varias retransmisiones simultáneas de la misma sesión. Asigna una cadena única a cada retransmisión simultánea de una sesión en curso. Véase Emisiones simultáneas.

  • maxBitrate (opcional) — La tasa de bits máxima para las transmisiones, en bits por segundo. El valor mínimo es 100 000 y el máximo, 6 000 000.

  • maxDuration (Número entero) — Opcional. La duración máxima de la retransmisión, en segundos. La retransmisión se detendrá automáticamente cuando se alcance la duración máxima. Puedes establecer la duración máxima en un valor comprendido entre 60 (60 segundos) y 36 000 (10 horas). La duración máxima predeterminada es de 4 horas (14 400 segundos).

  • outputs (Objeto) — Obligatorio. Este objeto define los tipos de flujos de retransmisión que deseas iniciar (tanto HLS como RTMP). Puedes incluir HLS, RTMP o ambos como flujos de retransmisión. Si incluyes la retransmisión por RTMP, puedes especificar hasta cinco flujos RTMP de destino (o solo uno).

    Para cada transmisión RTMP, especifica serverUrl (la URL del servidor RTMP), streamName (el nombre de la retransmisión, como el nombre de la retransmisión en directo de YouTube o la clave de retransmisión de Facebook), y (opcionalmente) id (un identificador único para el flujo). Asegúrate de incluir el puerto para el serverUrl, como en "rtmps://myfooserver:443/myfooapp" (en lugar de "rtmps://myfooserver/myfooapp"). Si se especifica un ID, este se incluirá en la respuesta de la llamada REST y el Método REST para obtener información sobre una retransmisión en directo. Vonage transmite la sesión a cada URL RTMP que especifiques. Ten en cuenta que la transmisión en directo de OpenTok es compatible con RTMP y RTMPS.

    Para HLS, incluye un único hls en la propiedad outputs objeto. Este objeto incluye las siguientes propiedades opcionales:

    • dvr (Booleano) — Si se debe habilitar Funcionalidad de grabación digital (DVR) — rebobinar, pausar y reanudar — en los reproductores que lo admiten (true), o no (false, el valor por defecto). Si la función DVR está activada, la URL HLS incluirá un ?DVR cadena de consulta añadida al final.
    • lowLatency (Booleano) — Si se debe habilitar modo de baja latencia para HLSstream. Algunos reproductores HLS no admiten el modo de baja latencia. Esta función es incompatible con las transmisiones HLS en modo DVR.

    La URL HLS se devuelve en la respuesta y en el método REST para obtener información sobre una retransmisión en directo.

  • resolution (Cadena) — La resolución de la emisión: o bien "640x480" (paisaje SD, el valor predeterminado), "1280x720" (HD horizontal), "1920x1080" (FHD en horizontal), "480x640" (retrato en SD), "720x1280" (vertical en alta definición), o "1080x1920" (FHD vertical). Es posible que te interese utilizar una relación de aspecto vertical para las retransmisiones que incluyan transmisiones de vídeo desde dispositivos móviles (que suelen utilizar la relación de aspecto vertical). Esta propiedad es opcional.

  • streamMode (Cadena) — (Opcional) Indica si las transmisiones incluidas en la emisión se seleccionan automáticamente ("auto", que es el valor predeterminado) o manualmente ("manual"). Cuando las transmisiones se seleccionan automáticamente ("auto"), todas las transmisiones de la sesión pueden incluirse en la emisión. Cuando las transmisiones se seleccionan manualmente ("manual"), se especifican los flujos que se van a incluir mediante llamadas a este método REST. Puedes especificar si en la emisión se incluye el audio, el vídeo o ambos de una transmisión. Tanto en el modo automático como en el manual, el editor de emisiones incluye las transmisiones en función de normas de priorización de flujos.

Si solo necesitas admitir una URL RTMP, puedes pasar un objeto (en lugar de una matriz de objetos) para el rtmp valor de la propiedad en los datos POST que se proporcionan al llamar al método REST. Por ejemplo, los siguientes datos POST especifican una URL de salida RTMP (y no incluyen la salida HLS):

{
  "sessionId": "",
  "layout": {
    "type": "custom",
    "stylesheet": "the layout stylesheet (only used with type == custom)"
  },
  "outputs": {
    "rtmp": {
      "id": "my-id",
      "serverUrl": "rtmp://myserver:443/myapp",
      "streamName": "my-stream-name"
    }
  }
}

Respuesta

Los datos sin procesar de la respuesta HTTP, con código de estado 200, son un mensaje codificado en JSON con el siguiente formato:

{
  "id": "1748b7070a81464c9759c46ad10d3734",
  "sessionId": "2_MX4xMDBfjE0Mzc2NzY1NDgwMTJ-TjMzfn4",
  "projectId": 100,
  "createdAt": 1437676551000,
  "updatedAt": 1437676551000,
  "resolution": "640x480",
  "status": "started",
  "streamMode": "auto",
  "streams": [],
  "multiBroadcastTag": "broadcast-1234b",
  "broadcastUrls": {
    "hls" : "http://server/fakepath/playlist.m3u8",
    "hlsStatus": "connecting",
    "rtmp": [{
      "id": "foo",
      "status": "connecting",
      "serverUrl": "rtmps://myfooserver:443/myfooapp",
      "streamName": "myfoostream",
    }, {
      "id": "bar",
      "status": "connecting",
      "serverUrl": "rtmp://mybarserver:443/mybarapp",
      "streamName": "mybarstream",
    }]
  }
}

El objeto JSON incluye las siguientes propiedades:

  • id — El identificador único de la emisión
  • sessionId — El ID de sesión de OpenTok
  • projectId — Tu clave de API de OpenTok
  • createdAt — La hora a la que comenzó la emisión, expresada en milisegundos desde la época Unix (1 de enero de 1970, 00:00:00 UTC)
  • updatedAt — En este método de inicio, esta marca de tiempo coincide con la marca de tiempo «createdAt».
  • resolution — La resolución de la emisión (ya sea «640x480», «1280x720», «1920x1080», «480x640», «720x1280» o «1920x1080»).
  • status - Se establece en "started".
  • streamMode - Si todos los flujos se incluyen en la emisión ("auto") o seleccione los flujos que desea incluir en la emisión ("manual").
  • streams - Una matriz de objetos correspondientes a los flujos que se están emitiendo actualmente. Esto sólo se establece para una emisión con el parámetro status ajustado a "started" y el streamMode ajustado a "manual". Cada objeto de la matriz incluye las siguientes propiedades:
    • streamId — El identificador de la transmisión incluida en la emisión.
    • hasAudio — Si el audio de la transmisión se incluye en la emisión.
    • hasVideo - Si el vídeo del flujo se incluye en la emisión.
  • maxDuration — La duración máxima de la emisión (si se ha establecido alguna), en segundos.
  • multiBroadcastTag - La etiqueta única para emisiones simultáneas (si se ha establecido una).
  • broadcastUrls — Un objeto que contiene información sobre las transmisiones HLS y RTMP.

Si has especificado un punto final HLS, el objeto incluye un hls propiedad y un hlsStatus propiedad. El hls La propiedad se establece en la URL de la emisión HLS. Ten en cuenta que esta URL de emisión HLS apunta a un archivo de índice, una lista de reproducción con formato .M3U8 que contiene una lista de URL de archivos de segmentos multimedia .ts (archivos de flujo de transporte MPEG-2). Aunque las URL tanto del archivo de índice de la lista de reproducción como de los archivos de segmentos multimedia se facilitan en cuanto se devuelve la respuesta HTTP, no se debe acceder a ellas hasta 15-20 segundos después, una vez iniciada la transmisión HLS, debido al retraso entre la transmisión HLS y las transmisiones en directo de la sesión de OpenTok. Véase https://developer.apple.com/library/ios/technotes/tn2288/_index.html Para obtener más información sobre el archivo de índice de la lista de reproducción y los archivos de segmentos multimedia para HLS. El hlsStatus es una de las siguientes:

  • "connecting" — El servidor de OpenTok está iniciando los transcodificadores. Este es el estado inicial.
  • "ready" — El servidor de OpenTok se ha inicializado correctamente, pero la CDN no está reproduciendo el contenido multimedia.
  • "live" — El servidor de OpenTok se ha inicializado correctamente y la CDN está reproduciendo el contenido multimedia.
  • "ended" - El flujo fuente ha finalizado. Si el DVR está activado y se solicitan medios pregrabados, el estado cambiará a "live".
  • "error" — Se ha producido un error en la plataforma OpenTok.

Si has especificado puntos finales de transmisión RTMP, el objeto incluye un rtmp propiedad. Se trata de una matriz de objetos que contiene información sobre cada una de las transmisiones RTMP. Cada uno de estos objetos tiene las siguientes propiedades: id (el ID que has asignado a la transmisión RTMP), serverUrl (la URL del servidor), streamName (el nombre del canal), y status propiedad (que está establecida en "connecting"). Puedes llamar al Método REST de OpenTok para consultar las actualizaciones de estado de la retransmisión.

La respuesta HTTP tendrá uno de los siguientes códigos de estado:

  • 200 — Éxito.
  • 400 — Solicitud no válida. Esta respuesta puede indicar que los datos de tu solicitud no son JSON válido. También puede indicar que has introducido opciones de diseño no válidas. O bien, que has superado el límite de cinco transmisiones RTMP simultáneas para una sesión de OpenTok. O que has especificado una resolución no válida.
  • 403 — Error de autenticación.
  • 409 — La retransmisión de la sesión ya ha comenzado. O si intentas iniciar una retransmisión simultánea de una sesión sin haber establecido un identificador único multiBroadcastTag valor.
  • 500 — Error del servidor de OpenTok.

Ejemplo

curl -i \
-X POST \
-H X-OPENTOK-AUTH:JWT_TOKEN \
-H "Content-Type:application/json" \
-D "{ \
  \"sessionId\": \"your-opentok-session-id\", \
  \"layout\": { \
    \"type\": \"custom\", \
    \"stylesheet\": \"custom-stylesheet-data\" \
  }, \
  \"outputs\": { \
    \"hls\": {}, \
    \"rtmp\": [{ \
      \"id\": \"foo\", \
      \"serverUrl\": \"rtmps://myfooserver:443/myfooapp\", \
      \"streamName\": \"myfoostream\" \
    }, \
    { \
      \"id\": \"bar\", \
      \"serverUrl\": \"rtmp://mybarserver:443/mybarapp\", \
      \"streamName\": \"mybarstream\" \
    }] \
  } \
}" \
https://api.opentok.com/v2/project/$apiKey/broadcast

Detener una retransmisión en directo

Utiliza este método para detener la retransmisión en directo de una sesión de OpenTok.

Ten en cuenta que una retransmisión se detiene automáticamente 60 segundos después de que el último cliente se desconecte de la sesión. Además, existe una duración máxima predeterminada de 4 horas (14 400 segundos) para cada transmisión HLS y RTMP (la retransmisión en directo se detiene automáticamente al alcanzar esta duración). Puedes modificar la duración máxima de la retransmisión configurando el maxDuration propiedad cuando tú iniciar la emisión Método REST.

HTTP POST a broadcast//stop

Envía una solicitud HTTP POST a la siguiente URL:

https://api.opentok.com/v2/project/<apiKey>/broadcast/<broadcastId>/stop

Sustituir <apiKey> con tu clave API de OpenTok. Sustituye <broadcastId> con el ID de la retransmisión que deseas detener. El ID de la retransmisión se obtiene al iniciar una retransmisión.

Propiedades del encabezado POST

Autentifica esta llamada a la API utilizando un encabezado HTTP personalizado — X-OPENTOK-AUTH — establecido como un token web JSON. Véase Autenticación.

Nota: Anteriormente, esta URL REST utilizaba /partner (que ahora está en desuso) en lugar de /project.

Respuesta

Los datos sin procesar de la respuesta HTTP, con código de estado 200, son un mensaje codificado en JSON con el siguiente formato:

{
  "id": "1748b707-0a81-464c-9759-c46ad10d3734",
  "sessionId": "2_MX4xMDBfjE0Mzc2NzY1NDgwMTJ-TjMzfn4",
  "projectId": 100,
  "createdAt": 1437676551000,
  "updatedAt": 1437936607000,
  "resolution": "640x480",
  "broadcastUrls": null
}

El objeto JSON incluye las siguientes propiedades:

  • id — El identificador único de la emisión
  • sessionId — El ID de la sesión de OpenTok que se está retransmitiendo
  • projectId — Tu clave de API de OpenTok
  • createdAt — La hora a la que comenzó la emisión, expresada en segundos desde la época Unix (1 de enero de 1970, 00:00:00 UTC)
  • updatedAt — El momento en que se interrumpió la emisión, expresado en segundos desde la época Unix (1 de enero de 1970, 00:00:00 UTC)
  • resolution — La resolución de la emisión (ya sea «640x480», «1280x720», «1920x1080», «480x640», «720x1280» o «1080x1920»).
  • status - Se establece en "stopped".
  • streamMode - Si todos los flujos se incluyen en la emisión ("auto") o seleccione los flujos que desea incluir en la emisión ("manual").
  • streams — Una matriz de objetos que corresponden a las transmisiones que se están emitiendo en ese momento. En el caso del método «stop», se trata de una matriz vacía.
  • maxDuration — La duración máxima de la emisión (si se ha establecido alguna), en segundos.
  • multiBroadcastTag - La etiqueta única para emisiones simultáneas (si se ha establecido una).
  • broadcastUrls — En el método «stop», este valor se establece en «null».

La respuesta HTTP tendrá uno de los siguientes códigos de estado:

  • 200 — Éxito.
  • 400 — Solicitud no válida. Esta respuesta puede indicar que los datos de tu solicitud no son JSON válido.
  • 403 — Error de autenticación.
  • 404 — No se ha encontrado la emisión (con el ID especificado) o ya ha finalizado.
  • 500 — Error del servidor de OpenTok.

Ejemplo

curl -i \
-X POST \
-H X-OPENTOK-AUTH:JWT_TOKEN \
https://api.opentok.com/v2/project/API_KEY/broadcast/BROADCAST_ID/stop

Lista de retransmisiones en directo

Utiliza este método para obtener información sobre las retransmisiones que están en curso y las que ya han comenzado. Las retransmisiones finalizadas no se incluyen en la lista.

Solicitud HTTP GET para la difusión

Envía una solicitud HTTP GET a la siguiente URL:

https://api.opentok.com/v2/project/<apiKey>/broadcast

Sustituir <apiKey> con tu clave API de OpenTok.

Se aceptan los siguientes parámetros de consulta:

  • offset (opcional) — El desplazamiento inicial en la lista de emisiones existentes
  • count (opcional, valor por defecto: 50, máximo: 1000) — El número de transmisiones que se van a recuperar a partir del desplazamiento
  • sessionId (opcional): Recuperar únicamente las transmisiones correspondientes a un ID de sesión determinado

Propiedades del encabezado GET

Autentifica esta llamada a la API utilizando un encabezado HTTP personalizado — X-OPENTOK-AUTH — configurado como un token web JSON. Véase Autenticación.

Respuesta

Los datos sin procesar de la respuesta HTTP, con código de estado 200, son un mensaje codificado en JSON con el siguiente formato:

{
  "count" : 2,
  "items" : [
    {
      "id": "1748b707-0a81-464c-9759-c46ad10d3734",
      "sessionId": "2_MX4xMDBfjE0Mzc2NzY1NDgwMTJ-TjMzfn4",
      "projectId": 100,
      "createdAt": 1437676551000,
      "updatedAt": 1437676551000,
      "resolution": "640x480",
      "broadcastUrls": {
        "hls" : "http://server/fakepath/playlist.m3u8",
        "hlsStatus": "live",
        "rtmp": {
          "foo": {
            "serverUrl": "rtmps://myfooserver:443/myfooapp",
            "streamName": "myfoostream",
            "status": "started"
          },
          "bar": {
            "serverUrl": "rtmp://mybarserver:443/mybarapp",
            "streamName": "mybarstream",
            "status": "live"
          }
        }
      }
      "status": "started",
      "streamMode" : "manual",
      "streams" : []
    }, {
      "id": "1c46ad10-0a81-464c-9759-748b707d3734",
      "sessionId": "2_MX2NzY1NDgwMTJ4xMDBfjE0Mzc-Tfn4jMz",
      "projectId": 100,
      "createdAt": 1437676853000,
      "updatedAt": 1437676853000,
      "resolution": "640x480",
      "broadcastUrls": {
        "hls" : "http://server/fakepath2/playlist.m3u8",
        "hlsStatus": "live",
        "rtmp": {
          "foo": {
            "serverUrl": "rtmp://myfooserver:443/myfooapps",
            "streamName": "myfoostreams",
            "status": "live"
          }
        }
      },
      "settings": {
        "hls": {
          "dvr": false,
          "lowLatency": false
        }
      },
      "status": "started",
      "streamMode" : "auto"
    }
  ]
}

El objeto JSON incluye las siguientes propiedades:

  • count — El número total de emisiones que aparecen en los resultados.
  • items — Una matriz de objetos que definen cada emisión recuperada. Las emisiones aparecen ordenadas de más reciente a más antigua en el conjunto devuelto.

Cada objeto de emisión (elemento) tiene las siguientes propiedades:

  • id — El identificador único de la emisión

  • sessionId — El ID de sesión de OpenTok

  • projectId — Tu clave de API de OpenTok

  • createdAt — La hora a la que comenzó la emisión, expresada en milisegundos desde la época Unix (1 de enero de 1970, 00:00:00 UTC)

  • updatedAt — Para este método GET, esta marca de tiempo coincide con la marca de tiempo «createdAt».

  • resolution — La resolución de la emisión (ya sea «640x480», «1280x720», «1920x1080», «480x640», «720x1280» o «1080x1920»).

  • status — El estado de la emisión. Este método solo devuelve emisiones cuyo estado esté establecido en "started".

  • maxDuration — La duración máxima de la emisión (si se ha establecido alguna), en segundos.

  • multiBroadcastTag - La etiqueta única para emisiones simultáneas (si se ha establecido una).

  • broadcastUrls - Detalles sobre los flujos de difusión HLS y RTMP.

    En el caso de un flujo HLS, la URL se proporciona como la dirección hls propiedad. Consulta el Guía para desarrolladores de retransmisiones en directo de OpenTok Para obtener más información sobre cómo utilizar esta URL. El hlsStatus es una de las siguientes:

    • "connecting" — El servidor de OpenTok está iniciando los transcodificadores. Este es el estado inicial.
    • "ready" — El servidor de OpenTok se ha inicializado correctamente, pero la CDN no está reproduciendo el contenido multimedia.
    • "live" — El servidor de OpenTok se ha inicializado correctamente y la CDN está reproduciendo el contenido multimedia.
    • "ended" — La transmisión de la fuente ha finalizado. Si el DVR está activado y se solicita contenido pregrabado, el estado pasará a live".
    • "error" — Se ha producido un error en la plataforma OpenTok.

    Para cada transmisión RTMP, se indican la URL del servidor RTMP y el nombre de la transmisión, junto con el estado de la transmisión RTMP. El status es una de las siguientes:

    • connecting — La plataforma OpenTok está conectándose al servidor RTMP remoto. Este es el estado inicial, y es el estado en el que se encuentra al iniciar la sesión cuando no hay transmisiones publicadas en ella. Pasa a «en directo» cuando hay transmisiones (o cambia a uno de los demás estados).
    • live — La plataforma OpenTok se ha conectado correctamente al servidor RTMP remoto y el contenido multimedia se está transmitiendo.
    • offline — La plataforma OpenTok no ha podido conectarse al servidor RTMP remoto. Esto se debe a que el servidor no está disponible o a un error en el establecimiento de la conexión RTMP. Entre las causas se incluyen conexiones RTMP rechazadas, Applications RTMP inexistentes, nombres de transmisión rechazados, errores de autenticación, etc. Comprueba que el servidor esté en línea y que hayas introducido la URL del servidor y el nombre de la transmisión correctos.
    • error — Se ha producido un error en la plataforma OpenTok.

  • settings - Más detalles sobre el flujo de difusión HLS. Este settings objeto incluye un hls propiedad con las siguientes características:

  • streamMode - Si todos los flujos se incluyen en la emisión ("auto") o bien seleccionas las transmisiones que quieres incluir en la emisión ("manual"). Véase Selección de las transmisiones que se incluirán en una retransmisión en directo.

  • streams — Para una emisión con "manual" streamMode y un status ajustado a "started", se trata de una matriz de objetos que corresponden a las transmisiones que se están emitiendo en este momento. Cada objeto de la matriz incluye las siguientes propiedades:

    • streamId — El identificador de la transmisión incluida en la emisión.
    • hasAudio — Si el audio de la transmisión se incluye en la emisión.
    • hasVideo - Si el vídeo del flujo se incluye en la emisión.

La respuesta HTTP tendrá uno de los siguientes códigos de estado:

  • 200 — Éxito
  • 403 — Error de autenticación
  • 500 — Error del servidor de OpenTok

Ejemplos

Lista de todas las emisiones (hasta 50):

curl -i \
  -X GET \
  -H X-OPENTOK-AUTH:JWT_TOKEN \
  https://api.opentok.com/v2/project/API_KEY/broadcast

Lista de una serie de emisiones:

curl -i \
  -X GET \
  -H X-OPENTOK-AUTH:JWT_TOKEN \
  https://api.opentok.com/v2/project/API_KEY/broadcast?offset=200&count=100

Mostrar las transmisiones correspondientes a un ID de sesión específico:

SESSION_ID="1_MX40NTMyODc3Mn5-MTU1MDg3NDIHVXBxbkp3Qzd-fg"
curl -i \
  -X GET \
  -H X-OPENTOK-AUTH:JWT_TOKEN \
  https://api.opentok.com/v2/project/API_KEY/broadcast?sessionId=$SESSION_ID

Cómo obtener información sobre una retransmisión en directo

Utiliza este método para obtener información sobre una emisión que se está realizando en ese momento.

Solicitud HTTP GET para la difusión

Envía una solicitud HTTP GET a la siguiente URL:

https://api.opentok.com/v2/project/<apiKey>/broadcast/<broadcastId>

Sustituir <apiKey> con tu clave API de OpenTok. Sustituye <broadcastId> con el ID de la retransmisión. El ID de la retransmisión se obtiene al iniciar una retransmisión.

Nota: Anteriormente, esta URL REST utilizaba /partner (que ahora está en desuso) en lugar de /project.

Propiedades del encabezado GET

Autentifica esta llamada a la API utilizando un encabezado HTTP personalizado — X-OPENTOK-AUTH — establecido como un token web JSON. Véase Autenticación.

Respuesta

Los datos sin procesar de la respuesta HTTP, con código de estado 200, son un mensaje codificado en JSON con el siguiente formato:

{
  "id": "1748b707-0a81-464c-9759-c46ad10d3734",
  "sessionId": "2_MX4xMDBfjE0Mzc2NzY1NDgwMTJ-TjMzfn4",
  "projectId": 100,
  "createdAt": 1437676551000,
  "updatedAt": 1437676551000,
  "resolution": "640x480",
  "streamMode" : "auto",
  "streams" : [],
  "broadcastUrls": {
    "hls" : "http://server/fakepath/playlist.m3u8",
    "hlsStatus": "live",
    "rtmp": {
      "foo": {
        "serverUrl": "rtmps://myfooserver:443/myfooapp",
        "streamName": "myfoostream",
        "status": "live"
      },
      "bar": {
        "serverUrl": "rtmp://mybarserver:443/mybarapp",
        "streamName": "mybarstream",
        "status": "live"
      }
    }
  },
  "settings": {
    "hls": {
      "dvr": false,
      "lowLatency": false
    }
  },
  "status": "live"
}

El objeto JSON incluye las siguientes propiedades:

  • id — El identificador único de la emisión

  • sessionId — El ID de sesión de OpenTok

  • projectId — Tu clave de API de OpenTok

  • createdAt — La hora a la que comenzó la emisión, expresada en milisegundos desde la época Unix (1 de enero de 1970, 00:00:00 UTC)

  • updatedAt - Para este método GET, esta marca de tiempo coincide con la marca de tiempo createdAt.

  • resolution — La resolución de la emisión (ya sea «640x480», «1280x720», «1920x1080», «480x640», «720x1280» o «1080x1920»).

  • status — El estado de la emisión: o bien "started" o "stopped".

  • broadcastUrls - Detalles sobre los flujos de difusión HLS y RTMP.

    En el caso de un flujo HLS, la URL se proporciona como la dirección hls propiedad. Véase el Guía para desarrolladores de retransmisiones en directo de OpenTok para más información sobre cómo utilizar esta URL. En hlsStatus es una de las siguientes:

  • "connecting" — El servidor de OpenTok está iniciando los transcodificadores. Este es el estado inicial.
  • "ready" — El servidor de OpenTok se ha inicializado correctamente, pero la CDN no está reproduciendo el contenido multimedia.
  • "live" — El servidor de OpenTok se ha inicializado correctamente y la CDN está reproduciendo el contenido multimedia.
  • "ended" - El flujo fuente ha finalizado. Si el DVR está activado y se solicitan medios pregrabados, el estado cambiará a "live".
  • "error" — Se ha producido un error en la plataforma OpenTok.

Para cada transmisión RTMP, se indican la URL del servidor RTMP y el nombre de la transmisión, junto con el estado de la transmisión RTMP.

  • status — El estado de la transmisión RTMP. Realiza consultas con frecuencia para comprobar si hay actualizaciones de estado. Esta propiedad puede tomar uno de los siguientes valores:

    • connecting — La plataforma OpenTok está estableciendo conexión con el servidor RTMP remoto. Este es el estado inicial, y es el estado en el que se encuentra si se inicia la sesión cuando no hay transmisiones publicadas en ella. Pasa a «en directo» cuando hay transmisiones (o cambia a alguno de los otros estados).
    • live — La plataforma OpenTok se ha conectado correctamente al servidor RTMP remoto y el contenido multimedia se está transmitiendo.
    • offline — La plataforma OpenTok no ha podido conectarse al servidor RTMP remoto. Esto se debe a que el servidor no está disponible o a un error en el establecimiento de la conexión RTMP. Entre las causas se incluyen conexiones RTMP rechazadas, Applications RTMP inexistentes, nombres de transmisión rechazados, errores de autenticación, etc. Comprueba que el servidor esté en línea y que hayas introducido correctamente la URL del servidor y el nombre de la transmisión.
    • error — Se ha producido un error en la plataforma OpenTok.

  • settings - Más detalles sobre el flujo de difusión HLS. Este properties incluye un objeto hls propiedad con las siguientes características:

  • multiBroadcastTag - La etiqueta única para emisiones simultáneas (si se ha establecido una).

  • streamMode - Si todos los flujos se incluyen en la emisión ("auto") o seleccione los flujos que desea incluir en la emisión ("manual"). Véase Selección de los flujos que se incluirán en una retransmisión en directo.

  • streams - Una matriz de objetos correspondientes a los flujos que se están emitiendo actualmente. Esto sólo se establece para una emisión con el parámetro status ajustado a "started" y el streamMode ajustado a "manual". Cada objeto de la matriz incluye las siguientes propiedades:

    • streamId — El identificador de la transmisión incluida en la emisión.
    • hasAudio — Si el audio de la transmisión se incluye en la emisión.
    • hasVideo - Si el vídeo del flujo se incluye en la emisión.

La respuesta HTTP tendrá uno de los siguientes códigos de estado:

  • 200 — Éxito
  • 400 — Solicitud no válida
  • 403 — Error de autenticación
  • 404 — No se ha encontrado ninguna emisión que coincida (con el ID especificado)
  • 500 — Error del servidor de OpenTok

Ejemplo

curl -i \
  -X GET \
  -H X-OPENTOK-AUTH:JWT_TOKEN \
  https://api.opentok.com/v2/project/API_KEY/broadcast/BROADCAST_ID

Cambiar dinámicamente el tipo de presentación durante una retransmisión en directo

Puedes cambiar dinámicamente el tipo de diseño de una retransmisión en directo.

Para obtener más información sobre las retransmisiones en directo de OpenTok, consulta la Guía para desarrolladores de retransmisiones.

HTTP PUT para la difusión

Envía una solicitud HTTP PUT a la siguiente URL:

https://api.opentok.com/v2/project/<apiKey>/broadcast/<broadcastId>/layout

Sustituir <apiKey> con tu clave API de OpenTok.

Sustituir <broadcastId> con el identificador de emisión.

Propiedades del encabezado PUT

Fije el Content-Type encabezado a application/json.

Autentifica esta llamada a la API utilizando un encabezado HTTP personalizado — X-OPENTOK-AUTH — establecido como un token web JSON. Véase Autenticación.

Datos PUT

Incluye un objeto JSON con el siguiente formato como contenido del cuerpo de la solicitud:

{
  "type": "custom",
  "stylesheet": "the layout stylesheet (only used with type == custom)",
  "screenshareType": "the layout type to use when there is a screen-sharing stream (optional)"
}

El objeto JSON incluye las siguientes propiedades:

  • tipo (Cadena) — El tipo de diseño de la emisión. Los valores válidos son "bestFit" (ajuste óptimo), "custom" (personalizado), "horizontalPresentation" (presentación horizontal), "pip" (imagen en imagen) y "verticalPresentation" (presentación vertical)). Si se especifica un "custom" tipo de diseño, establezca el stylesheet propiedad en la hoja de estilos. (Para otros tipos de diseño, no establezcas la stylesheet propiedad.) Para obtener más información, consulta Configuración del diseño de vídeo para la función de retransmisión en directo de OpenTok.
  • hoja de estilo (Cadena) — Opcional. Indícalo solo si configuras el type propiedad a "custom". Ajuste el stylesheet propiedad en la hoja de estilos. (Para otros tipos de diseño, no establezcas la stylesheet propiedad.) Para obtener más información, consulta Definición de diseños personalizados.
  • tipo de pantalla compartida (Cadena) — Opcional. El tipo de diseño que se utilizará cuando haya una transmisión compartida de pantalla en la sesión. Ten en cuenta que, para utilizar esta propiedad, debes establecer la type a "bestFit" y dejar la propiedad stylesheet Propiedad no definida. Para obtener más información, consulta Tipos de diseño para pantalla compartida.

Al especificar un tipo de diseño distinto al de «Best Fit», asegúrate de aplicar las clases de diseño adecuadas a las transmisiones de la sesión de OpenTok (véase Asignación de clases de diseño de retransmisiones en directo a las retransmisiones de OpenTok.

Respuesta

La respuesta HTTP tendrá uno de los siguientes códigos de estado:

  • 200 — Éxito.
  • 400 — Solicitud no válida. Esta respuesta puede indicar que los datos de tu solicitud no cumplen con el formato JSON válido. También puede indicar que has introducido opciones de diseño no válidas.
  • 403 — Error de autenticación.
  • 500 — Error del servidor de OpenTok.

Ejemplo

curl -i \
   -X PUT \
   -H X-OPENTOK-AUTH:JWT_TOKEN \
   -H "Content-Type:application/json" \
   -D {\"type\":"verticalPresentation"} \
   https://api.opentok.com/v2/project/$apiKey/broadcast/$broadcastId/layout

Cambiar las clases de diseño de la retransmisión en directo para una retransmisión de OpenTok

Utiliza este método para cambiar las clases de diseño de una transmisión de OpenTok. Las clases de diseño definen cómo se muestra la transmisión en el diseño de la emisión. Para obtener más información, consulta Asignación de clases de diseño de retransmisiones en directo a las retransmisiones de OpenTok.

HTTP PUT para la transmisión

Envía una solicitud HTTP PUT a la siguiente URL:

https://api.opentok.com/v2/project/<apiKey>/session/<sessionId>/stream

Sustituir <apiKey> con tu clave API de OpenTok.

Sustituir <sessionId> con el ID de sesión.

Propiedades del encabezado PUT

Fije el Content-Type encabezado a application/json.

Autentifica esta llamada a la API utilizando un encabezado HTTP personalizado — X-OPENTOK-AUTH — establecido como un token web JSON. Véase Autenticación.

Datos PUT

Incluye un objeto JSON con el siguiente formato como contenido del cuerpo de la solicitud:

{
  "items": [
    {
      "id": "8b732909-0a06-46a2-8ea8-074e64d43422",
      "layoutClassList": ["full"]
    }
  ]
}

El objeto JSON incluye un items matriz de objetos. Cada objeto define las clases de diseño que se deben asignar a un flujo y contiene las siguientes propiedades:

  • id (Cadena) — El identificador del flujo.
  • layoutClassList (Matriz) — Una matriz de clases de diseño (todas ellas cadenas) para el flujo.

Puedes actualizar la lista de clases de diseño para varias secuencias pasando varios objetos JSON en el items matriz.

Respuesta

La respuesta HTTP tendrá uno de los siguientes códigos de estado:

  • 200 — Éxito.
  • 400 — Solicitud no válida. Esta respuesta puede indicar que los datos de tu solicitud no cumplen con el formato JSON válido. También puede indicar que has introducido opciones de diseño no válidas.
  • 403 — Error de autenticación.
  • 500 — Error del servidor de OpenTok.

Ejemplo

curl -i \
   -X PUT \
   -H X-OPENTOK-AUTH:JWT_TOKEN \
   -H "Content-Type:application/json" \
   -D {\"streamId\":STREAM_ID,\"layoutClassList\":[\"CLASS_NAME\"]} \
   https://api.opentok.com/v2/project/$apiKey/session/$sessionId

Selección de los flujos que se incluirán en una retransmisión en directo

Utiliza este método para modificar las transmisiones incluidas en una emisión en directo que se haya iniciado con el streamMode ajustado a "manual" (véase Iniciar una retransmisión en directo).

El compositor de emisiones incluye flujos añadidos basados en normas de priorización de flujos.

HTTP PATCH a broadcast/streams

Envía una solicitud HTTP PATCH a la siguiente URL:

https://api.opentok.com/v2/project/<apiKey>/broadcast/<broadcastId>/streams

Sustituir <apiKey> con tu clave API de OpenTok. Sustituye <broadcastId> con el identificador de emisión.

Propiedades del encabezado PATCH

Fije el Content-Type encabezado a application/json.

Autentifica esta llamada a la API utilizando un encabezado HTTP personalizado — X-OPENTOK-AUTH — configurado como un token web JSON. Véase Autenticación.

Datos de PATCH

Para añadir una transmisión a la emisión, incluye un objeto JSON con el siguiente formato como contenido del cuerpo de la solicitud:

{
  "addStream": "12312312-3811-4726-b508-e41a0f96c68f",
  "hasAudio": true,
  "hasVideo": false
}

El objeto JSON contiene las siguientes propiedades:

  • addStream (Cadena) — El identificador del flujo.
  • hasAudio (Booleano, opcional) — Indica si la retransmisión debe incluir el audio de la transmisión (true, el valor por defecto) o no (false).
  • hasVideo (Booleano, opcional) — Indica si la retransmisión debe incluir el vídeo de la emisión (true, el valor por defecto) o no (false).

Puedes llamar al método varias veces con addStream configurados con el mismo ID de transmisión, para activar o desactivar el audio o el vídeo de la transmisión durante la emisión.

Si configuras ambos hasAudio y hasVideo a false, recibirás una respuesta de error.

Para evitar que una transmisión se incluya en la emisión, incluye un objeto JSON con el siguiente formato como contenido del cuerpo de la solicitud:

{
  "removeStream": "12312312-3811-4726-b508-e41a0f96c68f"
}

Fije el removeStream propiedad al ID del flujo.

Respuesta

La respuesta HTTP tendrá uno de los siguientes códigos de estado:

  • 204 — Éxito (sin contenido).
  • 400 — Solicitud no válida. Esta respuesta puede indicar que los datos proporcionados en tu solicitud no son un JSON válido, o que la solicitud no se ha podido completar porque la difusión se inició con streamMode ajustado a "auto", que no admite la manipulación de flujos.
  • 403 — Error de autenticación.
  • 404 — No se ha encontrado la emisión o la retransmisión.
  • 500 — Error del servidor de OpenTok.

Ejemplos

Añadir una transmisión a una emisión:

curl -i \
   -X PATCH \
   -H X-OPENTOK-AUTH:$JWT_TOKEN \
   -H "Content-Type:application/json" \
   -D {\"addStream\":$STREAM_ID} \
   https://api.opentok.com/v2/project/$apiKey/broadcast/$BROADCAST_ID/streams

Cómo eliminar el vídeo de una retransmisión (pero mantener el audio):

curl -i \
   -X PATCH \
   -H X-OPENTOK-AUTH:$JWT_TOKEN \
   -H "Content-Type:application/json" \
   -D {\"addStream\":\"$STREAM_ID\", \"hasAudio\":true, \"hasVideo\":false } \
   https://api.opentok.com/v2/project/$apiKey/broadcast/$BROADCAST_ID/streams

Cómo eliminar una transmisión de una emisión:

curl -i \
   -X PATCH \
   -H X-OPENTOK-AUTH:$JWT_TOKEN \
   -H "Content-Type:application/json" \
   -D {\"removeStream\":\"$STREAM_ID\"} \
   https://api.opentok.com/v2/project/$apiKey/broadcast/$BROADCAST_ID/streams

Iniciar subtítulos en directo

Utiliza este método para activar los subtítulos en tiempo real en una sesión de OpenTok.

La duración máxima permitida es de 4 horas; transcurrido este tiempo, los subtítulos de audio se detendrán sin que ello afecte a la sesión de OpenTok en curso. Las sesiones de subtítulos también finalizarán 60 segundos después de que el último cliente se desconecte. Se enviará un evento a tu URL de devolución de llamada, si se ha facilitado al iniciar los subtítulos.

Cada sesión de OpenTok solo admite una sesión de subtitulado de audio.

Para obtener más información sobre la función «Subtítulos en directo», consulta el Guía para desarrolladores de Live Captions.

Solicitud HTTP POST para iniciar los subtítulos en directo

Envía una solicitud HTTP POST a la siguiente URL:

https://api.opentok.com/v2/project/<apiKey>/captions

Sustituir <apiKey> con tu clave API de OpenTok.

Fije el Content-Type encabezado a application/json.

Autentifica esta llamada a la API utilizando un encabezado HTTP personalizado — X-OPENTOK-AUTH — establecido como un token web JSON. Véase Autenticación.

Datos POST

Incluye un objeto JSON con el siguiente formato como contenido del cuerpo de la solicitud:

{
  "sessionId": "<session-id>",
  "token": "A valid OpenTok token with the role set to moderator",
  "languageCode": "en-US",
  "maxDuration": 1800,
  "partialCaptions": true,
}

El objeto JSON incluye las siguientes propiedades:

  • sessionId (Cadena) — El identificador de la sesión de OpenTok. El audio de los emisores que transmiten en esta sesión se utilizará para generar los subtítulos.
  • token(Cadena de caracteres)— Un token válido de OpenTok con el rol establecido en «Moderador».
  • languageCode (Cadena) — (Opcional) El código BCP-47 del idioma utilizado por «Live Captions» (véase esta lista de idiomas admitidos). El valor por defecto es «en-US».
  • maxDuration (Número entero) — (Opcional) La duración máxima de los subtítulos de audio, en segundos. El valor por defecto es 14 400 segundos (4 horas), que es la duración máxima permitida. El valor mínimo para maxDuration es 300 (300 segundos, es decir, 5 minutos).
  • partialCaptions (Booleano) — (Opcional) Indica si se debe activar esta opción para acelerar la generación de subtítulos, a costa de un cierto grado de imprecisión. El valor por defecto es true.

Respuesta

Si la operación se realiza correctamente, los datos sin procesar de la respuesta HTTP, con código de estado 200, son un mensaje codificado en JSON con el siguiente formato:

{
  "captionsId": "7c0680fc-6274-4de5-a66f-d0648e8d3ac2"
}

El objeto JSON incluye la siguiente propiedad:

  • captionsId — El identificador único de la sesión de subtitulado de audio.

La respuesta HTTP tendrá uno de los siguientes códigos de estado:

  • 202 — Aceptado.
  • 400 — Solicitud incorrecta; la respuesta puede indicar un error relacionado con los datos de la solicitud que no son aceptables.
  • 403 — Error de autenticación. El dato facilitado X-OPENTOK-AUTH puede que no sea válido.
  • 409 — Ya han comenzado los subtítulos en directo de esta sesión de OpenTok.
  • 500 — Error de la plataforma Vonage Video API.

Ejemplo


curl -X POST  \
-H 'X-OPENTOK-AUTH: ' \
-H 'Content-Type: application/json' \
-d '{
  "sessionId": "<valid-session-id>",
  "token": "<valid-token>",
}'
 https://api.opentok.com/v2/project/<apiKey>/captions

Desactivar los subtítulos en directo

Utiliza este método para desactivar los subtítulos en directo de una sesión.

Solicitud HTTP POST para detener los subtítulos en directo

Envía una solicitud HTTP POST a la siguiente URL:

POST https://api.opentok.com/v2/project/<apiKey>/captions/<captionsId>/stop

Sustituir <apiKey> con tu clave API de OpenTok. Sustituye <captionsId> con el ID devuelto en la respuesta de la API de subtítulos iniciales.

Autentifica esta llamada a la API utilizando un encabezado HTTP personalizado — X-OPENTOK-AUTH — establecido como un token web JSON. Véase Autenticación.

La respuesta HTTP tendrá uno de los siguientes códigos de estado:

  • 202 — Aceptado
  • 403 — Error de autenticación
  • 404 — No se ha encontrado ningún «captionsId» que coincida
  • 500 — Error de la plataforma Vonage Video API

Ejemplo

curl
  -X POST
  -H "Content-Type: application/json"
  -H "X-OPENTOK-AUTH:<valid-jwt-token>"
  https://api.opentok.com/v2/project/<apiKey>/captions/<captionsId>/stop;

Iniciar Experience Composer

Utiliza este método para crear un Experience Composer para una sesión de OpenTok. Para obtener más información, consulta el Guía para desarrolladores de Experience Composer.

POST HTTP para la representación

Envía una solicitud HTTP POST a la siguiente URL:

https://api.opentok.com/v2/project/<apiKey>/render

Sustituir <apiKey> con tu clave API de OpenTok.

Propiedades del encabezado POST

Fije el Content-Type encabezado a application/json.

Autentifica esta llamada a la API utilizando un encabezado HTTP personalizado — X-OPENTOK-AUTH — configurado como un token web JSON. Véase Autenticación.

Datos POST

Incluye un objeto JSON con el siguiente formato como contenido del cuerpo de la solicitud:

{
  "sessionId": "&lt;session-id&gt;",
  "token": "A valid OpenTok token",
  "url": "https://webapp.customer.com",
  "maxDuration": 1800,
  "resolution": "1280x720",
  "properties": {
    "name": "Composed stream for Live event #1"
  }
}

El objeto JSON incluye las siguientes propiedades:

  • sessionId (String) — El identificador de la sesión de OpenTok que incluirá la transmisión de Experience Composer.
  • token (cadena de caracteres) — Un token válido de OpenTok con el rol de «Publisher» y (opcionalmente) los datos de conexión que se asociarán a la transmisión de salida.
  • url (cadena de caracteres) — Una URL de acceso público gestionada por el cliente y capaz de generar el contenido que se va a mostrar sin intervención del usuario. La longitud mínima de la URL es de 15 caracteres y la máxima, de 2048 caracteres.
  • maxDuration (entero) — (Opcional) El tiempo máximo permitido para el Experience Composer, en segundos. Transcurrido este tiempo, se detendrá automáticamente si aún se está ejecutando. El valor máximo es 36 000 (10 horas), el valor mínimo es 60 (1 minuto) y el valor predeterminado es 7 200 (2 horas). Cuando finaliza el Experience Composer, su transmisión se retira de la publicación y se envía un evento a la URL de devolución de llamada, si se ha configurado en el Portal de la cuenta.
  • resolución (cadena de caracteres) — (Opcional) La resolución del Experience Composer, que puede ser «640x480» (SD horizontal), «480x640» (SD vertical), «1280x720» (HD horizontal), «720x1280» (HD vertical), «1920x1080» (FHD horizontal) o «1080x1920» (FHD vertical). Por defecto, esta resolución es «1280x720» (HD horizontal, la predeterminada).
  • propiedades (Objeto) — (Opcional) La configuración inicial de las propiedades del Publisher para el flujo de salida compuesto. El objeto de propiedades contiene el nombre de la clave (cadena de caracteres), que sirve como nombre del flujo de salida compuesto que se publica en la sesión. El nombre debe tener una longitud mínima de 1 y una máxima de 200.

Respuesta

Los datos sin procesar de la respuesta HTTP, con código de estado 200, son un mensaje codificado en JSON con el siguiente formato:

{
  "id": "1248e7070b81464c9789f46ad10e7764",
  "sessionId": "2_MX4xMDBfjE0Mzc2NzY1NDgwMTJ-TjMzfn4",
  "projectId": "e2343f23456g34709d2443a234",
  "createdAt": 1437676551000,
  "updatedAt": 1437676551000,
  "callbackUrl": "https://callback.customer.com/",
  "name": "Composed-HD-Customer-1",
  "url": "https://webapp.customer.com",
  "resolution": "1280x720",
  "status": "starting",
  "streamId": "e32445b743678c98230f238" 
}

El objeto JSON incluye las siguientes propiedades:

  • id — El identificador único del Experience Composer.
  • sessionId — El identificador de sesión de OpenTok.
  • projectId — Tu clave de API de OpenTok.
  • createdAt — La hora en que se inició Experience Composer, expresada en milisegundos desde la época Unix (1 de enero de 1970, 00:00:00 UTC).
  • updatedAt — Se trata de la marca de tiempo UNIX correspondiente a la última actualización del estado de Experience Composer. En este método de inicio, esta marca de tiempo coincide con la marca de tiempo createdAt.
  • callbackUrl — La URL de devolución de llamada para los eventos de Experience Composer (si se ha configurado alguna). Véase Configuración de las retrollamadas.
  • nombre — El nombre del Experience Composer (si se ha especificado alguno).
  • url — Una URL de acceso público gestionada por el cliente y capaz de generar el contenido que se va a mostrar sin intervención del usuario.
  • resolución — La resolución del Experience Composer (ya sea «640x480», «480x640», «1280x720», «720x1280», «1920x1080» o «1080x1920»).
  • estado — En este método de inicio, se establece en «iniciando».
  • streamId — El identificador de la secuencia compuesta que se está publicando.

La respuesta HTTP tendrá uno de los siguientes códigos de estado:

  • 202 — Éxito.

  • 400 — Solicitud no válida. Esta respuesta puede indicar que los datos de tu solicitud no son válidos en formato JSON. Puede incluir un código de error; a continuación se enumeran algunos de ellos:

    • 50001 — Estructura de la URL de la aplicación no válida.
    • 50002 — No se puede acceder a la URL de la aplicación.
    • 50005 — Se ha especificado un valor «maxDuration» no válido.
    • 50006 — Se ha proporcionado una resolución no válida.
    • 50007 — Se ha introducido un nombre de flujo no válido.
    • 50008 — Se ha introducido un «sessionId» no válido.

  • 403 — Error de autenticación. Puede incluir un código de error; a continuación se enumeran algunos de ellos:

    • 10001 - Formato o firma del token no válidos.
    • 10002 - Token no autorizado.
    • 10003 - Formato de autenticación del socio no válido.
    • 10004 - Autenticación de socio no autorizada.
    • 10007 - El token no coincide con el ID de sesión.
    • 10012 - Token caducado.

  • 429 — Demasiadas solicitudes. Has superado el límite de uso de Experienced Composer. La respuesta incluirá un código de error 50004.

  • 500 — Error de la plataforma Vonage Video API.

Ejemplo

  curl 
  -X POST 
  -H "Content-Type: application/json" 
  -H "X-OPENTOK-AUTH:<valid-jwt-token>"  
  -d '{"url": "&lt;valid-url-to-be-rendered&gt;", "sessionId": "&lt;valid-session-id&gt;", "token": "&lt;valid-token&gt;", "projectId": "&lt;valid-project-id&gt;"}'
  https://api.opentok.com/v2/project/&lt;apiKey&gt;/render

Cómo obtener información sobre un «Experience Composer»

Utiliza este método para obtener información detallada sobre un Experience Composer.

Solicitud HTTP GET para generar el contenido

Envía una solicitud HTTP GET a la siguiente URL:

https://api.opentok.com/v2/project/<apiKey>/render/<experienceComposerId>

Sustituir <apiKey> con tu clave API de OpenTok. Sustituye <experienceComposerId> con el ID del Experience Composer. El ID del Experience Composer se obtiene al iniciar un Experience Composer.

Propiedades del encabezado GET

Autentifica esta llamada a la API utilizando un encabezado HTTP personalizado — X-OPENTOK-AUTH — configurado con un token web JSON. Consulta Autenticación.

Respuesta

Los datos sin procesar de la respuesta HTTP, con código de estado 200, son un mensaje codificado en JSON con el siguiente formato:

{
  "id":"80abaf0d-25a3-4efc-968f-6268d620668d",
  "sessionId":"1_MX4yNzA4NjYxMn5-MTU0NzA4MDUyMTEzNn5sOXU5ZnlWYXplRnZGblV4RUo3dXJpZk1-fg",
  "projectId":"27086612",
  "createdAt":1547080532099,
  "updatedAt":1547080532199,
  "callbackUrl": "https://callback.customer.com/",
  "name": "Composed-HD-Customer-1",
  "url": "https://webapp.customer.com",
  "resolution": "480x640",
  "status":"failed",
  "reason":"Could not load URL"
}

El objeto JSON incluye las siguientes propiedades:

  • id — El identificador único del Experience Composer.
  • sessionId — El identificador de sesión de OpenTok.
  • projectId — Tu clave de API de OpenTok.
  • createdAt — La hora en que se inició Experience Composer, expresada en milisegundos desde la época Unix (1 de enero de 1970, 00:00:00 UTC).
  • updatedAt — En este método GET, esta marca de tiempo coincide con la marca de tiempo createdAt.
  • callbackUrl — La URL de devolución de llamada para los eventos de URL Experience Composer (si se ha configurado alguna). Véase Configuración de las retrollamadas.
  • nombre — El nombre del Experience Composer (si se ha especificado alguno).
  • url — Una URL de acceso público gestionada por el cliente y capaz de generar el contenido que se va a mostrar sin necesidad de intervención por parte del usuario.
  • resolución — La resolución del Experience Composer (ya sea «640x480», «1280x720», «480x640» o «720x1280»).
  • estado — El estado del Experience Composer. Consulta con frecuencia para comprobar si hay novedades en el estado. Esta propiedad puede tomar uno de los siguientes valores:
    • «iniciando» — La plataforma de la Video API de Vonage está conectándose a la aplicación remota en la URL facilitada. Este es el estado inicial.
    • «iniciado» — La plataforma de la Video API de Vonage se ha conectado correctamente al servidor de aplicaciones remoto, y está publicando la vista web en una transmisión de OpenTok.
    • «detener» — El Experience Composer se ha detenido.
    • «falló»: se ha producido un error y Experience Composer no ha podido continuar. Puede ocurrir al iniciar el programa si el servidor de OpenTok no puede conectarse al servidor de aplicaciones remoto o volver a publicar la transmisión. También puede ocurrir en cualquier momento durante el proceso debido a un error en la plataforma de la Video API de Vonage.
  • motivo — El campo «motivo» solo está disponible cuando el estado es «detenido» o «fallido». Si el estado es «detenido», el campo «motivo» mostrará «Se ha superado la duración máxima» o «Se ha solicitado la detención ». Si el estado es «fallido», el motivo mostrará un mensaje de error más específico.
  • streamId — El identificador de la transmisión compuesta que se está publicando. El streamId no está disponible cuando el estado es «starting» y es posible que tampoco lo esté cuando el estado es «failed».

La respuesta HTTP tendrá uno de los siguientes códigos de estado:

  • 200 — Éxito
  • 400 — Solicitud no válida
  • 403 — Error de autenticación
  • 404 — No se ha encontrado ningún compositor de Experience que coincida con el ID especificado.
  • 500 — Error de la plataforma Vonage Video API.

Ejemplo

curl 
  -X GET 
  -H "X-OPENTOK-AUTH:&lt;valid-jwt-token&gt;"
  https://api.opentok.com/v2/project/&lt;apiKey&gt;/render/&lt;experienceComposerId&gt;

Cómo obtener una lista de compositores con experiencia

Utiliza este método para obtener una lista de los «Experience Composers» asociados a un proyecto.

Solicitud HTTP GET para generar el contenido

Envía una solicitud HTTP GET a la siguiente URL:

https://api.opentok.com/v2/project/<apiKey>/render

Sustituir <apiKey> con tu clave API de OpenTok. Se pueden añadir los siguientes parámetros de consulta opcionales:

  • desplazamiento — El desplazamiento inicial de la lista de «Experience Composers». El valor por defecto es 0.
  • count — El número de «Experience Composers» que se van a recuperar a partir del desplazamiento indicado. El valor por defecto es 50 y el máximo es 1000.

Propiedades del encabezado GET

Autentifica esta llamada a la API utilizando un encabezado HTTP personalizado — X-OPENTOK-AUTH — configurado con un token web JSON. Consulta Autenticación.

Respuesta

Los datos sin procesar de la respuesta HTTP, con código de estado 200, son un mensaje codificado en JSON con el siguiente formato:

{
  "count":2,
  "items":[
    {
      "id":"80abaf0d-25a3-4efc-968f-6268d620668d",
      "sessionId":"1_MX4yNzA4NjYxMn5-MTU0NzA4MDUyMTEzNn5sOXU5ZnlWYXplRnZGblV4RUo3dXJpZk1-fg",
      "projectId":"27086612",
      "createdAt":1547080532099,
      "updatedAt":1547080532099,
      "callbackUrl": "callback.customer.com/",
      "name": "Composed-HD-Customer-1",
      "url": "https://webapp.customer.com",
      "resolution": "1280x720",
      "status": "started",
      "streamId": "d2334b35690a92f78945"
    },
    {
      "id":"d95f6496-df6e-4f49-86d6-832e00303602",
      "sessionId":"2_MX4yNzA4NjYxMn5-MTU0NzA4MDUwMDc2MH5STWRiSE1jZjVoV3lBQU9nN2JuNElUV3V-fg",
      "projectId":"27086612",
      "createdAt":1547080511760,
      "updatedAt":1547080518965,
      "callbackUrl": "https://callback.customer.com/",
      "name": "Composed-HD-Customer-2",
      "url": "https://webapp2.customer.com",
      "resolution": "1280x720",
      "status":"stopped",
      "streamId": "d2334b35690a92f78945",
      "reason":"Max duration exceeded"
    }
  ]
}

El objeto JSON incluye las siguientes propiedades:

  • count — El número total de «Experience Composers».
  • elementos: la matriz que contiene los «Experience Composers» recuperados. Cada elemento «Experience Composer» incluye las siguientes propiedades:
    • id — El identificador único del Experience Composer.
    • sessionId — El identificador de sesión de OpenTok.
    • projectId — Tu clave de API de OpenTok.
    • createdAt — La hora en que se inició Experience Composer, expresada en milisegundos desde la época Unix (1 de enero de 1970, 00:00:00 UTC).
    • updatedAt — En este método GET, esta marca de tiempo coincide con la marca de tiempo createdAt.
    • callbackUrl — La URL de devolución de llamada para los eventos de Experience Composer (si se ha configurado alguna). Véase Configuración de las retrollamadas.
    • nombre — El nombre del Experience Composer (si se ha especificado alguno).
    • url — Una URL de acceso público gestionada por el cliente y capaz de generar el contenido que se va a mostrar sin necesidad de intervención por parte del usuario.
    • resolución — La resolución del Experience Composer (ya sea «640x480», «1280x720», «480x640» o «720x1280»).
    • estado — El estado del Experience Composer. Consulta con frecuencia para comprobar si hay novedades en el estado. Esta propiedad puede tomar uno de los siguientes valores:
      • «iniciando» — La plataforma de la Video API de Vonage está conectándose a la aplicación remota en la URL facilitada. Este es el estado inicial.
      • «iniciado» — La plataforma de la Video API de Vonage se ha conectado correctamente al servidor de aplicaciones remoto y está publicando la vista web en una transmisión de OpenTok.
      • «detener» — El Experience Composer se ha detenido.
      • «falló»: se ha producido un error y Experience Composer no ha podido continuar. Esto puede ocurrir al iniciar el programa si el servidor de OpenTok no puede conectarse al servidor de aplicaciones remoto o volver a publicar la transmisión. También puede ocurrir en cualquier momento durante el proceso debido a un error de la plataforma de la Video API de Vonage.
    • motivo — El campo «motivo» solo está disponible cuando el estado es «detenido» o «fallido». Si el estado es «detenido», el campo «motivo» contendrá «Duración máxima superada» o «Detenido solicitado». Si el estado es «fallido», el motivo contendrá un mensaje de error más específico.
    • streamId — El identificador de la transmisión compuesta que se está publicando. El streamId no está disponible cuando el estado es «starting» y es posible que tampoco lo esté cuando el estado es «failed».

La respuesta HTTP tendrá uno de los siguientes códigos de estado:

  • 200 — Éxito
  • 403 — Error de autenticación
  • 500 — Error de la plataforma Vonage Video API.

Ejemplo

curl 
  -X GET 
  -H "X-OPENTOK-AUTH:&lt;valid-jwt-token&gt;"
  https://api.opentok.com/v2/project/&lt;apiKey&gt;/render?count=2

Detener un «Experience Composer»

Utiliza este método para detener un Experience Composer de una sesión de OpenTok. Ten en cuenta que, de forma predeterminada, los Experience Composers se detienen automáticamente 2 horas después de su inicio. También puedes establecer un valor diferente para «maxDuration» al crear el Experience Composer. Cuando el Experience Composer finaliza, se envía un evento a la URL de devolución de llamada, si has he configurado uno para el proyecto.

HTTP DELETE para renderizar

Envía una solicitud HTTP DELETE a la siguiente URL:

https://api.opentok.com/v2/project/<apiKey>/render/<experienceComposerId>/

Sustituir <apiKey> con tu clave API de OpenTok. Sustituye <experienceComposerId> con el ID del Experience Composer que deseas detener. El ID del Experience Composer se obtiene de la respuesta recibida al iniciar un Experience Composer.

Propiedades del encabezado DELETE

Autentifica esta llamada a la API utilizando un encabezado HTTP personalizado — X-OPENTOK-AUTH — configurado con un token web JSON. Consulta Autenticación.

Respuesta

La respuesta HTTP tendrá uno de los siguientes códigos de estado:

  • 204 — Sin contenido.
  • 400 — Solicitud no válida.
  • 403 — Error de autenticación.
  • 404 — No se ha encontrado el «Experience Composer» (con el ID especificado) o ya se ha detenido.
  • 500 — Error de la plataforma Vonage Video API.

Ejemplo

curl 
  -X DELETE 
  -H "Content-Type: application/json" 
  -H "X-OPENTOK-AUTH:&lt;valid-jwt-token&gt;" 
  https://api.opentok.com/v2/project/&lt;apiKey&gt;/render/&lt;experienceComposerId&gt;/

Iniciar una conexión WebSocket de Audio Connector

Utiliza este método para enviar audio desde una sesión de la Video API de Vonage a un WebSocket.

Para obtener más información, incluidos los detalles sobre los datos de WebSocket, consulta el Guía del desarrollador del Conector de audio.

Solicitud HTTP POST para conectarse

Envía una solicitud HTTP POST a la siguiente URL:

https://api.opentok.com/v2/project/<apiKey>/connect

Sustituir <apiKey> con tu clave API de OpenTok.

Propiedades del encabezado POST

Fije el Content-Type encabezado a application/json.

Autentifica esta llamada a la API utilizando un encabezado HTTP personalizado — X-OPENTOK-AUTH — configurado como un token web JSON. Véase Autenticación.

Datos POST

Incluye un objeto JSON con el siguiente formato como contenido del cuerpo de la solicitud:

{
  "sessionId": "OpenTok session ID",
  "token": "A valid OpenTok token",
  "websocket": {
    "uri": "wss://service.com/ws-endpoint",
    "streams": [
      "streamId-1",
      "streamId-2"
    ],
    "headers": {
      "headerKey": "headerValue"
    },
    "audioRate" : 8000,
    "bidirectional": false,
    "audioTransport": {
      "transport": "binary"
    }
  }
}

El objeto JSON incluye las siguientes propiedades:

  • sessionId​ (obligatorio) — El identificador de sesión de OpenTok que incluye las transmisiones de OpenTok que deseas incluir en la transmisión de WebSocket. La función «Audio Connector» solo es compatible con sesiones enrutadas (sesiones que utilizan el OpenTok Media Router).

  • token​ (obligatorio) — El token de OpenTok que se utilizará para la conexión de Audio Connector a la sesión de OpenTok. Puedes añadir un token data para identificar que la conexión corresponde al punto final de Audio Connector o para obtener otros datos identificativos. (Las bibliotecas de cliente de OpenTok incluyen propiedades que permiten examinar los datos de conexión de un cliente conectado a una sesión.) Si vas a utilizar Audio Connector para publicar audio en la sesión, establece el rol del token en publisher o moderator. Consulta el Creación de fichas guía del desarrollador.

  • websocket ​(obligatorio): Datos incluidos para el WebSocket:

    • uri ​(obligatorio): Una URI de WebSocket accesible públicamente que se utilizará como destino de la transmisión de audio (por ejemplo, «wss://example.com/ws-endpoint»).

    • streams (opcional) — Una matriz de identificadores de transmisión correspondientes a las transmisiones de OpenTok que desees incluir en el audio de WebSocket. Si omites esta propiedad, se incluirán todas las transmisiones de la sesión .

    • headers​ (opcional) — Un objeto compuesto por pares clave-valor de encabezados que se enviarán a tu servidor WebSocket con cada mensaje, con una longitud máxima de 512 bytes.

    • audioRate (opcional) - Un número que representa la frecuencia de muestreo de audio en Hz. Los valores aceptados son 8000, 16000 (por defecto) y 24000.

    • audioTransport (opcional) — Un objeto JSON que configura cómo se serializa el audio en el canal WebSocket. Por defecto, el audio se envía como tramas PCM binarias sin procesar de 16 bits. Configúralo así para utilizar audio base64 envuelto en JSON, algo que exigen algunos proveedores de IA (por ejemplo, OpenAI Realtime). El objeto tiene las siguientes propiedades:

      • transport (obligatorio) — "binary" (PCM16 sin procesar, la opción predeterminada) o "json".
      • encoding (necesario cuando el transporte es "json") — "base64".
      • audio_field (opcional) — La clave JSON para los datos de audio de salida. El valor por defecto es "audio".
      • receive_audio_field (opcional) - La clave JSON para los datos de audio entrantes (cuando la bidireccionalidad está activada). Por defecto tiene el mismo valor que audio_field.
      • static_fields (opcional) - Un objeto de pares clave-valor adicionales incluidos en cada mensaje de audio JSON saliente.

    • bidirectional (opcional) — (booleano) Indica si se deben enviar datos de audio desde la conexión WebSocket a una transmisión publicada en la sesión. El valor por defecto es false (el WebSocket no se utiliza para publicar un flujo). Consulta los detalles en el Guía del desarrollador del Conector de audio.

Respuesta

Una llamada realizada correctamente genera una respuesta HTTP con el código de estado 200, con los detalles incluidos en los datos de la respuesta JSON:

{
  "id": "b0a5a8c7-dc38-459f-a48d-a7f2008da853",
  "connectionId": "e9f8c166-6c67-440d-994a-04fb6dfed007"
}

Los datos de respuesta JSON incluyen las siguientes propiedades:

  • id - Un ID único que identifica la conexión WebSocket del Conector de Audio.

  • connectionId — El identificador de conexión de OpenTok correspondiente a la conexión WebSocket del Audio Connector en la sesión de OpenTok.

En caso de error, la respuesta HTTP incluirá uno de los siguientes códigos de estado:

  • 400 — Solicitud no válida. Esta respuesta puede indicar que los datos de tu solicitud no son válidos en formato JSON, o que alguna de las propiedades JSON no es válida.
  • 403 — Error de autenticación.
  • 409 — Solo las sesiones enrutadas pueden iniciar conexiones WebSocket de Audio Connector.
  • 500 — Error del servidor de OpenTok.

Ejemplo

Iniciar un WebSocket de Audio Connector:

api_key=12345
json_web_token="jwt_string" # replace with a JSON web token (see "Authentication")
session_id=2_MX40NzIwMzJ-flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN-MC45NDQ2MzE2NH4
data='{\
  "sessionId" : "'$session_id'", \
  "token": "A valid OpenTok token", \
  "websocket": { \
    "uri": "wss://example.com/ws-endpoint", \
    "streams": [
      "opentok-stream-id-1",
      "opentok-stream-id-2",
    ]
  },
  "headers": [
    "X-Custom-Header-1": "header-data-1"
    "X-Custom-Header-2": "header-data-2"
  ],
}'
curl \
  -i \
  -H "Content-Type: application/json" \
  -H "X-OPENTOK-AUTH:$json_web_token" \
    -d "$data" \
  https://api.opentok.com/v2/project/$api_key/connect

Creación de una nueva clave API de proyecto

Utiliza este método para crear una clave y un secreto de la API de OpenTok para un proyecto.

Importante: Una vez creado el proyecto, pueden pasar hasta 60 segundos hasta que esté disponible para su uso.

También puedes crear un nuevo proyecto en tu Cuenta API de Video de Vonage página.

POST se asociará con

Envía una solicitud HTTP POST a la siguiente URL:

https://api.opentok.com/v2/project

Propiedades del encabezado POST

Si vas a enviar datos de solicitud para establecer un nombre (consulta la siguiente sección, «Datos POST»), configura el Content-Type encabezado a application/json. De lo contrario, no configures el Content-Type de cabeza.

Autentifica esta llamada a la API utilizando un encabezado HTTP personalizado — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Establece este encabezado con un token JWT (véase Autenticación). Ten en cuenta que debes utilizar el a nivel de cuenta Clave API y a nivel de cuenta API secreto al crear el token. La clave API y el secreto a nivel de Account solo están disponibles para los administradores registrados de tu Account de OpenTok.

Datos POST

Incluye un objeto JSON con el siguiente formato como contenido del cuerpo de la solicitud:

{
  "name": "Acme"  // optional
}

Si no deseas asignar un nombre al proyecto, no incluyas ningún contenido en el cuerpo del mensaje.

Respuesta HTTP

La respuesta HTTP tendrá uno de los siguientes códigos de estado:

  • 200 — Éxito. Los datos de la respuesta son un Detalles del proyecto Objeto.

  • 400 — Solicitud no válida. Esta respuesta puede indicar que los datos de tu solicitud no cumplen con el formato JSON válido.

  • 403 — Error de autenticación.

  • 500 — Error del servidor de OpenTok.

Ejemplo

export token=YOUR_TOKEN_STRING # See "Authentication."
export TB_url=https://api.opentok.com
headerstr="X-OPENTOK-AUTH:$token"
export data='{"name":"Acme"}'
curl -i\
   -X POST \
   -H $headerstr \
   -H "Content-Type:application/json" \
   -D $data \
   $TB_url/v2/project

Cambiar el estado de una clave API de proyecto

Los administradores de cuentas pueden utilizar este método para cambiar el estado de un proyecto. El estado puede ser «activo» o «suspendido». Si el estado de un proyecto es «suspendido», no podrás utilizar la clave API del proyecto (ni ninguna sesión de OpenTok creada con ella).

Puedes cambiar el estado de un proyecto de «activo» a «suspendido» y viceversa.

PUT para socio

Envía una solicitud HTTP PUT a la siguiente URL:

https://api.opentok.com/v2/project/<api_key>

Dónde <api_key> es la clave API del proyecto.

Propiedades del encabezado PUT

Fije el Content-Type encabezado a application/json.

Autentifica esta llamada a la API utilizando un encabezado HTTP personalizado — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Establece este encabezado con un token JWT (véase Autenticación). Ten en cuenta que debes utilizar el a nivel de cuenta Clave API y a nivel de cuenta API secreto al crear el token. La clave API y el secreto a nivel de Account solo están disponibles para los administradores registrados de tu Account de OpenTok.

Datos PUT

Incluye un objeto JSON con el siguiente formato como contenido del cuerpo de la solicitud:

{
  "status": "ACTIVE" | "SUSPENDED"
}

Respuesta HTTP

La respuesta HTTP tendrá uno de los siguientes códigos de estado:

  • 200 — Éxito. Los datos de la respuesta son los siguientes: Detalles del proyecto Objeto.

  • 400 — Solicitud no válida. Esta respuesta puede indicar que los datos de tu solicitud no cumplen con el formato JSON válido.

  • 403 — Error de autenticación.

  • 500 — Error del servidor de OpenTok.

Ejemplo

En el siguiente ejemplo se establece el estado del proyecto «Acme» como «suspendido»:

export token=YOUR_TOKEN_STRING # See "Authentication."
export TB_url=https://api.opentok.com
headerstr="X-OPENTOK-AUTH:$token"
apikey=1234567         # Replace with the project API key.
export data='{"status":"SUSPENDED"}'
curl -i\
   -X PUT \
   -H $headerstr \
   -H "Content-Type:application/json" \
   -D $data \
   $TB_url/v2/project/$apikey

Eliminar un proyecto

Utiliza este método para eliminar un proyecto. De este modo se impide el uso de la clave API del proyecto (así como de cualquier sesión de OpenTok creada con ella).

También puedes, de forma temporal, suspender la clave API de un proyecto.

Nota: También puedes eliminar un proyecto de tu Cuenta API de Video de Vonage página.

ELIMINAR socio

Envía una solicitud HTTP DELETE a la siguiente URL:

https://api.opentok.com/v2/project/<api_key>

Dónde <api_key> es la clave API del proyecto.

Propiedades del encabezado DELETE

Autentifica esta llamada a la API utilizando un encabezado HTTP personalizado — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Establece este encabezado con un token JWT (véase Autenticación). Ten en cuenta que debes utilizar el a nivel de cuenta Clave API y a nivel de cuenta API secreto al crear el token. La clave API y el secreto a nivel de Account solo están disponibles para los administradores registrados de tu Account de OpenTok.

Respuesta HTTP

La respuesta HTTP tendrá uno de los siguientes códigos de estado:

  • 204 — Éxito (sin contenido).
  • 403 — Error de autenticación.
  • 404 — No encontrado. No existe ningún proyecto para la clave API facilitada.
  • 500 — Error del servidor de OpenTok.

Ejemplo

En el siguiente ejemplo se elimina un proyecto:

export token=YOUR_TOKEN_STRING # See "Authentication."
export TB_url=https://api.opentok.com
headerstr="X-OPENTOK-AUTH:$token"
apikey=1234567         # Replace with the project API key.
curl -i\
   -X DELETE \
   -H $headerstr \
   $TB_url/v2/project/$apikey

Obtener información sobre proyectos

Utiliza este método para obtener un registro con los detalles del proyecto (o para obtener los registros de todos los proyectos). Consulta Detalles del proyecto Objeto.

Conviértete en socio de GET

Para obtener información sobre un proyecto concreto, envía una solicitud GET a la siguiente URL:

https://api.opentok.com/v2/project/<api_key>

Dónde <api_key> es la clave API del proyecto.

Para obtener información sobre todos tus proyectos, envía una solicitud GET a la siguiente URL:

https://api.opentok.com/v2/project

Propiedades del encabezado GET

Autentifica esta llamada a la API utilizando un encabezado HTTP personalizado — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Establece este encabezado con un token JWT (véase Autenticación). Ten en cuenta que debes utilizar el a nivel de cuenta Clave API y a nivel de cuenta API secreto al crear el token. La clave API y el secreto a nivel de Account solo están disponibles para los administradores registrados de tu Account de OpenTok.

Respuesta HTTP

La respuesta HTTP tendrá uno de los siguientes códigos de estado:

  • 200 — Éxito. Los datos de la respuesta son el objeto de detalles del proyecto o una matriz de objetos de detalles del proyecto. Véase Detalles del proyecto Objeto.

  • 403 — Error de autenticación.

  • 404 — No encontrado. No existe ningún proyecto para la clave API facilitada.

  • 500 — Error del servidor de OpenTok.

### Ejemplo

En el siguiente ejemplo se obtienen los detalles de un proyecto concreto:

export token=YOUR_TOKEN_STRING # See "Authentication."
export TB_url=https://api.opentok.com
headerstr="X-OPENTOK-AUTH:$token"
apikey=1234567         # Replace with the project API key.
curl -i\
   -X GET \
   -H $headerstr \
   $TB_url/v2/project/$apikey

La respuesta es un JSON Detalles del proyecto Objeto.

El siguiente ejemplo muestra los detalles de todos tus proyectos:

export token=YOUR_TOKEN_STRING # See "Authentication."
export TB_url=https://api.opentok.com
headerstr="X-OPENTOK-AUTH:$token"
curl -i\
   -X GET \
   -H $headerstr \
   $TB_url/v2/project

La respuesta es una matriz de detalles del proyecto objetos.

Generar un nuevo secreto de API para el proyecto

Por motivos de seguridad, es posible que desees generar un nuevo secreto de API para un proyecto.

Nota: Utiliza el nuevo secreto de API para todas las llamadas a la API REST y con los SDK del lado del servidor de OpenTok. Cuando generes un nuevo secreto de API, todos los existentes fichas de cliente dejarán de ser válidos (y no se podrán utilizar para conectarse a sesiones de OpenTok); utiliza el nuevo secreto de la API con el Client SDK del servidor de OpenTok para generar tokens de cliente.

POST para actualizar «secret»

Envía una solicitud HTTP POST a la siguiente URL:

https://api.opentok.com/v2/project/<api_key>/refreshSecret

Dónde <api_key> es la clave API del proyecto.

Propiedades del encabezado POST

Autentifica esta llamada a la API utilizando un encabezado HTTP personalizado — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Establece este encabezado con un token JWT (véase Autenticación). Ten en cuenta que debes utilizar el a nivel de cuenta Clave API y a nivel de cuenta API secreto al crear el token. La clave API y el secreto a nivel de Account solo están disponibles para los administradores registrados de tu Account de OpenTok.

Respuesta HTTP

La respuesta HTTP tendrá uno de los siguientes códigos de estado:

  • 200 — Éxito. Los datos de la respuesta son los siguientes: Detalles del proyecto Objeto, con el nuevo secreto de la API.

  • 403 — Error de autenticación.

  • 404 — No encontrado. No existe ningún proyecto para la clave API facilitada.

  • 500 — Error del servidor de OpenTok.

Ejemplo

El siguiente ejemplo genera un nuevo secreto de API para el proyecto:

export token=YOUR_TOKEN_STRING # See "Authentication."
export TB_url=https://api.opentok.com
headerstr="X-OPENTOK-AUTH:$token"
apikey=1234567         # Replace with the project API key.
curl -i\
   -X POST \
   -H $headerstr \
   $TB_url/v2/project/$apikey/refreshSecret