Référence de l'API REST Vonage Video API

Utilisez l'API REST OpenTok pour créer des sessions OpenTok, gérer les archives et gérer les diffusions en direct. L' SDK pour serveurs OpenTok (pour Java, .NET, Node.js, PHP, Pythonet Rubis) mettent en œuvre bon nombre des méthodes de l'API REST.

L'API REST comprend des méthodes permettant d'effectuer les opérations suivantes :

Création de sessions, signalisation et modération

Archivage

Interconnexion SIP

Diffusion en direct

Sous-titres en direct

Compositeur d'expérience

Connecteur audio

Gestion des comptes

Les SDK OpenTok mettre en œuvre l'API REST d'OpenTok afin de faciliter les appels vers la plateforme OpenTok.

Authentification

Les appels à l'API REST doivent être authentifiés à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH — ainsi qu’un JSON Web Token. Créez le jeton JWT avec les revendications suivantes :

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

Set (jeu de mots) iss à votre clé API OpenTok. Pour la plupart des appels à l'API REST, utilisez la clé API correspondant au projet spécifique de votre Account. Celle-ci est indiquée sur la page « Projet » de votre Video API Account. Toutefois, les méthodes REST suivantes sont réservées aux administrateurs enregistrés du compte OpenTok. Pour utiliser ces méthodes, vous devez configurer iss à la au niveau de l'account Clé API, accessible uniquement aux administrateurs de compte. (voir Gestion des comptes) :

Pour obtenir la clé API et le secret au niveau de l'Account, connectez-vous à votre Video API Account, cliquez Paramètres du compte dans le menu de gauche, puis sous API REST d'OpenTok, cliquez Afficher les clés du compte.

Pour la plupart des appels d'API REST, définissez ist à "project". Toutefois, pour ce qui suit Gestion des comptes Méthodes REST, set ist à "account":

Set (jeu de mots) iat à l'horodatage Unix actuel (date de création du jeton), en secondes.

Set (jeu de mots) exp à l'heure d'expiration du jeton. Pour des raisons de sécurité, nous vous recommandons d'utiliser un délai d'expiration proche du délai de création du jeton (par exemple, 3 minutes après la création) et de créer un nouveau jeton pour chaque appel à l'API REST. Le délai d'expiration maximal autorisé est de 5 minutes.

Set (jeu de mots) jti à un identifiant unique pour le JWT. Cet identifiant est facultatif. Voir la page Spécification du jeton web JSON pour plus de détails.

Utilisez votre clé secrète API OpenTok comme clé secrète JWT et signez-la à l'aide de l' algorithme de chiffrement HMAC-SHA256. Pour la plupart des appels à l'API REST, utilisez la clé secrète API correspondant au projet spécifique de votre Account. Celle-ci est indiquée sur la page Projet de votre Account Video API Account. Toutefois, les méthodes REST suivantes sont réservées aux administrateurs enregistrés du compte OpenTok. Pour utiliser ces méthodes, vous devez utiliser le au niveau de l'account API clé et secret (qui n'est accessible qu'aux administrateurs du compte) en tant que clé secrète JWT (voir Gestion des comptes) :

Par exemple, le code Python suivant crée un jeton pouvant être utilisé dans un appel à l'API REST d'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')

Remplacer le my-OpenTok-API-key et my-OpenTok-API-secret avec la clé API et le secret API d'OpenTok.

Remarque : Avant l'utilisation des jetons Web JSON, les appels à l'API REST d'OpenTok étaient authentifiés à l'aide d'un en-tête HTTP personnalisé : X-TB-PARTNER-AUTH en remplaçant la valeur par votre clé API OpenTok et votre secret API, reliés par deux points :

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

Cependant, ce mode d'authentification (utilisant X-TB-PARTNER-AUTH) est obsolète, et vous devriez désormais utiliser les jetons JSON Web pour l'authentification. (L'utilisation de ce mode d'authentification obsolète prendra fin en juillet 2017.)

Création d'une session

Créer une nouvelle session.

URL de la ressource :

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

Verbe de ressource :

POST

Propriétés de l'en-tête POST

Les appels API doivent être authentifiés à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH — ainsi qu’un jeton Web JSON (JWT). Voir Authentification.

Régler le Content-Type à l'en-tête application/x-www-form-urlencoded:

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

Régler le Accept à l'en-tête application/json:

Accept:application/json

Paramètres POST

archiveName

Nom à utiliser pour les archives dans les sessions archivées automatiquement. Lorsque cette option est activée, le archiveMode Cette option doit être définie sur always sinon une erreur se produira. Le nom de l'archive peut comporter jusqu'à 80 caractères. En raison de contraintes d'encodage, les caractères spéciaux suivants sont remplacés par deux points (:) : ~, -, _. Si vous ne spécifiez pas de nom et que le archiveMode l'option est définie sur always, le nom de l'archive sera vide.

archiveResolution

Résolution des archives dans une session à archivage automatique. Les valeurs valides sont « 480x640 », « 640x480 » (par défaut), « 720x1280 », « 1280x720 », « 1080x1920 » et « 1920x1080 ». Lorsque cette option est définie, le archiveMode Cette option doit être définie sur always sinon une erreur se produira.

location

L'adresse IP que la Video API Vonage utilisera pour localiser la session au sein de son réseau mondial. Si aucune indication de localisation n'est fournie (ce qui est recommandé), la session utilise un serveur multimédia en fonction de la localisation du premier client se connectant à la session. Ne transmettez une indication de localisation que si vous connaissez la région géographique générale (et une adresse IP représentative) et si vous pensez que le premier client à se connecter pourrait ne pas se trouver dans cette région. Spécifiez une adresse IP représentative de la localisation géographique de la session.

p2p.preference

Régler sur enabled si vous préférez que les clients tentent d'envoyer des flux audio-vidéo directement à d'autres clients ; définissez ce paramètre sur disabled pour les sessions utilisant OpenTok Media Router. (Facultatif ; le paramètre par défaut est disabled -- la session utilise le routeur multimédia OpenTok.)

Les Routeur multimédia OpenTok offre les avantages suivants :

  • Le routeur multimédia OpenTok permet de réduire la consommation de bande passante lors des sessions multipartites. (Lorsque la propriété p2p.preference est définie sur enabledchaque client doit envoyer un flux audio-vidéo distinct à chaque client qui s'y abonne).
  • Le routeur multimédia OpenTok permet d'améliorer la qualité de l'expérience utilisateur grâce à repli audio et récupération vidéo. Grâce à ces fonctionnalités, si la connexion d'un client se détériore au point de ne plus permettre la lecture de la vidéo d'un flux auquel il est abonné, la vidéo est interrompue pour ce client (sans affecter les autres clients), et celui-ci ne reçoit alors que le son. Si la connexion du client s'améliore, la vidéo reprend.
  • Le routeur multimédia OpenTok prend en charge le fonction d'archivage, qui vous permet d'enregistrer, de sauvegarder et de consulter des sessions OpenTok.

Avec la p2p.preference Si cette propriété est définie sur « enabled », la session tentera de transmettre les flux directement entre les clients. Si les clients ne parviennent pas à se connecter en raison de restrictions de pare-feu, la session utilise le serveur TURN d'OpenTok pour relayer les flux audio et vidéo.

Exemples de demandes

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

L'exemple de ligne de commande suivant permet de créer une session utilisant OpenTok Media Router et de spécifier une indication de localisation :

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

L'exemple de ligne de commande suivant permet de créer une session qui tente de transmettre des flux directement entre les clients (sans passer par le routeur multimédia OpenTok) :

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

L'exemple de ligne de commande suivant permet de créer une session archivée automatiquement :

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

Exemple de réponse

La réponse se présente sous la forme de données JSON comme suit :

[
  {
    "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"
  }
]

Notez que si vous n'incluez pas l'en-tête « Accept:application/json », le format de la réponse sera XML. Cette version XML de l'appel d'API est obsolète.

La réponse HTTP renvoie un code d'état 403 si vous fournissez une clé API OpenTok ou un jeton JWT non valide.

La réponse HTTP affiche un code d'état 500 correspondant à une erreur du serveur OpenTok.

Envoi d'un signal depuis votre serveur d'applications vers les clients connectés

Utilisez l'API REST Signal pour envoyer des signaux à tous les participants d'une session OpenTok active ou à un client spécifique connecté à cette session. Les signaux envoyés depuis le serveur ont un from paramètre dans le signal reçu gestionnaires sur les clients connectés à la session. Pour un signal envoyé par un participant à la session, le from Cette propriété contient l'identifiant de connexion du client qui a envoyé le signal, mais dans ce cas précis, il n'y a pas de connexion associée.

Pour les deux exemples de signal ci-dessous, le corps de la requête sera utilisé pour transmettre à la fois le type et data champs. Ceux-ci correspondent au type et aux paramètres de données transmis aux gestionnaires de réception des signaux du client.

type

Chaîne de caractères. Sa longueur maximale est de 128 octets, et elle ne doit contenir que des lettres (A-Z et a-z), des Numbers (0-9), les caractères « - », « _ » et « ~ ».

data

Chaîne de caractères. La longueur maximale est de 8 ko.

Signaler tous les clients connectés à la session

Envoyez une requête HTTP POST à l'adresse signal ressource de la session :

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

Remarque : Auparavant, cette URL REST utilisait /partner (qui est désormais obsolète) au lieu de /project.

Signaler un client spécifique connecté à la session

Envoyez une requête HTTP POST à l'adresse signal ressource associée à un identifiant de connexion spécifique, appartenant à la session :

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

Réponses en cas d'erreur de signalisation

Les erreurs sont renvoyées dans la réponse sous forme de codes d'état HTTP :

  • 400 — L'une des propriétés du signal — data, type, sessionId ou connectionId — n'est pas valide.
  • 403 — Vous n'êtes pas autorisé(e) à envoyer ce signal. Vérifiez vos identifiants d'authentification.
  • 404 — Le client spécifié par le connectionId La propriété n'est pas associée à la session.
  • 413 — La chaîne de caractères de type dépasse la longueur maximale (128 octets), ou la chaîne de données dépasse la taille maximale (8 ko).

En cas d'erreur, le corps de la réponse se présentera comme suit :

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

Forcer un point de terminaison client à se déconnecter d'une session

Votre serveur d'applications peut déconnecter un client d'une session OpenTok en envoyant une requête HTTP DELETE à la ressource correspondant à la connexion de ce client :

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}

Remarque : Auparavant, cette URL REST utilisait /partner (qui est désormais obsolète) au lieu de /project.

Réponses d'erreur

Les erreurs sont renvoyées dans la réponse sous forme de codes d'état HTTP :

  • 400 — L'un des arguments — sessionId ou connectionId — n'est pas valide.
  • 403 — Vous n'êtes pas autorisé à utiliser la commande « forceDisconnect » ; veuillez vérifier vos identifiants d'authentification.
  • 404 — Le client spécifié par le connectionId La propriété n'est pas associée à la session.

En cas d'erreur, le corps de la réponse se présentera comme suit :

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

Récupération des informations sur le flux

Utilisez cette méthode pour obtenir des informations sur un flux OpenTok (ou sur tous les flux d'une session).

Par exemple, vous pouvez appeler cette méthode pour obtenir des informations sur les classes de mise en page utilisées par un flux OpenTok. Ces classes de mise en page définissent la manière dont le flux s'affiche dans la mise en page d'un flux de diffusion. Pour plus d'informations, consultez Attribution de classes de mise en page de diffusion en direct aux flux OpenTok streams.

Requête HTTP GET vers session/stream

Pour obtenir des informations sur la classe de mise en page d'un flux spécifique, envoyez une requête HTTP GET à l'URL suivante :

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

  • Remplacer <apiKey> avec votre clé API OpenTok.

  • Remplacer <sessionId> avec l'identifiant de session.

  • Remplacer <streamId> avec l'identifiant du flux.

Pour obtenir des informations sur les classes de mise en page de tous les flux d'une session, envoyez une requête HTTP GET à l'URL suivante (en omettant l'identifiant du flux à la fin) :

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

Propriétés de l'en-tête GET

Authentifiez cet appel API à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH — définir sur un jeton Web JSON. Voir Authentification.

Réponse

Lorsqu'on récupère les informations relatives à la classe de mise en page d'un flux donné, les données JSON de la réponse contiennent un layoutClassList de la gamme :

{
  "id": "8b732909-0a06-46a2-8ea8-074e64d43422",
  "videoType": "camera",
  "name": "",
  "layoutClassList": ["full"]
}
  • Les layoutClassList est un tableau de classes de mise en page pour le flux.
  • Les id est l'identifiant du flux.
  • Les videoType La propriété est définie sur « camera », « screen » ou « custom ». Une vidéo « screen » utilise le partage d'écran du diffuseur comme source vidéo ; une vidéo « custom » est diffusée par un client Web utilisant un élément VideoTrack HTML comme source vidéo.
  • Les name est le nom du flux (s'il a été défini lors de la publication du flux par le client).

Lorsqu'on récupère les informations relatives à la classe de mise en page pour plusieurs flux, les données JSON de la réponse incluent un items propriété, qui est un tableau contenant des informations de mise en page pour les flux de la session :

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

La réponse HTTP comportera l'un des codes d'état suivants :

  • 200 — Réussite.
  • 400 — Demande non valide. Cette réponse peut indiquer que les données contenues dans votre requête sont au format JSON non valide. Elle peut également signifier que vous n'avez pas fourni d'identifiant de session ou que vous avez fourni un identifiant de flux non valide.
  • 403 — Vous avez fourni une clé API OpenTok ou un jeton JWT non valide.
  • 404 — La session existe, mais aucun flux ne lui a encore été ajouté.
  • 408 — Vous avez saisi un identifiant de flux non valide.
  • 500 — Erreur du serveur OpenTok.

Exemple

L'exemple de ligne de commande suivant permet de récupérer les informations relatives à la classe de mise en page d'un flux spécifique :

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
  • Définir la valeur de api_key à votre clé API OpenTok.
  • Définir la valeur de json_web_token vers un jeton Web JSON (voir « Authentification »).
  • Régler le session_id valeur à la session.
  • Régler le stream_id valeur à l'identifiant du flux.

L'exemple de ligne de commande suivant permet de récupérer les informations relatives à la classe de mise en page pour tous les flux d'une session :

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/
  • Définir la valeur de api_key à votre clé API OpenTok.
  • Définir la valeur de json_web_token vers un jeton Web JSON (voir « Authentification »).
  • Régler le session_id valeur à la session.

Forcer la mise en sourdine de l'audio publié d'un flux unique

Vous pouvez utiliser l'API REST OpenTok pour forcer l'éditeur d'un flux spécifique à couper le son.

POST vers session/stream/mute

Envoyez une requête HTTP POST à l'URL suivante :

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

Remplacer <api_key> avec la clé API du projet OpenTok (voir la page du projet de votre Video API Account). Remplacer <session_id> avec l'identifiant de la session contenant le flux. Remplacer <stream_id> avec l'identifiant du flux.

Propriétés de l'en-tête POST

Authentifiez cet appel API à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Définissez cet en-tête sur un jeton JWT (voir Authentification).

Réponse HTTP

La réponse HTTP comportera l'un des codes d'état suivants :

  • 200 — Réussite. Les données de réponse sont un détails du projet objet.

  • 400 — Demande non valide.

  • 403 — Erreur d'authentification.

  • 404 — Page introuvable. La session ou le flux est introuvable.

  • 500 — Erreur du serveur OpenTok.

Exemple

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

Forcer la mise en sourdine de l'audio publié lors d'une session de streaming

Vous pouvez utiliser l'API REST OpenTok pour forcer tous les flux (à l'exception d'une liste facultative de flux) d'une session à couper le son publié. Vous pouvez également utiliser cette méthode pour désactiver l'état de coupure forcée du son d'une session (voir ci-dessous).

POST vers session/mute

Envoyez une requête HTTP POST à l'URL suivante :

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

Remplacer <api_key> avec la clé API du projet OpenTok (voir la page du projet de votre Video API Account). Remplacer <session_id> avec l'identifiant de session.

Propriétés de l'en-tête POST

Régler le Content-Type à l'en-tête application/json.

Authentifiez cet appel API à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Définissez cet en-tête sur un jeton JWT (voir Authentification).

Données POST

Incluez un objet JSON se présentant sous la forme suivante dans le corps de la requête :

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

Les données JSON comprennent les propriétés suivantes :

  • active (Booléen, obligatoire) — Indique s'il faut couper le son des flux audio de la session (true) et activer le mode « muet » de la session, ou désactiver le mode « muet » de la session (false). Lorsque la fonction « Muet » est activée (true), tous les flux actuels et futurs publiés dans la session (à l'exception des flux figurant dans le excludedStreamIds tableau) sont désactivés. Lorsque vous appelez cette méthode avec le active est définie comme étant la propriété false, les flux futurs publiés dans la session ne sont pas mis en sourdine (mais les flux déjà mis en sourdine le restent).

  • excludedStreamIds (Tableau de chaînes de caractères, facultatif) — Les identifiants des flux qui ne doivent pas être mis en sourdine. Il s'agit d'une propriété facultative. Si vous omettez cette propriété, tous les flux de la session seront mis en sourdine. Cette propriété ne s'applique que lorsque le active est fixée à true. Lorsque le active est fixée à false, elle est ignorée.

    Les éléments contenus dans le excludedStreamIds Le tableau contient les identifiants (chaînes de caractères) des flux que vous souhaitez exclure de la mise en sourdine.

    Si vous ne souhaitez pas inclure de liste de flux exclus, n'ajoutez aucun contenu dans le corps du message.

Réponse HTTP

La réponse HTTP comportera l'un des codes d'état suivants :

  • 200 — Réussite. Les données de réponse sont un détails du projet objet.

  • 400 — Demande non valide. Cette réponse peut indiquer que les données contenues dans votre demande ne sont pas au format JSON valide.

  • 403 — Erreur d'authentification.

  • 404 — Page introuvable. La session est introuvable.

  • 500 — Erreur du serveur OpenTok.

Exemple

La commande suivante force tous les flux (à l'exception d'une liste facultative de flux) d'une session à couper le son de l'audio publié :

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

Pour désactiver le mode « muet » de la session (et empêcher que les flux futurs ne soient mis en mode « muet »), appelez à nouveau la méthode avec le active est définie comme étant la propriété 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

Répertorier les connexions d'une session

Utilisez cette méthode pour répertorier les connexions d'une session OpenTok associée à un projet.

Requête HTTP GET vers la session/connexion

Envoyez une requête HTTP GET à l'URL suivante :

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

Remplacer <api_key> avec votre clé API OpenTok. Consultez la page du projet dans votre Video API Account.

Remplacer <sessionId> avec l'identifiant de la session contenant les connexions.

Vous pouvez ajouter des paramètres de requête facultatifs pour filtrer les résultats :

  • offset (entier, facultatif) : indice (à partir de zéro) de la première connexion à renvoyer. La valeur par défaut est 0 (la connexion la plus ancienne).
  • count (entier, facultatif) : nombre maximal de connexions à renvoyer. La valeur par défaut est 50 ; la valeur maximale est 1 000.

Par exemple, l'appel suivant récupère 20 connexions à partir de la position 400 :

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

Propriétés de l'en-tête GET

Les appels API doivent être authentifiés à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH — ainsi que d'un jeton Web JSON (JWT). Voir Authentification.

Réponse

Les données brutes de la réponse HTTP, dont le code d'état est 200, constituent un message encodé au format JSON se présentant sous la forme suivante :

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

L'objet JSON comprend les propriétés suivantes :

  • nombre — Nombre total de connexions dans la session.
  • projectId — Votre clé API OpenTok.
  • sessionId — L'identifiant de session.
  • items — Tableau d'objets définissant chacune des connexions récupérées. Les connexions sont classées par ordre chronologique, de la plus ancienne à la plus récente, dans le jeu de résultats.

Chaque élément du tableau `items` représente une connexion et possède les propriétés suivantes :

  • connectionId — L'identifiant de la connexion.
  • connectionState — L'état de la connexion :
    • « Connexion » — La connexion est encore en cours d'établissement et n'est pas encore entièrement établie.
    • « Connecté » — La connexion est entièrement établie et reliée à la session.
  • createdAt — Horodatage correspondant au moment de la création de la connexion, exprimé en millisecondes depuis l'époque Unix (1er janvier 1970, 00:00:00 UTC).

La réponse HTTP comportera l'un des codes d'état suivants :

  • 200 — Réussite. Les données de réponse contiennent la liste des connexions d'une session OpenTok.
  • 400 — Demande non valide. Cette réponse peut indiquer qu'un paramètre de votre requête n'est pas valide.
  • 403 — Erreur d'authentification.
  • 404 — La session est introuvable.
  • 500 — Erreur du serveur OpenTok.

Exemple

Dans les exemples suivants :

  • Remplacez la valeur de la variable API_KEY par votre clé API OpenTok.
  • Définissez la valeur de JWT sur un jeton Web JSON valide (voir Authentification).
  • Définissez la valeur de SESSION_ID en indiquant votre identifiant de session OpenTok.

L'exemple de ligne de commande suivant permet de récupérer les 50 premières connexions de la session :

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

L'exemple de ligne de commande suivant permet de récupérer la première connexion créée au cours de la session :

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

L'exemple de ligne de commande suivant récupère deux connexions, en commençant par la cinquième connexion créée au cours de la session :

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

L'exemple suivant ne renvoie aucune connexion, car le décalage est supérieur au nombre de connexions de la session :

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

Migration d'une session

Utilisez cette méthode pour migrer une session vers un autre serveur lorsque cela s'avère nécessaire. La migration n'est possible que si aucune migration n'est en cours pour cette session et si celle-ci n'a pas été créée ou migrée récemment. (Voir la Rotation des serveurs et migration des sessions guide du développeur.)

Remarque : Lorsque la migration est lancée, toutes les connexions disposant de la capacité « migrate » seront transférées vers le nouveau serveur. Toutes les connexions ne disposant pas de la capacité « migrate » seront fermées dans le cadre du processus de migration. (Voir Activation de la migration de session dans les clients.)

URL de la ressource :

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

Remplacer <api_key> avec la clé API du projet OpenTok (voir la page du projet de votre Video API Account). Remplacer <session_id> avec l'identifiant de la session à migrer vers un autre serveur.

Verbe de ressource :

POST

Propriétés de l'en-tête POST

Régler le Content-Type à l'en-tête application/json.

Authentifiez cet appel API à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Définissez cet en-tête sur un jeton JWT (voir Authentification).

Réponse HTTP

Pour certaines réponses d'erreur, outre le code de réponse HTTP, le corps de la réponse comprend un code champ permettant d'indiquer la cause précise de l'erreur. La réponse HTTP comportera l'un des codes d'état suivants :

  • 202 — Accepté. La demande est valide et la session sera transférée.

  • 400 — Demande non valide. Cette réponse peut indiquer que certaines informations manquent dans la demande.

  • 403 — Erreur d'authentification. Jeton non autorisé ou non valide

  • 404 — Page introuvable. La session est introuvable.

  • 409 — Conflit. La session ne peut pas être migrée pour le moment. Cela peut être dû à l'une des raisons suivantes :

    • code 15214 : Une migration est déjà en cours pour cette session.
    • code 15215 : La session a été créée ou migrée récemment.

  • 500 — Erreur interne du serveur OpenTok.

Demande d'échantillon

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
  • Définir la valeur de API_KEY à votre clé API OpenTok.
  • Définir la valeur de JWT vers un jeton Web JSON (voir « Authentification »).
  • Régler le SESSION_ID valeur correspondant à l'identifiant de la session à migrer.

Exemple de réponse

Réponse d'erreur d'authentification :

{
  "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"
}

Démarrage d'un enregistrement d'archives

Pour lancer l'enregistrement d'une session OpenTok, envoyez une requête HTTP POST.

Pour pouvoir lancer correctement l'enregistrement d'une archive, au moins un client doit être connecté à la session.

Vous ne pouvez enregistrer que les archives des sessions qui utilisent OpenTok Media Router (avec le mode multimédia défini sur « routed ») ; vous ne pouvez pas archiver les sessions dont le mode multimédia est défini sur « relayed ». (Voir Le routeur multimédia OpenTok et les modes multimédias.)

Pour plus d'informations, voir le Guide du développeur sur l'archivage OpenTok.

Requête HTTP POST vers l'archive

Envoyez une requête HTTP POST à l'URL suivante :

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

Remplacer <api_key> avec votre clé API OpenTok. Consultez la page du projet de votre Video API Account.

Remarque : Auparavant, cette URL REST utilisait /partner (qui est désormais obsolète) au lieu de /project.

Propriétés de l'en-tête POST

Les appels API doivent être authentifiés à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH — ainsi qu’un jeton Web JSON (JWT). Voir Authentification.

Définissez l'en-tête « Content-type » sur « application/json » :

Content-Type:application/json

Données POST

Incluez un objet JSON sous la forme suivante dans les données 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"
}

L'objet JSON comprend les propriétés suivantes :

  • sessionId (Chaîne) — (Obligatoire) L'identifiant de la session OpenTok que vous souhaitez commencer à archiver
  • hasAudio (Booléen) — (Facultatif) Indique si l'archive enregistrera le son (true, valeur par défaut) ou non (false). Si vous définissez à la fois hasAudio et hasVideo Si la valeur est « false », l'appel de cette méthode génère une erreur.
  • hasVideo (Booléen) — (Facultatif) Indique si l'archive enregistrera la vidéo (true, valeur par défaut) ou non (false). Si vous définissez les deux hasAudio et hasVideo Si la valeur est « false », l'appel de cette méthode génère une erreur.
  • layout (Objet) — Facultatif. Indiquez cet élément pour définir le type de structure initiale de l'archive. Cela s'applique uniquement à archives classées. Cet objet possède trois propriétés : type, stylesheetet screenshareType, qui sont toutes des chaînes de caractères. Les valeurs valides pour le layout les propriétés sont les suivantes : "bestFit" (meilleur ajustement), "custom" (sur mesure), "horizontalPresentation" (présentation horizontale), "pip" (image dans l'image) et "verticalPresentation" (présentation verticale)). Si vous spécifiez un "custom" définir le type de mise en page stylesheet de la propriété layout ajouter la feuille de style. (Pour les autres types de mise en page, ne définissez pas de stylesheet propriété.) Définissez la screenshareType propriété du type de mise en page à utiliser lorsqu'un flux de partage d'écran est présent dans la session. (Cette propriété est facultative.) Remarque : si vous définissez la screenshareType propriété, vous devez définir la type à "bestFit" et laisser la propriété stylesheet Propriété non définie. Si vous ne spécifiez pas de type de mise en page initiale, l'archive utilise le type de mise en page le plus adapté. Pour plus d'informations, consultez Personnalisation de la présentation vidéo pour les archives composées.
  • maxBitrate (facultatif) — Débit binaire vidéo maximal de l'archive, en bits par seconde. La valeur minimale est de 100 000 et la valeur maximale de 6 000 000. Cette option n'est valable que pour les archives composées. Définissez le débit binaire vidéo maximal pour contrôler la taille de l'archive composée. Ce débit binaire maximal s'applique uniquement au débit binaire vidéo. Si l'archive de sortie contient de l'audio, ces bits seront exclus de la limite. Lorsque vous définissez le maxBitrate propriété, l'archive utilise un débit binaire constant. Vous ne pouvez pas définir à la fois la maxBitrate et la propriété quantizationParameter propriétés — cela provoque une erreur.
  • multiArchiveTag (Chaîne) — (Facultatif) Activez cette option pour permettre l'enregistrement simultané de plusieurs archives pour une même session. Attribuez une chaîne unique à chaque archive simultanée d'une session en cours. Vous devez également activer cette option lorsque vous lancez manuellement une archive dans une session qui est archivés automatiquement. Si vous ne spécifiez pas un multiArchiveTag, vous ne pouvez enregistrer qu'une seule archive à la fois pour une session donnée. Voir Archives simultanées.
  • name (Chaîne de caractères) — (Facultatif) Nom de l'archive (à des fins d'identification personnelle). La longueur maximale du nom de l'archive est de 255 caractères.
  • outputMode (Chaîne) — (Facultatif) Indique si tous les flux de l'archive sont enregistrés dans un seul fichier ("composed", par défaut) ou à des fichiers spécifiques ("individual"). Voir aussi Archives individuelles de flux et composées.
  • quantizationParameter (Nombre) — (Facultatif) Paramètre de quantification (QP) d’une archive composée, qui permet d’ajuster le compromis entre la qualité vidéo et la taille du fichier. La définition de ce paramètre de quantification fait en sorte que l’archive utilise un débit binaire variable et une quantification de compression constante, ce qui garantit un niveau de qualité homogène d’une scène à l’autre. Les valeurs valides sont comprises entre 15 et 40 ; les valeurs comprises entre 20 et 30 donnent des résultats satisfaisants sans différence perceptible significative en termes de qualité. Des valeurs de QP plus faibles produisent une quantification de compression vidéo plus fine, ce qui se traduit par une meilleure qualité vidéo (conservation d’un plus grand nombre de détails) et une taille de fichier plus importante. Des valeurs de QP plus élevées produisent une quantification de compression vidéo plus grossière, ce qui réduit la qualité vidéo et se traduit par une taille de fichier plus petite. Vous ne pouvez définir un paramètre de quantification que pour une archive composée — la configuration quantizationParameter La tentative d'archivage d'un flux individuel génère une erreur. Vous ne pouvez pas définir à la fois le quantizationParameter et la propriété maxBitrate ce qui entraînerait une erreur.
  • resolution (Chaîne) — (Facultatif) La résolution de l'archive, soit "640x480" (format paysage SD, par défaut), "1280x720" (HD en mode paysage), "1920x1080" (FHD en mode paysage), "480x640" (portrait SD), "720x1280" (portrait HD), ou "1080x1920" (FHD portrait). Vous pouvez choisir d'utiliser un format portrait pour les archives contenant des flux vidéo provenant d'appareils mobiles (qui utilisent souvent ce format). Cette propriété s'applique uniquement aux archives composées. Si vous définissez cette propriété et que vous définissez la outputMode à la propriété "individual", l'appel à la méthode REST génère une erreur.
  • streamMode (Chaîne) — (Facultatif) Indique si les flux inclus dans l'archive sont sélectionnés automatiquement ("auto", valeur par défaut) ou manuellement ("manual"). Lorsque les flux sont sélectionnés automatiquement ("auto"), tous les flux de la session peuvent être inclus dans l'archive. Lorsque les flux sont sélectionnés manuellement ("manual"), vous spécifiez les flux à inclure en fonction des appels à cette méthode REST. Vous pouvez préciser si l'archive doit inclure le flux audio, le flux vidéo ou les deux. Dans les archives composées, tant en mode automatique qu'en mode manuel, l'outil de création d'archives inclut les flux en fonction de règles de hiérarchisation des cours d'eau.

Les données brutes de la réponse HTTP, dont le code d'état est 200, constituent un message encodé au format JSON se présentant sous la forme suivante :

{
  "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
}

L'objet JSON comprend les propriétés suivantes :

  • createdAt — L'horodatage correspondant au moment où l'archivage a commencé, exprimé en millisecondes depuis l'époque Unix (1er janvier 1970, 00:00:00 UTC).
  • hasAudio — Indique si l'archive enregistrera le son (vrai) ou non (faux).
  • hasVideo — Indique si l'archive enregistrera des vidéos (vrai) ou non (faux).
  • id — L'identifiant unique de l'archive. Enregistrez cette valeur pour une utilisation ultérieure (par exemple, pour arrêter l'enregistrement).
  • multiArchiveTag — L'identifiant unique des archives simultanées (si un tel identifiant a été défini).
  • name — Le nom de l'archive que vous avez fournie (cette information est facultative).
  • outputMode — Soit "composed" ou "individual". Voir Archives individuelles de flux et composées.
  • projectId — Votre clé API OpenTok.
  • resolution — La résolution de l'archive (soit « 640x480 », « 1280x720 », « 1920x1080 », « 480x640 », « 720x1280 » ou « 1080x1920 »). Cette propriété n’est définie que pour les archives composées.
  • sessionId — L'identifiant de la session OpenTok en cours d'archivage.
  • status - Cette valeur est fixée à "started".
  • streamMode — La sélection des flux inclus dans les archives se fait-elle automatiquement ("auto", valeur par défaut) ou manuellement ("manual").
  • streams — Un tableau d'objets correspondant aux flux en cours d'archivage. Cette valeur n'est définie que pour une archive avec le status fixé à "started" et le streamMode fixé à "manual". Chaque objet du tableau comprend les propriétés suivantes :
    • streamId — L'identifiant du flux inclus dans l'archive.
    • hasAudio — Si l'audio du flux est inclus dans l'archive.
    • hasVideo — Si la vidéo du flux est incluse dans les archives.

La réponse HTTP renvoie un code d'état 400 dans les cas suivants :

  • Vous ne transmettez pas d'identifiant de session ou vous transmettez un identifiant de session non valide.
  • Aucun client n'est actuellement connecté à la session OpenTok.
  • Vous avez saisi une valeur non valide resolution valeur.
  • Les outputMode est fixée à "individual" et vous définissez le resolution propriété et (qui n'est pas prise en charge dans les archives de flux individuelles).
  • Vous avez saisi une valeur non valide maxBitrate valeur ou si vous spécifiez un maxBitrate valeur correspondant à une archive de flux spécifique. (maxBitrate (n'est pris en charge que pour les archives composées.)
  • Vous avez saisi une valeur non valide quantizationParameter valeur ou si vous spécifiez un quantizationParameter valeur correspondant à une archive de flux spécifique. (quantizationParameter (n'est pris en charge que pour les archives composées.)
  • Vous devez indiquer à la fois un maxBitrate et un quantizationParameter propriété.

La réponse HTTP renvoie un code d'état 403 si vous fournissez une clé API OpenTok ou un jeton JWT non valide.

La réponse HTTP renvoie un code d'état 404 si la session n'existe pas, ou si la session existe mais qu'aucun client n'y est connecté.

La réponse HTTP renvoie un code d'état 409 si vous tentez de lancer l'archivage d'une session qui n'utilise pas OpenTok Media Router. Il en va de même si vous tentez de lancer l'archivage d'une session déjà en cours d'enregistrement sans avoir défini le multiArchiveTag option. Ou si vous essayez de lancer une archivage simultané pour une session sans définir un identifiant unique multiArchiveTag valeur.

La réponse HTTP affiche un code d'état 500 correspondant à une erreur du serveur OpenTok.

Exemple

L'exemple de ligne de commande suivant permet de lancer l'enregistrement d'une session 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
  • Définir la valeur de api_key à votre clé API OpenTok.
  • Définir la valeur de json_web_token en un jeton Web JSON (voir Authentification).
  • Régler le session_id à l'identifiant de la session OpenTok que vous souhaitez archiver.
  • Régler le name ajouter une valeur au nom de l'archive (cette étape est facultative).

Arrêt d'un enregistrement d'archives

Pour arrêter l'enregistrement d'une archive, envoyez une requête HTTP POST.

Les archives cessent d'enregistrer au bout de 4 heures (14 400 secondes), ou 60 secondes après la déconnexion du dernier client de la session, ou 60 minutes après que le dernier client a cessé de publier. Cependant, archives automatiques continuer l'enregistrement dans plusieurs fichiers consécutifs d'une durée maximale de 4 heures chacun. Pour plus d'informations, consultez Durée de conservation des archives

L'appel de cette méthode pour archives automatiques n'a aucun effet. L'archivage automatique continue d'enregistrer dans plusieurs fichiers consécutifs d'une durée maximale de 4 heures (14 400 secondes) chacun, jusqu'à 60 secondes après la déconnexion du dernier client de la session, ou 60 minutes après que le dernier client a cessé de diffuser un flux vers la session.

Requête HTTP POST vers l'archive

Envoyez une requête HTTP POST à l'URL suivante :

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

Remplacer <api_key> avec votre clé API OpenTok. Consultez la page de votre projet sur votre Video API Account.

Remplacer <archive_id> avec l'identifiant d'archive. Vous pouvez obtenir cet identifiant d'archive à partir de la réponse à l'appel d'API vers commencer l'enregistrement de l'archive.

Remarque : Auparavant, cette URL REST utilisait /partner (qui est désormais obsolète) au lieu de /project.

Propriétés de l'en-tête POST

Les appels API doivent être authentifiés à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH — ainsi qu’un jeton Web JSON (JWT). Voir Authentification.

Réponse

Les données brutes de la réponse HTTP, dont le code d'état est 200, constituent un message encodé au format JSON se présentant sous la forme suivante :

{
  "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
}

L'objet JSON comprend les propriétés suivantes :

  • createdAt — L'horodatage correspondant au moment où l'archivage a commencé, exprimé en millisecondes depuis l'époque Unix (1er janvier 1970, 00:00:00 UTC).
  • hasAudio — Indique si l'archive enregistrera le son (vrai) ou non (faux).
  • hasVideo — Indique si l'archive enregistrera des vidéos (vrai) ou non (faux).
  • id — L'identifiant unique de l'archive.
  • multiArchiveTag — L'identifiant unique des archives simultanées (si un tel identifiant a été défini).
  • outputMode — Soit "composed" ou "individual". Voir Archives individuelles de flux et composées.
  • projectId — Votre clé API OpenTok.
  • resolution — La résolution de l'archive (soit « 640x480 », « 1280x720 », « 1920x1080 », « 480x640 », « 720x1280 » ou « 1080x1920 »). Cette propriété n’est définie que pour les archives composées.
  • sessionId — L'identifiant de la session OpenTok qui a été archivée.
  • name — Le nom de l'archive que vous avez fournie (facultatif)
  • size — Lorsque l'archivage est interrompu (et qu'il n'a pas encore été généré), la taille est définie sur 0.
  • status - Cette valeur est fixée à "stopped".
  • streamMode — La sélection des flux inclus dans les archives se fait-elle automatiquement ("auto", valeur par défaut) ou manuellement ("manual").
  • streams — Un tableau d'objets correspondant aux flux en cours d'archivage. Cette valeur n'est définie que pour une archive avec le status fixé à "started" et le streamMode fixé à "manual". Chaque objet du tableau comprend les propriétés suivantes :
    • streamId — L'identifiant du flux inclus dans l'archive.
    • hasAudio — Si l'audio du flux est inclus dans l'archive.
    • hasVideo — Si la vidéo du flux est incluse dans les archives.

La réponse HTTP renvoie un code d'état 400 si vous ne fournissez pas d'identifiant de session ou si vous fournissez un identifiant de session non valide.

La réponse HTTP renvoie un code d'état 403 si vous fournissez une clé API OpenTok ou un jeton JWT non valide.

La réponse HTTP renvoie un code d'état 404 si vous indiquez un identifiant d'archive non valide.

La réponse HTTP renvoie un code d'état 409 si vous tentez d'arrêter une archive qui n'est pas en cours d'enregistrement.

La réponse HTTP affiche un code d'état 500 correspondant à une erreur du serveur OpenTok.

Exemple

L'exemple de ligne de commande suivant permet d'arrêter l'enregistrement d'une session 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
  • Définir la valeur de api_key à votre clé API OpenTok.
  • Définir la valeur de json_web_token en un jeton Web JSON (voir Authentification).
  • Régler le id valeur à l'identifiant d'archive. Vous pouvez obtenir cet identifiant d'archive à partir de la réponse à l'appel d'API vers commencer l'enregistrement de l'archive.

Archives des annonces

Pour obtenir la liste des archives associées à votre clé API, qu'elles soient terminées ou en cours, envoyez une requête HTTP GET.

Remarque : Les archives sont conservées pendant une durée maximale de 12 mois.

Requête HTTP GET vers l'archive

Envoyez une requête HTTP GET à l'URL suivante :

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

Remplacer <api_key> avec votre clé API OpenTok. Consultez la page du projet dans votre Video API Account.

Remarque : Auparavant, cette URL REST utilisait /partner (qui est désormais obsolète) au lieu de /project.

Vous pouvez ajouter des paramètres de requête pour filtrer les résultats (ces paramètres sont facultatifs) :

  • Définir un offset paramètres de requête permettant de spécifier le décalage d'index de la première archive. 0 correspond au décalage de l'archive la plus récente (à l'exclusion des archives supprimées). 1 correspond au décalage de l'archive qui a été créée avant l'archive la plus récente. La valeur par défaut est 0.

  • Fixer un count paramètre de requête permettant de limiter le nombre d'archives renvoyées. Le nombre par défaut d'archives renvoyées est de 50 (ou moins, s'il y a moins de 50 archives). Le nombre maximal d'archives que l'appel renverra est de 1 000.

  • Fixer un sessionId Paramètre de requête permettant d'afficher la liste des archives associées à un identifiant de session spécifique. (Cette fonction est utile pour afficher la liste de plusieurs archives pour un archivée automatiquement session.)

Par exemple, l'appel suivant spécifie un count et offset valeurs :

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

L'appel suivant spécifie un (faux) sessionId valeur :

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

Les archives supprimées ne sont pas incluses dans les résultats de cet appel d'API.

Remplacer <api_key> avec votre clé API OpenTok. Consultez la page du projet dans votre Video API Account.

Propriétés de l'en-tête GET

Les appels API doivent être authentifiés à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH — ainsi qu’un jeton Web JSON (JWT). Voir Authentification.

Réponse

Les données brutes de la réponse HTTP, dont le code d'état est 200, constituent un message encodé au format JSON se présentant sous la forme suivante :

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

L'objet JSON comprend les propriétés suivantes :

  • count — Le nombre total d'archives associées à la clé API.
  • items — Un tableau d'objets définissant chaque archive récupérée. Les archives sont classées par ordre chronologique décroissant (de la plus récente à la plus ancienne) dans le jeu de résultats.

Chaque objet d'archive (élément) possède les propriétés suivantes :

  • createdAt — L'horodatage correspondant au moment où l'archivage a commencé, exprimé en millisecondes depuis l'époque Unix (1er janvier 1970, 00:00:00 UTC).
  • duration — La durée de l'archive en secondes. Pour les archives en cours d'enregistrement (dont la propriété « status » est définie sur « started »), cette valeur est fixée à 0.
  • hasAudio — Indique si l'archive enregistrera le son (vrai) ou non (faux).
  • hasVideo — Indique si l'archive enregistrera des vidéos (vrai) ou non (faux).
  • id — L'identifiant unique de l'archive.
  • multiArchiveTag — L'identifiant unique des archives simultanées (si un tel identifiant a été défini).
  • name — Le nom de l'archive que vous avez fournie (facultatif)
  • outputMode — Soit "composed" ou "individual". Voir Archives individuelles de flux et composées.
  • projectId — Votre clé API OpenTok.
  • reason — Pour les archives ayant le statut "stopped", elle peut être réglée sur "maximum duration exceeded", "maximum idle time exceeded", "session ended", "user initiated". Pour les archives dont le statut est "failed", elle peut être réglée sur "failure".
  • sessionId — L'identifiant de la session OpenTok qui a été archivée.
  • status — État des archives :

    • "available" — L'archive peut être téléchargée depuis le cloud OpenTok.

    • "expired" — L'archive n'est plus disponible au téléchargement depuis le cloud OpenTok.

    • "failed" — L'enregistrement dans les archives a échoué.

    • "paused" — Lorsqu'un enregistrement est mis en pause, rien n'est enregistré. L'enregistrement est mis en pause si l'une des conditions suivantes se produit :

      • Aucun client ne publie de flux vers la session. Dans ce cas, le délai d'expiration est de 60 minutes ; passé ce délai, l'archivage s'arrête et l'état de l'archivage passe à "stopped".
      • Tous les clients se déconnectent de la session. Au bout de 60 secondes, l'archivage s'arrête et l'état de l'archivage passe à "stopped".

      Si un client reprend la publication alors que l'archive est à l'état « en pause », l'enregistrement de l'archive reprend et l'état repasse à "started".

    • "started" — L'archivage a commencé et l'enregistrement est en cours.

    • "stopped" — L'archive a cessé d'enregistrer.

    • "uploaded" — L'archive peut être téléchargée à partir du compartiment S3 que vous avez indiqué dans votre Video API Account.

  • streamMode — La sélection des flux inclus dans les archives se fait-elle automatiquement ("auto", valeur par défaut) ou manuellement ("manual").
  • resolution — La résolution de l'archive (soit « 640x480 », « 1280x720 », « 1920x1080 », « 480x640 », « 720x1280 » ou « 1080x1920 »). Cette propriété n’est définie que pour les archives composées.
  • size — La taille du fichier d'archive. Pour les archives qui n'ont pas encore été générées, cette valeur est définie sur 0.
  • streamMode — Si tous les flux sont inclus dans l'archive ("auto") ou vous sélectionnez les flux à inclure dans l'archive ("manual"). Voir aussi Sélection des flux à inclure dans une archive.
  • streams — Un tableau d'objets correspondant aux flux en cours d'archivage. Cette valeur n'est définie que pour une archive avec le status fixé à "started" et le streamMode fixé à "manual". Chaque objet du tableau comprend les propriétés suivantes :
    • streamId — L'identifiant du flux inclus dans l'archive.
    • hasAudio — Si l'audio du flux est inclus dans l'archive.
    • hasVideo — Si la vidéo du flux est incluse dans les archives.
  • url — L'URL de téléchargement du fichier d'archive disponible. Elle n'est définie que pour une archive dont le statut est défini sur "available"; pour les autres archives, (y compris les archives ayant le statut "uploaded") cette propriété est définie sur null. L'URL de téléchargement est masquée, et le fichier n'est accessible via cette URL que pendant 10 minutes. Pour générer une nouvelle URL, utilisez l'API REST pour recherche d'informations dans les archives ou archives des listes.

La réponse HTTP renvoie un code d'état 403 si vous fournissez une clé API OpenTok ou un jeton JWT non valide.

La réponse HTTP affiche un code d'état 500 correspondant à une erreur du serveur OpenTok.

Exemple

L'exemple de ligne de commande suivant permet de récupérer des informations sur toutes les archives :

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
  • Définir la valeur de api_key à votre clé API OpenTok.
  • Définir la valeur de json_web_token en un jeton Web JSON (voir Authentification).

Récupération d'informations d'archives

Pour récupérer des informations sur une archive spécifique, envoyez une requête HTTP GET.

Remarque : Les archives sont conservées pendant une durée maximale de 12 mois.

Vous pouvez également récupérer des informations sur plusieurs archives. Voir Archives des annonces.

Requête HTTP GET vers l'archive

Envoyez une requête HTTP GET à l'URL suivante :

https://api.opentok.com/v2/project/<api_key>/archive/<archive_id>
  • Remplacer <api_key> avec votre clé API OpenTok. Consultez la page du projet de votre Video API Account.
  • Remplacer <archive_id avec l'identifiant de l'archive.

Remarque : Auparavant, cette URL REST utilisait /partner (qui est désormais obsolète) au lieu de /project.

Propriétés de l'en-tête GET

Les appels API doivent être authentifiés à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH — ainsi qu’un jeton Web JSON (JWT). Voir Authentification.

Réponse

Les données brutes de la réponse HTTP, dont le code d'état est 200, constituent un message encodé au format JSON se présentant sous la forme suivante :

{
  "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"
}

L'objet JSON comprend les propriétés suivantes :

  • createdAt — L'horodatage correspondant au moment où l'archivage a commencé, exprimé en millisecondes depuis l'époque Unix (1er janvier 1970, 00:00:00 UTC).
  • duration — La durée de l'archive en secondes. Pour les archives en cours d'enregistrement (dont la propriété « status » est définie sur « started »), cette valeur est fixée à 0.
  • hasAudio — Indique si l'archive enregistrera le son (vrai) ou non (faux).
  • hasVideo — Indique si l'archive enregistrera des vidéos (vrai) ou non (faux).
  • id — L'identifiant unique de l'archive.
  • multiArchiveTag — L'identifiant unique des archives simultanées (si un tel identifiant a été défini).
  • name — Le nom de l'archive que vous avez fournie (facultatif)
  • outputMode — Soit "composed" ou "individual". Voir Archives individuelles de flux et composées.
  • projectId — Votre clé API OpenTok.
  • reason — Pour les archives ayant le statut "stopped", elle peut être réglée sur "maximum duration exceeded", "maximum idle time exceeded", "session ended", "user initiated". Pour les archives dont le statut est "failed", elle peut être réglée sur "failure".
  • resolution — La résolution de l'archive (soit « 640x480 », « 1280x720 », « 1920x1080 », « 480x640 », « 720x1280 » ou « 1080x1920 »). Cette propriété n’est définie que pour les archives composées.
  • sessionId — L'identifiant de la session OpenTok qui a été archivée.
  • status — État des archives :

    • "available" — L'archive peut être téléchargée depuis le cloud OpenTok.

    • "deleted" — L'archive a été supprimée.

    • "expired" — L'archive n'est plus disponible au téléchargement depuis le cloud OpenTok.

    • "failed" — L'enregistrement dans les archives a échoué.

    • "paused" — Lorsqu'un enregistrement est mis en pause, rien n'est enregistré. L'enregistrement est mis en pause si l'une des conditions suivantes se produit :

      • Aucun client ne publie de flux vers la session. Dans ce cas, le délai d'expiration est de 60 minutes ; passé ce délai, l'archivage s'arrête et l'état de l'archivage passe à "stopped".
      • Tous les clients se déconnectent de la session. Au bout de 60 secondes, l'archivage s'arrête et l'état de l'archivage passe à "stopped".

      Si un client reprend la publication alors que l'archive se trouve dans le "paused" état, l'enregistrement d'archive reprend et l'état revient à "started".

    • "started" — L'archivage a commencé et l'enregistrement est en cours.

    • "stopped" — L'archive a cessé d'enregistrer.

    • "uploaded" — L'archive peut être téléchargée à partir du compartiment S3 que vous avez indiqué dans votre Video API Account.

  • size — La taille du fichier d'archive. Pour les archives qui n'ont pas encore été générées, cette valeur est définie sur 0.
  • streamMode — Si tous les flux sont inclus dans l'archive ("auto") ou vous sélectionnez les flux à inclure dans l'archive ("manual"). Voir aussi Sélection des flux à inclure dans une archive.
  • streams — Un tableau d'objets correspondant aux flux en cours d'archivage. Cette valeur n'est définie que pour une archive dont le statut est défini sur "started" et le streamMode fixé à "manual". Chaque objet du tableau comprend les propriétés suivantes :
    • streamId — L'identifiant du flux inclus dans l'archive.
    • hasAudio — Si l'audio du flux est inclus dans l'archive.
    • hasVideo — Si la vidéo du flux est incluse dans les archives.
  • url — L'URL de téléchargement du fichier d'archive disponible. Elle n'est définie que pour une archive dont le statut est défini sur "available"; pour les autres archives, (y compris les archives ayant le statut "uploaded") cette propriété est définie sur null. L'URL de téléchargement est masquée, et le fichier n'est accessible via cette URL que pendant 10 minutes. Pour générer une nouvelle URL, utilisez l'API REST pour recherche d'informations dans les archives ou archives des listes.

La réponse HTTP renvoie un code d'état 400 si vous ne fournissez pas d'identifiant de session ou si vous fournissez un identifiant d'archive non valide.

La réponse HTTP renvoie un code d'état 403 si vous fournissez une clé API OpenTok ou un jeton JWT non valide.

La réponse HTTP affiche un code d'état 500 correspondant à une erreur du serveur OpenTok.

Exemple

L'exemple de ligne de commande suivant permet de récupérer des informations sur une archive :

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
  • Définir la valeur de api_key à votre clé API OpenTok.
  • Définir la valeur de json_web_token en un jeton Web JSON (voir Authentification).
  • Régler le id valeur à l'identifiant d'archive.

Suppression d'une archive

Pour supprimer une archive, envoyez une requête HTTP DELETE.

Vous ne pouvez supprimer qu'une archive dont le statut est "available" ou "uploaded". La suppression d'une archive entraîne la suppression de son entrée de la liste des archives (voir Archives des annonces). Pour un "available" archive, cela supprime également le fichier d'archive, qui ne sera alors plus disponible au téléchargement.

Requête HTTP DELETE pour l'archivage

Envoyez une requête HTTP DELETE à l'URL suivante :

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

Remplacer <api_key> avec votre clé API OpenTok. Consultez la page du projet de votre Video API Account.

Remplacer <archive_id> avec l'identifiant de l'archive.

Remarque : Auparavant, cette URL REST utilisait /partner (qui est désormais obsolète) au lieu de /project.

Propriétés de l'en-tête DELETE

Les appels API doivent être authentifiés à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH — ainsi qu’un jeton Web JSON (JWT). Voir Authentification.

Réponse

Une réponse HTTP avec un code d'état 204 indique que l'archive a été supprimée.

La réponse HTTP renvoie un code d'état 403 si vous transmettez une clé API OpenTok non valide, un jeton JWT non valide ou un identifiant d'archive non valide.

La réponse HTTP renvoie un code d'état 409 si l'état de l'archive n'est pas "uploaded", "available"ou "deleted".

La réponse HTTP affiche un code d'état 500 correspondant à une erreur du serveur OpenTok.

Exemple

L'exemple de ligne de commande suivant permet de supprimer une archive :

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
  • Définir la valeur de api_key à votre clé API OpenTok.
  • Définir la valeur de json_web_token en un jeton Web JSON (voir Authentification).
  • Régler le id valeur correspondant à l'identifiant de l'archive à supprimer.

Configuration d'une destination de transfert vers S3 ou Azure pour l'archivage

Dans le cadre d'un projet OpenTok, vous pouvez demander à OpenTok de transférer les archives finalisées vers un compartiment Amazon S3 (ou un fournisseur de stockage compatible S3) ou vers un conteneur Windows Azure.

Remarque : Vous pouvez également définir une destination de téléchargement des archives sur votre Compte Video API de Vonage page.

Pour Amazon S3, vous devrez accorder à Vonage une autorisation de mise en ligne uniquement sur le compartiment Amazon S3. Si vous souhaitez utiliser un utilisateur IAM S3, attribuez-lui la politique d'utilisateur suivante :

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

Pour définir une destination de téléchargement d'archives, envoyez une requête HTTP PUT.

Si vous définissez une destination de téléchargement, chaque fichier d'archive finalisé est téléchargé sous la forme d'un fichier nommé archive.mp4 dans le chemin d'accès /projectKey/archiveId/ du compartiment cible, où projectKey correspond à la clé API du projet, et archiveId correspond à l'identifiant de l'archive.

Si vous avez déjà défini une destination de téléchargement d'archives pour les fichiers d'archives d'un projet, vous pouvez envoyer une autre requête PUT pour enregistrer une nouvelle destination de téléchargement.

Pour plus d'informations sur l'archivage, voir la page Programmation de l'archivage Guide.

Requête HTTP PUT vers l'archive

Envoyez une requête HTTP PUT à l'URL suivante :

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

Remplacer <api_key> avec la clé API du projet OpenTok.

Propriétés de l'en-tête PUT

Authentifiez cet appel API à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Définissez cet en-tête sur un jeton JWT (voir Authentification).

Régler le Content-type à l'en-tête application/json:

Content-Type:application/json

Données PUT

Pour un compartiment Amazon S3, incluez un objet JSON sous la forme suivante dans les données de la requête PUT :

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

L'objet JSON comprend les propriétés suivantes :

  • type - "s3" (pour Amazon S3)

  • config — Paramètres de l’Account Amazon Web Services :

  • accessKey — La clé d'accès à Amazon Web Services

  • secretKey — La clé secrète d'Amazon Web Services

  • bucket — Le nom du compartiment S3.

  • endpoint (facultatif) — Un point de terminaison S3. Ce paramètre est facultatif. Le point de terminaison par défaut est http://s3.amazonaws.com (le point de terminaison d'Amazon S3). Indiquez cette valeur si vous souhaitez utiliser une solution de stockage compatible S3 (autre qu'Amazon S3). Définissez cette valeur sur l'URL de base du point de terminaison, en incluant le protocole (http ou https), par exemple "https://s3.cloudianhyperstore.com" ou "https://storage.googleapis.com". Nous prenons en charge Cloudian et Google Cloud Storage (accessible via l'API AWS S3) en tant que solutions de stockage compatibles S3. D'autres services compatibles S3 peuvent présenter des limitations au niveau des fonctionnalités.

  • fallback — Réglez ce paramètre sur "opentok" pour que l'archive soit disponible dans le tableau de bord OpenTok en cas d'échec du téléchargement. Définissez ce paramètre sur "none" (ou omettre cette propriété) pour empêcher que les fichiers d'archive ne soient stockés dans le cloud OpenTok en cas d'échec du téléchargement.

Pour un conteneur Windows Azure, incluez un objet JSON sous la forme suivante dans les données PUT :

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

L'objet JSON comprend les propriétés suivantes :

  • type - "azure" (pour Microsoft Azure)

  • config — Paramètres de l’account Windows Azure :

  • accountName — Le nom de l’account Windows Azure

  • accountKey — La clé d’account Windows Azure

  • container — Le nom du conteneur Windows Azure.

  • domain (facultatif) — Le domaine Windows Azure dans lequel se trouve le conteneur.

  • fallback — Réglez ce paramètre sur "opentok" pour que l'archive soit disponible dans le tableau de bord OpenTok en cas d'échec du téléchargement. Définissez ce paramètre sur "none" (ou omettre cette propriété) pour empêcher le stockage des fichiers d'archive dans le cloud OpenTok en cas d' échec du téléchargement.

Réponse HTTP

La réponse HTTP comportera l'un des codes d'état suivants :

  • 200 — Réussite. Le corps de la réponse correspond aux données que vous avez envoyées.

  • 400 — Demande non valide. Cette réponse peut indiquer ce qui suit :

  • Le type n'est pas défini.

  • Ce type n'est pas pris en charge (il n'est pas "s3" ou "azure").

  • La configuration n'est pas définie.

  • La valeur de configuration dépasse la limite de taille. Nous chiffrons le paramètre de configuration lors de son enregistrement, et la taille du fichier chiffré ne doit pas dépasser 2 048 caractères.

  • Les données de votre requête contiennent du code JSON non valide.

    • 403 — Erreur d'authentification. Vous avez fourni un jeton non valide dans le X-OPENTOK-AUTH l'en-tête.

Exemple

L'exemple de ligne de commande suivant permet de définir un compartiment S3 pour un projet :

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

  • Définir la valeur de token vers un jeton JWT OpenTok valide.

  • Définir la valeur de projectKey à la clé API du projet.

  • Régler le storage_type valeur à "s3".

  • Régler le access_key à la clé d'accès de votre compte Amazon Web Services .

  • Régler le secret_key à la clé secrète de votre compte Amazon Web Services .

  • Régler le bucket valeur au nom du compartiment.

Suppression d'une destination de téléchargement d'archivage

Si vous avez défini une destination de téléchargement pour les fichiers d'archive d'un projet, vous pouvez la supprimer.

Remarque : Vous pouvez également supprimer une destination de téléchargement d'archives sur votre Compte Video API de Vonage page.

Requête HTTP DELETE pour l'archivage

Envoyez une requête HTTP DELETE à l'URL suivante :

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

Remplacer <project_key> avec la clé API du projet.

Propriétés de l'en-tête DELETE

Authentifiez cet appel API à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH :

X-OPENTOK-AUTH:<token>

Définissez cet en-tête sur un jeton JWT (voir Authentification).

Réponse

La réponse HTTP comportera l'un des codes d'état suivants :

  • 204 — Réussite (pas de contenu).

  • 403 — Erreur d'authentification. Vous avez fourni un jeton non valide dans l'en-tête X-OPENTOK-AUTH.

  • 404 — Aucune destination de téléchargement n'existe.

### Exemple

L'exemple de ligne de commande suivant permet de supprimer une destination de téléchargement pour un projet :

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

  • Définir la valeur de token vers un jeton JWT OpenTok valide.

  • Définir la valeur de projectKey à la clé API du projet.

Modification dynamique du type de mise en page d'une archive composée

Vous pouvez modifier dynamiquement le type de mise en page d'une archive composée pendant son enregistrement.

Pour plus d'informations sur l'archivage composé, consultez le Guide du développeur sur l'archivage OpenTok et Personnalisation de la mise en page vidéo pour les composées.

Requête HTTP PUT vers l'archive

Envoyez une requête HTTP PUT à l'URL suivante :

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

Remplacer <apiKey> avec votre clé API OpenTok.

Remplacer <archiveId> avec l'identifiant de l'archive.

Propriétés de l'en-tête PUT

Régler le Content-Type à l'en-tête application/json.

Authentifiez cet appel API à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH — définir sur un jeton Web JSON. Voir Authentification.

Données PUT

Incluez un objet JSON se présentant sous la forme suivante dans le corps de la requête :

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

L'objet JSON comprend les propriétés suivantes :

  • type (Chaîne) — Type de structure de l'archive. Les valeurs valides sont : "bestFit" (meilleur ajustement), "custom" (personnalisé), "horizontalPresentation" (présentation horizontale), "pip" (image dans l'image), et "verticalPresentation" (présentation verticale). Si vous spécifiez un "custom" définir le type de mise en page stylesheet propriété à la feuille de style. (Pour les autres types de mise en page, ne définissez pas la stylesheet propriété.) Pour plus d'informations, consultez Personnalisation de la présentation vidéo pour les archives composées.

    Lorsque vous spécifiez un type de mise en page autre que « Best Fit », veillez à appliquer les classes de mise en page appropriées aux flux de la session OpenTok (voir Attribution de classes de mise en page de diffusion en direct aux flux OpenTok streams).

  • feuille de style (Chaîne) — Facultatif. Ne le spécifiez que si vous définissez le type propriété à "custom". Régler le stylesheet propriété à la feuille de style. (Pour les autres types de mise en page, ne définissez pas la stylesheet propriété.) Pour plus d'informations, voir Définir des mises en page personnalisées.

  • type de partage d'écran (Chaîne) — Facultatif. Type de mise en page à utiliser lorsqu’il y a un flux de partage d’écran dans la session. Notez que pour utiliser cette propriété, vous devez définir la type à "bestFit" et laisser la propriété stylesheet Propriété non définie. Pour plus d'informations, voir Types de mise en page pour le partage d'écran.

Réponse

La réponse HTTP comportera l'un des codes d'état suivants :

  • 200 — Réussite.
  • 400 — Demande non valide. Cette réponse peut indiquer que les données contenues dans votre requête sont au format JSON non valide. Elle peut également indiquer que vous avez fourni des options de mise en page non valides.
  • 403 — Erreur d'authentification.
  • 500 — Erreur du serveur OpenTok.

Exemple

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

Modification des classes de mise en page des archives composées pour un flux OpenTok

Utilisez cette méthode pour modifier les classes de mise en page d'un flux OpenTok. Les classes de mise en page définissent la manière dont le flux s'affiche dans la mise en page d'une archive OpenTok composée. Pour plus d'informations, consultez Attribution de classes de mise en page de diffusion en direct aux flux OpenTok streams.

Requête HTTP PUT vers le flux

Envoyez une requête HTTP PUT à l'URL suivante :

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

Remplacer <apiKey> avec votre clé API OpenTok. Remplacez <sessionId> avec l'identifiant de session.

Propriétés de l'en-tête PUT

Régler le Content-Type à l'en-tête application/json.

Authentifiez cet appel API à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH — définir sur un jeton Web JSON. Voir Authentification.

Données PUT

Incluez un objet JSON se présentant sous la forme suivante dans le corps de la requête :

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

L'objet JSON contient un items tableau d'objets. Chaque objet définit les classes de mise en page à attribuer à un flux, et contient les propriétés suivantes :

  • id (Chaîne) — L'identifiant du flux.
  • layoutClassList (Tableau) — Tableau de classes de mise en page (chacune sous forme de chaîne de caractères) pour le flux.

Vous pouvez mettre à jour la liste des classes de mise en page pour plusieurs flux en transmettant plusieurs objets JSON dans le items de la gamme.

Réponse

La réponse HTTP comportera l'un des codes d'état suivants :

  • 200 — Réussite.
  • 400 — Demande non valide. Cette réponse peut indiquer que les données contenues dans votre requête sont au format JSON non valide. Elle peut également indiquer que vous avez fourni des options de mise en page non valides.
  • 403 — Erreur d'authentification.
  • 500 — Erreur du serveur OpenTok.

Exemple

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

Sélection des flux à inclure dans une archive

Utilisez cette méthode pour modifier les flux inclus dans une archive composée qui a été créée à l'aide de la commande streamMode fixé à "manual" (voir Démarrage d'un enregistrement d'archives).

Le compositeur d'archives inclut des flux ajoutés sur la base de règles de hiérarchisation des cours d'eau.

Requête HTTP PATCH vers archive/streams

Envoyez une requête HTTP PATCH à l'URL suivante :

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

Remplacer <apiKey> avec votre clé API OpenTok. Remplacez <archiveId> avec l'identifiant de l'archive.

Propriétés de l'en-tête PATCH

Régler le Content-Type à l'en-tête application/json.

Authentifiez cet appel API à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH — définir sur un jeton Web JSON. Voir Authentification.

Données PATCH

Pour ajouter un flux à l'archive, incluez un objet JSON sous la forme suivante dans le corps de la requête :

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

L'objet JSON contient les propriétés suivantes :

  • addStream (Chaîne) — L'identifiant du flux.
  • hasAudio (Booléen, facultatif) — Indique si l'archive générée doit inclure l'audio du flux (true, valeur par défaut) ou non (false).
  • hasVideo (Booléen, facultatif) — Indique si l'archive générée doit inclure la vidéo du flux (true, valeur par défaut) ou non (false).

Vous pouvez appeler cette méthode à plusieurs reprises à l'aide de addStream définis sur le même identifiant de flux, pour activer ou désactiver le son ou la vidéo du flux dans les archives.

Si vous configurez les deux hasAudio et hasVideo à false, vous obtiendrez une réponse d'erreur.

Pour empêcher qu'un flux ne soit inclus dans l'archive, ajoutez un objet JSON se présentant sous la forme suivante dans le corps de la requête :

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

Régler le removeStream propriété associée à l'identifiant du flux.

Réponse

La réponse HTTP comportera l'un des codes d'état suivants :

  • 204 — Réussite (pas de contenu).
  • 400 — Demande non valide. Cette réponse peut indiquer que les données fournies dans votre demande sont au format JSON non valide, ou que la demande n'a pas pu être traitée car l'archivage a été lancé avec streamMode fixé à "auto", qui ne prend pas en charge la manipulation des flux.
  • 403 — Erreur d'authentification.
  • 404 — Archive ou flux introuvable.
  • 500 — Erreur du serveur OpenTok.

Exemples

Ajouter un flux à une archive :

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

Supprimer la vidéo d'un flux dans une archive (tout en conservant l'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

Supprimer un flux d'une archive :

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

Lancer un appel SIP

Pour connecter votre plateforme SIP à une session OpenTok, envoyez une requête HTTP POST à l'adresse dial méthode. Le flux audio provenant de votre terminal SIP est ajouté à la session OpenTok sous la forme d'un flux exclusivement audio. Le routeur multimédia OpenTok mélange ce flux avec ceux des autres participants à la session, puis envoie le flux audio mixé à votre terminal SIP.

L'appel prend fin lorsque votre serveur SIP envoie un BYE message (pour mettre fin à l'appel). Vous pouvez également mettre fin à un appel à l'aide de la méthode de l'API REST OpenTok permettant de déconnecter un client d'une session. La passerelle SIP OpenTok met automatiquement fin à un appel après 5 minutes d'inactivité (5 minutes sans réception de données multimédia). De plus, par mesure de sécurité, la passerelle SIP OpenTok met fin à tout appel SIP qui dure plus de 6 heures.

La fonctionnalité d'interconnexion SIP nécessite l'utilisation d'une session OpenTok qui utilise le Routeur multimédia OpenTok (une session dont le mode média est défini sur « routé »).

Pour plus d'informations, y compris les détails techniques et les considérations relatives à la sécurité, voir le document Interconnexion SIP OpenTok guide du développeur.

Requête HTTP POST pour composer un numéro

Envoyez une requête HTTP POST à l'URL suivante :

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

Remplacer <api_key> avec votre clé API OpenTok. Consultez la page du projet de votre Video API Account.

Remarque : Auparavant, cette URL REST utilisait /partner (qui est désormais obsolète) au lieu de /project.

Propriétés de l'en-tête POST

Les appels API doivent être authentifiés à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH — ainsi qu’un jeton Web JSON (JWT). Voir Authentification.

Définissez l'en-tête « Content-type » sur « application/json » :

Content-Type:application/json

Données POST

Incluez un objet JSON sous la forme suivante dans les données 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"]
  }
}

L'objet JSON comprend les propriétés suivantes :

  • sessionId​ (obligatoire) — L'identifiant de session OpenTok correspondant à l'appel SIP auquel vous souhaitez vous joindre.
  • token​ (obligatoire) — Le jeton OpenTok à utiliser pour le participant appelé. Vous pouvez ajouter un jeton data pour vérifier que le participant utilise un terminal SIP ou pour obtenir d'autres données d'identification, telles que des numéros de téléphone. (Les bibliothèques client OpenTok comprennent des propriétés permettant d'examiner les données de connexion d'un client connecté à une session.) Voir la Création de jetons guide du développeur.

  • SIP uri​ ​(obligatoire) — L'URI SIP à utiliser comme destination de l'appel SIP lancé depuis OpenTok vers votre plateforme SIP.

    Si le SIP ​uri​ contient un ​transport=tls​ en-tête, la négociation entre Vonage et le terminal SIP s'effectuera de manière sécurisée. Notez que cela ne s'applique qu'à la négociation elle-même, et non à la transmission audio. Si vous souhaitez également que la transmission audio soit chiffrée, configurez le ​secure​ propriété à ​true​.

    Il s'agit d'un exemple de négociation d'appel sécurisée :

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

    Il s'agit d'un exemple de négociation d'appel non sécurisée :

    "sip:user@sip.partner.com"

  • from ​(facultatif) : Le numéro ou la chaîne de caractères qui sera transmis au numéro SIP final en tant qu'appelant. Il doit s'agir d'une chaîne de caractères sous la forme from@example.comoù from peut être une chaîne composée de caractères alphabétiques (a-z, A-Z, 0-9) ou des caractères _, +, !, %, `, ', ~ou -.

    Si from est fixé à un nombre (par exemple, "<14155550101@example.com>"), il s'affichera comme numéro de l'appelant sur les téléphones du réseau PSTN. Si from n'est pas défini ou est défini sur une chaîne de caractères (par exemple, "<joe@example.com>"), +00000000 s'affichera comme numéro entrant sur les téléphones RTC.

    Si from est indéfini, ou défini comme une chaîne de caractères (par exemple, "<joe@example.com>"), c'est-à-dire un numéro non reconnu ou non autorisé, celui-ci sera, dans la plupart des cas, converti en "Unknown" avant que la requête ne soit transmise à un opérateur en vue de la terminaison sur le réseau PSTN par les fournisseurs SIP. Selon le fournisseur, "Unknown" s'affichera comme numéro de l'appelant sur les téléphones du réseau PSTN. Dans certains cas, les opérateurs peuvent bloquer ces appels pour des raisons de sécurité, afin d'éviter des problèmes tels que l'usurpation de numéro. Si l'appel n'est pas bloqué par les opérateurs, +00000000 s'affichera comme numéro de l'appelant sur les téléphones du réseau PSTN.

    Un numéro est considéré comme non reconnu lorsqu'il n'est pas conforme à la norme E.164 ou qu'il ne s'agit pas d'un Numéro virtuel Vonage si vous vous connectez à la Vonage Voice API, par exemple.

  • SIP headers​​ (facultatif) — Cet objet définit les en-têtes personnalisés à ajouter au SIP ​INVITE​ initiée par OpenTok vers votre plateforme SIP.

  • SIP auth​ (facultatif) — Cet objet contient le nom d'utilisateur et le mot de passe à utiliser dans le protocole SIP INVITE​ pour l'authentification HTTP digest, si elle est requise par votre plateforme SIP.

  • secure​ (facultatif) — Un indicateur booléen précisant si le contenu multimédia doit être transmis sous forme chiffrée (​true​) ou non (​false​(par défaut).

  • video (facultatif) — Un indicateur booléen précisant si l'appel SIP inclura de la vidéo (​true​) ou non (​false​, valeur par défaut). Lorsque la vidéo est activée, la vidéo du client SIP est intégrée au flux OpenTok envoyé à la session OpenTok. La vidéo SIP est limitée à une résolution de 480p et un débit de 800 kbps. Le client SIP recevra une seule vidéo composite regroupant les flux publiés dans la session OpenTok.

  • observeForceMute (facultatif) Un indicateur booléen indiquant si le point d'extrémité SIP respecte force mute moderation (true) ou non (false(par défaut). De même, avec observeForceMute fixé à true, l'appelant peut appuyer sur « *6 » pour activer ou désactiver le son de l'audio diffusé. Pour que la commande « *6 » de mise en sourdine fonctionne, l'appelant SIP doit prendre en charge les signaux DTMF conformes à la norme RFC 2833 (chiffres RFC 2833/RFC 4733). La fonction de mise en sourdine n’est pas prise en charge avec les DTMF SIP INFO ou en bande. Un message (en anglais) est diffusé à l’appelant lorsqu’il active ou désactive la sourdine, ou lorsque le client SIP est mis en sourdine de manière forcée.

  • streams (facultatif) — Tableau contenant les identifiants des flux à inclure dans l'appel SIP. Si vous ne définissez pas cette propriété, tous les flux de la session sont inclus dans l'appel.

Réponse

Les données brutes de la réponse HTTP, dont le code d'état est 200, constituent un message encodé au format JSON se présentant sous la forme suivante :

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

L'objet JSON comprend les propriétés suivantes :

  • id - Un identifiant unique pour l'appel SIP.
  • connectionId — L'identifiant de connexion OpenTok correspondant à la connexion de l'appel SIP dans la session OpenTok. Vous pouvez utiliser cet identifiant de connexion pour mettre fin à l'appel SIP à l'aide de l'API REST OpenTok.
  • streamId — L'identifiant de flux OpenTok correspondant au flux de l'appel SIP dans la session OpenTok.

La réponse HTTP renvoie un code d'état 400 dans les cas suivants :

  • Vous ne transmettez pas d'identifiant de session ou vous transmettez un identifiant de session non valide.

La réponse HTTP renvoie un code d'état 403 si vous fournissez une clé API OpenTok ou un jeton Web JSON non valide.

La réponse HTTP renvoie un code d'état 404 si la session n'existe pas.

La réponse HTTP renvoie un code d'état 409 si vous tentez de lancer un appel SIP pour une session qui n'utilise pas le routeur multimédia OpenTok.

La réponse HTTP affiche un code d'état 500 correspondant à une erreur du serveur OpenTok.

Exemple

L'exemple de ligne de commande suivant permet de connecter votre terminal SIP à une session 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
  • Définir la valeur de api_key à votre clé API OpenTok.
  • Définir la valeur de json_web_token en un jeton Web JSON (voir Authentification).
  • Régler le session_id à l'identifiant de session OpenTok auquel vous souhaitez vous connecter depuis votre plateforme SIP.
  • Régler le sip_uri à l'URI SIP de votre terminal SIP.
  • Régler le token de la propriété data JSON en un jeton de connexion OpenTok valide pour le participant appelé (voir la Création de jetons guide du développeur).
  • Régler le username et password les propriétés de la data JSON contenant le nom d'utilisateur et le mot de passe de votre terminal SIP. (Cette étape est facultative.)

Envoi de chiffres DTMF aux clients SIP

Utilisez l'API REST « play-dtmf » pour envoyer des chiffres DTMF à tous les participants d'une session OpenTok active ou à un client spécifique connecté à cette session.

Les événements de téléphonie sont négociés via le protocole SDP et transmis sous forme de chiffres conformes aux normes RFC 4733/RFC 2833 au terminal distant.

Envoyer des chiffres DTMF à tous les clients connectés à la session

Envoyez une requête HTTP POST à l'URL suivante :

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

Remplacer <api_key> avec votre clé API OpenTok. Consultez la page « Projet » de votre Video API Account. Remplacer <session_id> avec l'identifiant de la session à laquelle vous envoyez le signal DTMF.

Le message DTMF est ignoré par les clients qui ne prennent pas en charge le DTMF (tels que les clients non SIP).

Propriétés de l'en-tête POST

Les appels API doivent être authentifiés à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH — ainsi que d'un jeton Web JSON (JWT). Voir Authentification.

Régler le Content-type à l'en-tête application/json:

Content-Type:application/json

Données POST

Incluez un objet JSON sous la forme suivante dans les données POST :

{ "digits": "1713" }

L'objet JSON contient un digits propriété. Il s'agit de la chaîne de chiffres DTMF à envoyer. Elle peut inclure 0-9, « * », « # » et « p ». A p indique une pause de 500 ms (si vous devez ajouter un délai dans l'envoi des chiffres).

Réponse

Lorsqu'un appel aboutit, la réponse contient un code d'état HTTP 200.

En cas d'erreur, la réponse contient l'un des codes d'état HTTP suivants :

  • 400 — L'un des biens immobiliers — digits ou sessionId — n'est pas valide.

  • 403 — Erreur d'authentification. Cela peut se produire si vous utilisez une clé API OpenTok non valide ou un jeton Web JSON non valide

  • 404 — La session indiquée n'existe pas.

En cas d'erreur, le corps de la réponse sera au format JSON et contiendra un code et message propriété :

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

Exemple

Le code suivant envoie une requête HTTP POST vers le play-dtmf ressource de la session :

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

Envoyer des tonalités DTMF à un client spécifique connecté à la session

Envoyez une requête HTTP POST à l'URL suivante :

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

Remplacer <api_key> avec votre clé API OpenTok. Consultez la page du projet de votre Video API Account. Remplacer <session_id> avec l'identifiant de la session à laquelle vous envoyez le signal DTMF. Remplacez <connection_id> avec l'identifiant de connexion du client auquel vous envoyez le signal DTMF.

Vous pouvez obtenir l'identifiant de connexion d'un client SIP à partir de la réponse à l'appel de l'API REST vers lancer l'appel SIP.

Si vous envoyez des chiffres DTMF à un client qui ne prend pas en charge le DTMF (comme un client non SIP), celui-ci ignore la requête.

Propriétés de l'en-tête POST

Les appels API doivent être authentifiés à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH — ainsi que d'un jeton Web JSON (JWT). Voir Authentification.

Régler le Content-type à l'en-tête application/json:

Content-Type:application/json

Données POST

Incluez un objet JSON sous la forme suivante dans les données POST :

{ "digits": "1713" }

L'objet JSON contient un digits propriété. Il s'agit de la chaîne de chiffres DTMF à envoyer. Elle peut inclure 0-9, « * », « # » et « p ». A p indique une pause de 500 ms (si vous devez ajouter un délai dans l'envoi des chiffres).

Réponse

Lorsqu'un appel aboutit, la réponse contient un code d'état HTTP 200.

En cas d'erreur, la réponse contient l'un des codes d'état HTTP suivants :

  • 400 — L'un des biens immobiliers — digits ou sessionId — n'est pas valide.

  • 403 — Erreur d'authentification. Cela peut se produire si vous utilisez une clé API OpenTok non valide ou un jeton Web JSON non valide

  • 404 — La session indiquée n'existe pas ou le client spécifié par le connectionId La propriété n'est pas associée à la session.

En cas d'erreur, le corps de la réponse sera au format JSON et contiendra un code et message propriété :

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

Exemple

Envoyez une requête HTTP POST à l'adresse play-dtmf ressource associée à un identifiant de connexion spécifique appartenant à la session :

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

Lancer une diffusion en direct

Utilisez cette méthode pour lancer une diffusion en direct pour une session OpenTok. Cela permet de diffuser la session via un flux HLS (HTTP Live Streaming) ou RTMP.

Pour lancer avec succès la diffusion d'une session, au moins un client doit être connecté à la session.

La diffusion en direct peut cibler un point de terminaison HLS et jusqu’à cinq serveurs RTMP simultanément pour une même session. Vous ne pouvez lancer la diffusion en direct que pour les sessions utilisant OpenTok Media Router (avec le mode multimédia défini sur « routed ») ; vous ne pouvez pas utiliser la diffusion en direct avec les sessions dont le mode multimédia est défini sur « relayed ». (Voir Le routeur multimédia OpenTok et les modes multimédia.)

Pour plus d'informations sur la diffusion en direct avec OpenTok, consultez la Guide du développeur pour la diffusion.

Requête HTTP POST pour la diffusion

Envoyez une requête HTTP POST à l'URL suivante :

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

Remplacer <apiKey> avec votre clé API OpenTok.

Remarque : Auparavant, cette URL REST utilisait /partner (qui est désormais obsolète) au lieu de /project.

Propriétés de l'en-tête POST

Régler le Content-Type à l'en-tête application/json.

Authentifiez cet appel API à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH — défini sur un jeton Web JSON. Voir Authentification.

Données POST

Incluez un objet JSON se présentant sous la forme suivante dans le corps de la requête :

{
  "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"
}

L'objet JSON comprend les propriétés suivantes :

  • sessionId (Chaîne) — Indiquez ici l'identifiant de la session OpenTok que vous souhaitez diffuser.

  • hasAudio (Booléen) — (Facultatif) Indique si la diffusion inclura du son (true, valeur par défaut) ou non (false). Si vous définissez les deux hasAudio et hasVideo Si la valeur est « false », l'appel de cette méthode génère une erreur.

  • hasVideo (Booléen) — (Facultatif) Indique si la diffusion inclura de la vidéo (true, valeur par défaut) ou non (false). Si vous définissez les deux hasAudio et hasVideo Si la valeur est « false », l'appel de cette méthode génère une erreur.

    Remarque : lors de la configuration hasVideo Si la valeur est définie sur « false », la diffusion inclura des images noires de 160 × 120 dans les flux RTMP. Certains terminaux, comme YouTube et Facebook, rejettent les flux RTMP contenant uniquement de l'audio.

  • layout (Objet) — Facultatif. Indiquez cet objet pour définir le type de mise en page initiale de la diffusion. Cet objet comporte trois propriétés : type, stylesheetet screenshareType, qui sont toutes des chaînes de caractères. Les valeurs valides pour le layout les propriétés sont les suivantes : "bestFit" (meilleur ajustement), "custom" (sur mesure), "horizontalPresentation" (présentation horizontale), "pip" (image dans l'image) et "verticalPresentation" (présentation verticale)). Si vous spécifiez un "custom" définir le type de mise en page stylesheet de la propriété layout ajouter la feuille de style. (Pour les autres types de mise en page, ne définissez pas de stylesheet propriété.) Définissez la screenshareType propriété du type de mise en page à utiliser lorsqu'un flux de partage d'écran est présent dans la session. (Cette propriété est facultative.) Remarque : si vous définissez la screenshareType propriété, vous devez définir la type à "bestFit" et laisser la propriété stylesheet Propriété non définie. Si vous ne spécifiez pas de type de mise en page initiale, le flux de diffusion utilise le type de mise en page « Best Fit ». Pour plus d'informations, consultez Configuration de la disposition vidéo pour la fonctionnalité de diffusion en direct d'OpenTok.

  • multiBroadcastTag (Chaîne) — (Facultatif) Définissez ce paramètre pour prendre en charge plusieurs diffusions simultanées d'une même session. Attribuez une chaîne unique à chaque diffusion simultanée d'une session en cours. Voir Diffusions simultanées.

  • maxBitrate (facultatif) — Débit binaire maximal du ou des flux de diffusion, en bits par seconde. La valeur minimale est de 100 000 et la valeur maximale de 6 000 000.

  • maxDuration (Entier) — Facultatif. Durée maximale de la diffusion, en secondes. La diffusion s'arrêtera automatiquement lorsque cette durée maximale sera atteinte. Vous pouvez définir la durée maximale sur une valeur comprise entre 60 (60 secondes) et 36 000 (10 heures). La durée maximale par défaut est de 4 heures (14 400 secondes).

  • outputs (Objet) — Obligatoire. Cet objet définit les types de flux de diffusion que vous souhaitez lancer (HLS et RTMP). Vous pouvez inclure des flux HLS, RTMP ou les deux. Si vous incluez la diffusion RTMP, vous pouvez spécifier jusqu’à cinq flux RTMP cibles (ou un seul).

    Pour chaque flux RTMP, indiquez serverUrl (l'URL du serveur RTMP), streamName (le nom du flux, par exemple le nom du flux YouTube Live ou la clé du flux Facebook), et (facultatif) id (un identifiant unique pour le flux). Veillez à indiquer le port pour le serverUrl, comme dans "rtmps://myfooserver:443/myfooapp" (au lieu de "rtmps://myfooserver/myfooapp"). Si vous indiquez un identifiant, celui-ci sera inclus dans la réponse à l'appel REST et le Méthode REST permettant d'obtenir des informations sur une diffusion en direct. Vonage diffuse la session vers chaque URL RTMP que vous indiquez. Notez que la diffusion en direct OpenTok prend en charge les protocoles RTMP et RTMPS.

    Pour HLS, inclure un seul hls dans la propriété outputs objet. Cet objet comprend les propriétés facultatives suivantes :

    • dvr (Booléen) — Indique s'il faut activer Fonctionnalité DVR — le retour en arrière, la mise en pause et la reprise — sur les lecteurs qui prennent en charge ces fonctions (true), ou non (false, valeur par défaut). Lorsque la fonction DVR est activée, l'URL HLS inclura un ?DVR ajouté à la fin de la chaîne de requête.
    • lowLatency (Booléen) — Indique s'il faut activer mode à faible latence pour le flux HLS. Certains lecteurs HLS ne prennent pas en charge le mode à faible latence. Cette fonctionnalité est incompatible avec les diffusions HLS en mode DVR.

    L'URL HLS est renvoyée dans la réponse et dans la méthode REST permettant d'obtenir des informations sur une diffusion en direct.

  • resolution (Chaîne) — La résolution de la diffusion : soit "640x480" (format paysage SD, par défaut), "1280x720" (HD en mode paysage), "1920x1080" (FHD en mode paysage), "480x640" (portrait SD), "720x1280" (portrait HD), ou "1080x1920" (FHD portrait). Vous pouvez choisir d'utiliser un format portrait pour les diffusions comprenant des flux vidéo provenant d'appareils mobiles (qui utilisent souvent le format portrait). Cette propriété est facultative.

  • streamMode (Chaîne) — (Facultatif) Indique si les flux inclus dans la diffusion sont sélectionnés automatiquement ("auto", valeur par défaut) ou manuellement ("manual"). Lorsque les flux sont sélectionnés automatiquement ("auto"), tous les flux de la session peuvent être intégrés à la diffusion. Lorsque les flux sont sélectionnés manuellement ("manual"), vous indiquez les flux à inclure à l'aide d'appels à cette méthode REST. Vous pouvez préciser si la diffusion inclut l'audio, la vidéo ou les deux d'un flux. Que ce soit en mode automatique ou manuel, l'éditeur de diffusion inclut les flux en fonction de règles de hiérarchisation des cours d'eau.

Si vous ne devez prendre en charge qu'une seule URL RTMP, vous pouvez transmettre un objet (au lieu d'un tableau d'objets) pour le rtmp valeur de la propriété dans les données POST que vous fournissez lors de l'appel de la méthode REST. Par exemple, les données POST suivantes spécifient une URL de sortie RTMP (et n'incluent pas de sortie 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"
    }
  }
}

Réponse

Les données brutes de la réponse HTTP, dont le code d'état est 200, constituent un message encodé au format JSON se présentant sous la forme suivante :

{
  "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",
    }]
  }
}

L'objet JSON comprend les propriétés suivantes :

  • id — L'identifiant unique de la diffusion
  • sessionId — L'identifiant de session OpenTok
  • projectId — Votre clé API OpenTok
  • createdAt — L'heure à laquelle la diffusion a commencé, exprimée en millisecondes depuis l'époque Unix (1er janvier 1970, 00:00:00 UTC)
  • updatedAt — Pour cette méthode de démarrage, cet horodatage correspond à l'horodatage « createdAt ».
  • resolution — La résolution de la diffusion (soit « 640x480 », « 1280x720 », « 1920x1080 », « 480 × 640 », « 720 × 1 280 » ou « 1 920 × 1 080 »).
  • status - Cette valeur est fixée à "started".
  • streamMode - Si tous les flux sont inclus dans la diffusion ("auto") ou vous sélectionnez les flux à inclure dans la diffusion ("manual").
  • streams - Un tableau d'objets correspondant aux flux en cours de diffusion. Ce tableau n'est défini que pour une diffusion avec l'option status fixé à "started" et le streamMode fixé à "manual". Chaque objet du tableau comprend les propriétés suivantes :
    • streamId - L'identifiant du flux inclus dans la diffusion.
    • hasAudio - Indique si le son du flux est inclus dans la diffusion.
    • hasVideo - Si la vidéo du flux est incluse dans la diffusion.
  • maxDuration — La durée maximale de la diffusion (si elle a été définie), en secondes.
  • multiBroadcastTag - La balise unique pour les diffusions simultanées (si une balise a été définie).
  • broadcastUrls — Un objet contenant des informations détaillées sur les diffusions HLS et RTMP.

Si vous avez spécifié un point de terminaison HLS, l'objet contient un hls propriété et un hlsStatus propriété. Le hls La propriété est définie sur l'URL de la diffusion HLS. Notez que cette URL de diffusion HLS pointe vers un fichier d'index, une liste de lecture au format .M3U8 contenant une liste d'URL vers des fichiers de segments multimédias .ts (fichiers de flux de transport MPEG-2). Bien que les URL du fichier d’index de la liste de lecture et des fichiers de segments multimédias soient fournies dès que la réponse HTTP est renvoyée, il ne faut pas accéder à ces URL avant 15 à 20 secondes, après le démarrage de la diffusion HLS, en raison du délai entre la diffusion HLS et les flux en direct dans la session OpenTok. Voir https://developer.apple.com/library/ios/technotes/tn2288/_index.html Pour plus d'informations sur le fichier d'index de la liste de lecture et les fichiers de segments multimédias pour HLS. Le hlsStatus est définie sur l'une des valeurs suivantes :

  • "connecting" — Le serveur OpenTok est en train de démarrer les transcodeurs. Il s'agit de l'état initial.
  • "ready" — Le serveur OpenTok s'est initialisé avec succès, mais le CDN ne récupère pas les fichiers multimédias.
  • "live" — Le serveur OpenTok s'est initialisé avec succès et le CDN est en train de diffuser le contenu multimédia.
  • "ended" - Le flux source est terminé. Si le DVR est activé et qu'un média préenregistré est demandé, l'état passera à "live".
  • "error" — Une erreur s'est produite sur la plateforme OpenTok.

Si vous avez spécifié des points de terminaison de flux RTMP, l'objet inclut un rtmp propriété. Il s'agit d'un tableau d'objets contenant des informations sur chacun des flux RTMP. Chacun de ces objets possède les propriétés suivantes : id (l'identifiant que vous avez attribué au flux RTMP), serverUrl (l'URL du serveur), streamName (le nom du flux), et status propriété (dont la valeur est définie sur "connecting"). Vous pouvez appeler le Méthode REST d'OpenTok permettant de vérifier les mises à jour d'état de la diffusion.

La réponse HTTP comportera l'un des codes d'état suivants :

  • 200 — Réussite.
  • 400 — Demande non valide. Cette réponse peut indiquer que les données de votre requête ne sont pas au format JSON valide. Elle peut également signifier que vous avez fourni des options de mise en page non valides. Il se peut aussi que vous ayez dépassé la limite de cinq flux RTMP simultanés pour une session OpenTok. Ou encore que vous ayez spécifié une résolution non valide.
  • 403 — Erreur d'authentification.
  • 409 — La diffusion de la session a déjà commencé. Ou si vous essayez de lancer une diffusion simultanée pour une session sans avoir défini un identifiant unique multiBroadcastTag valeur.
  • 500 — Erreur du serveur OpenTok.

Exemple

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

Interrompre une diffusion en direct

Utilisez cette méthode pour interrompre la diffusion en direct d'une session OpenTok.

Notez qu'une diffusion s'arrête automatiquement 60 secondes après la déconnexion du dernier client de la session. Il existe également une durée maximale par défaut de 4 heures (14 400 secondes) pour chaque flux HLS et RTMP (la diffusion en direct s'arrête automatiquement lorsque cette durée est atteinte). Vous pouvez modifier la durée maximale de la diffusion en configurant le paramètre maxDuration propriété lorsque vous démarrer l'émission Méthode REST.

Requête HTTP POST vers broadcast//stop

Envoyez une requête HTTP POST à l'URL suivante :

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

Remplacer <apiKey> avec votre clé API OpenTok. Remplacez <broadcastId> en indiquant l'identifiant de la diffusion que vous souhaitez arrêter. Vous obtenez cet identifiant lorsque vous lancez une diffusion.

Propriétés de l'en-tête POST

Authentifiez cet appel API à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH — défini sur un jeton Web JSON. Voir Authentification.

Remarque : Auparavant, cette URL REST utilisait /partner (qui est désormais obsolète) au lieu de /project.

Réponse

Les données brutes de la réponse HTTP, dont le code d'état est 200, constituent un message encodé au format JSON se présentant sous la forme suivante :

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

L'objet JSON comprend les propriétés suivantes :

  • id — L'identifiant unique de la diffusion
  • sessionId — L'identifiant de la session OpenTok en cours de diffusion
  • projectId — Votre clé API OpenTok
  • createdAt — L'heure à laquelle la diffusion a commencé, exprimée en secondes depuis l'époque Unix (1er janvier 1970, 00:00:00 UTC)
  • updatedAt — L'instant où la diffusion a été interrompue, exprimé en secondes depuis l'époque Unix (1er janvier 1970, 00:00:00 UTC)
  • resolution - La résolution de la diffusion (soit "640x480", "1280x720", "1920x1080", "480x640", "720x1280" ou "1080x1920").
  • status - Cette valeur est fixée à "stopped".
  • streamMode - Si tous les flux sont inclus dans la diffusion ("auto") ou vous sélectionnez les flux à inclure dans la diffusion ("manual").
  • streams — Un tableau d'objets correspondant aux flux en cours de diffusion. Ce tableau est vide pour la méthode `stop`.
  • maxDuration — La durée maximale de la diffusion (si elle a été définie), en secondes.
  • multiBroadcastTag - La balise unique pour les diffusions simultanées (si une balise a été définie).
  • broadcastUrls — Cette valeur est définie sur null pour la méthode stop.

La réponse HTTP comportera l'un des codes d'état suivants :

  • 200 — Réussite.
  • 400 — Demande non valide. Cette réponse peut indiquer que les données contenues dans votre requête ne sont pas au format JSON valide.
  • 403 — Erreur d'authentification.
  • 404 — La diffusion (dont l'identifiant est indiqué) est introuvable ou a déjà pris fin.
  • 500 — Erreur du serveur OpenTok.

Exemple

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

Liste des diffusions en direct

Utilisez cette méthode pour obtenir des informations sur les diffusions en cours et celles qui ont déjà commencé. Les diffusions terminées ne figurent pas dans la liste.

Requête HTTP GET pour la diffusion

Envoyez une requête HTTP GET à l'URL suivante :

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

Remplacer <apiKey> avec votre clé API OpenTok.

Les paramètres de requête suivants sont acceptés :

  • offset (facultatif) — Le décalage de départ dans la liste des diffusions existantes
  • count (facultatif, valeur par défaut : 50, maximum : 1 000) — Nombre de diffusions à récupérer à partir de l'offset
  • sessionId (facultatif) : récupérer uniquement les diffusions correspondant à un identifiant de session donné

Propriétés de l'en-tête GET

Authentifiez cet appel API à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH — définir sur un jeton Web JSON. Voir Authentification.

Réponse

Les données brutes de la réponse HTTP, dont le code d'état est 200, constituent un message encodé au format JSON se présentant sous la forme suivante :

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

L'objet JSON comprend les propriétés suivantes :

  • count — Le nombre total de diffusions figurant dans les résultats.
  • items — Un tableau d'objets définissant chaque diffusion récupérée. Les diffusions sont classées par ordre chronologique décroissant (de la plus récente à la plus ancienne) dans le jeu de résultats.

Chaque objet de diffusion (élément) possède les propriétés suivantes :

  • id — L'identifiant unique de la diffusion

  • sessionId — L'identifiant de session OpenTok

  • projectId — Votre clé API OpenTok

  • createdAt — L'heure à laquelle la diffusion a commencé, exprimée en millisecondes depuis l'époque Unix (1er janvier 1970, 00:00:00 UTC)

  • updatedAt — Pour cette méthode GET, cet horodatage correspond à l'horodatage « createdAt ».

  • resolution — La résolution de la diffusion (soit « 640x480 », « 1280x720 », « 1920x1080 », « 480x640 », « 720x1280 » ou « 1080x1920 »).

  • status — Le statut de la diffusion. Cette méthode ne renvoie que les diffusions dont le statut est défini sur "started".

  • maxDuration — La durée maximale de la diffusion (si elle a été définie), en secondes.

  • multiBroadcastTag - La balise unique pour les diffusions simultanées (si une balise a été définie).

  • broadcastUrls - Détails sur les flux de diffusion HLS et RTMP.

    Pour un flux HLS, l'URL est fournie sous la forme de l'élément hls propriété. Voir le Guide du développeur pour la diffusion en direct avec OpenTok Pour plus d'informations sur l'utilisation de cette URL. Le hlsStatus est définie sur l'une des valeurs suivantes :

    • "connecting" — Le serveur OpenTok est en train de démarrer les transcodeurs. Il s'agit de l'état initial.
    • "ready" — Le serveur OpenTok s'est initialisé avec succès, mais le CDN ne consomme pas de contenu multimédia.
    • "live" — Le serveur OpenTok s'est initialisé avec succès et le CDN est en train de diffuser le contenu multimédia.
    • "ended" — Le flux source est terminé. Si la fonction DVR est activée et qu’ un contenu préenregistré est demandé, l’état passera alors à live".
    • "error" — Une erreur s'est produite sur la plateforme OpenTok.

    Pour chaque flux RTMP, l'URL du serveur RTMP et le nom du flux sont indiqués, ainsi que l'état du flux RTMP. Le status est définie sur l'une des valeurs suivantes :

    • connecting — La plateforme OpenTok est en train de se connecter au serveur RTMP distant. Il s'agit de l'état initial ; c'est l'état dans lequel elle se trouve lorsque vous démarrez la session alors qu' aucun flux n'est publié. Il passe à « live » dès qu'il y a des flux (ou passe à l'un des autres états).
    • live — La plateforme OpenTok s'est connectée avec succès au serveur RTMP distant, et le flux multimédia est en cours de diffusion.
    • offline — La plateforme OpenTok n'a pas pu se connecter au serveur RTMP distant. Cela est dû à un serveur inaccessible ou à une erreur lors de la négociation RTMP. Les causes peuvent être notamment des connexions RTMP rejetées, des Applications RTMP inexistantes, des noms de flux rejetés, des erreurs d’authentification, etc. Vérifiez que le serveur est en ligne et que vous avez fourni l’ URL du serveur et le nom du flux corrects.
    • error — Une erreur s'est produite sur la plateforme OpenTok.

  • settings - Plus de détails sur le flux de diffusion HLS. Ce flux settings objet comprend un hls avec les propriétés suivantes :

  • streamMode - Si tous les flux sont inclus dans la diffusion ("auto") ou bien vous sélectionnez les flux à inclure dans la diffusion ("manual"). Voir aussi Sélection des flux à inclure dans une diffusion en direct.

  • streams — Pour une émission avec "manual" streamMode et un status fixé à "started", il s'agit d'un tableau d'objets correspondant aux flux actuellement diffusés. Chaque objet du tableau comporte les propriétés suivantes :

    • streamId - L'identifiant du flux inclus dans la diffusion.
    • hasAudio - Indique si le son du flux est inclus dans la diffusion.
    • hasVideo - Si la vidéo du flux est incluse dans la diffusion.

La réponse HTTP comportera l'un des codes d'état suivants :

  • 200 — Réussite
  • 403 — Erreur d'authentification
  • 500 — Erreur du serveur OpenTok

Exemples

Liste de toutes les diffusions (jusqu'à 50) :

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

Liste d'une série d'émissions :

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

Afficher les diffusions associées à un identifiant de session donné :

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

Obtenir des informations sur une diffusion en direct

Utilisez cette méthode pour obtenir des informations détaillées sur une diffusion en cours.

Requête HTTP GET pour la diffusion

Envoyez une requête HTTP GET à l'URL suivante :

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

Remplacer <apiKey> avec votre clé API OpenTok. Remplacez <broadcastId> avec l'identifiant de la diffusion. Vous obtenez cet identifiant lorsque vous lancez une diffusion.

Remarque : Auparavant, cette URL REST utilisait /partner (qui est désormais obsolète) au lieu de /project.

Propriétés de l'en-tête GET

Authentifiez cet appel API à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH — défini sur un jeton Web JSON. Voir Authentification.

Réponse

Les données brutes de la réponse HTTP, dont le code d'état est 200, constituent un message encodé au format JSON se présentant sous la forme suivante :

{
  "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"
}

L'objet JSON comprend les propriétés suivantes :

  • id — L'identifiant unique de la diffusion

  • sessionId — L'identifiant de session OpenTok

  • projectId — Votre clé API OpenTok

  • createdAt — L'heure à laquelle la diffusion a commencé, exprimée en millisecondes depuis l'époque Unix (1er janvier 1970, 00:00:00 UTC)

  • updatedAt - Pour cette méthode GET, cet horodatage correspond à l'horodatage de createdAt.

  • resolution - La résolution de la diffusion (soit "640x480", "1280x720", "1920x1080", "480x640", "720x1280" ou "1080x1920").

  • status — Le statut de la diffusion : soit "started" ou "stopped".

  • broadcastUrls - Détails sur les flux de diffusion HLS et RTMP.

    Pour un flux HLS, l'URL est fournie sous la forme de l'élément hls les biens. Voir le Guide du développeur pour la diffusion en direct avec OpenTok pour plus d'informations sur l'utilisation de cette URL. L'adresse hlsStatus est définie sur l'une des valeurs suivantes :

  • "connecting" — Le serveur OpenTok est en train de démarrer les transcodeurs. Il s'agit de l'état initial.
  • "ready" — Le serveur OpenTok s'est initialisé avec succès, mais le CDN ne traite pas les flux multimédias.
  • "live" — Le serveur OpenTok s'est initialisé avec succès et le CDN est en train de diffuser le contenu multimédia.
  • "ended" - Le flux source est terminé. Si le DVR est activé et qu'un média préenregistré est demandé, l'état passera à "live".
  • "error" — Une erreur s'est produite sur la plateforme OpenTok.

Pour chaque flux RTMP, l'URL du serveur RTMP et le nom du flux sont fournis, ainsi que l'état du flux RTMP.

  • status — L'état du flux RTMP. Effectuez des requêtes fréquentes pour vérifier les mises à jour d'état. Cette propriété peut prendre l'une des valeurs suivantes :

    • connecting — La plateforme OpenTok est en train de se connecter au serveur RTMP distant. Il s'agit de l'état initial ; c'est l'état qui s'affiche lorsque vous démarrez la session alors qu'aucun flux n'est publié. Il passe à « live » dès qu'il y a des flux (ou passe à l'un des autres états).
    • live — La plateforme OpenTok s'est connectée avec succès au serveur RTMP distant, et le flux multimédia est en cours de diffusion.
    • offline — La plateforme OpenTok n'a pas pu se connecter au serveur RTMP distant. Cela est dû à un serveur inaccessible ou à une erreur lors de la négociation RTMP. Les causes peuvent être notamment des connexions RTMP refusées, des Applications RTMP inexistantes, des noms de flux refusés, des erreurs d'authentification, etc. Vérifiez que le serveur est en ligne et que vous avez indiqué l'URL du serveur et le nom du flux corrects.
    • error — Une erreur s'est produite sur la plateforme OpenTok.

  • settings - Plus de détails sur le flux de diffusion HLS. Ce flux properties comprend un objet hls avec les propriétés suivantes :

  • multiBroadcastTag - La balise unique pour les diffusions simultanées (si une balise a été définie).

  • streamMode - Si tous les flux sont inclus dans la diffusion ("auto") ou vous sélectionnez les flux à inclure dans la diffusion ("manual"). Voir aussi Sélection des flux à inclure dans une diffusion en direct.

  • streams - Un tableau d'objets correspondant aux flux en cours de diffusion. Ce tableau n'est défini que pour une diffusion avec l'option status fixé à "started" et le streamMode fixé à "manual". Chaque objet du tableau comprend les propriétés suivantes :

    • streamId - L'identifiant du flux inclus dans la diffusion.
    • hasAudio - Indique si le son du flux est inclus dans la diffusion.
    • hasVideo - Si la vidéo du flux est incluse dans la diffusion.

La réponse HTTP comportera l'un des codes d'état suivants :

  • 200 — Réussite
  • 400 — Demande non valide
  • 403 — Erreur d'authentification
  • 404 — Aucune diffusion correspondante trouvée (avec l'ID spécifié)
  • 500 — Erreur du serveur OpenTok

Exemple

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

Changement dynamique du type de mise en page lors d'une diffusion en direct

Vous pouvez modifier dynamiquement le type de mise en page d'une diffusion en direct.

Pour plus d'informations sur les diffusions en direct avec OpenTok, consultez la Guide du développeur pour la diffusion.

Requête HTTP PUT pour la diffusion

Envoyez une requête HTTP PUT à l'URL suivante :

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

Remplacer <apiKey> avec votre clé API OpenTok.

Remplacer <broadcastId> avec l'identifiant de diffusion.

Propriétés de l'en-tête PUT

Régler le Content-Type à l'en-tête application/json.

Authentifiez cet appel API à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH — défini sur un jeton Web JSON. Voir Authentification.

Données PUT

Incluez un objet JSON se présentant sous la forme suivante dans le corps de la requête :

{
  "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)"
}

L'objet JSON comprend les propriétés suivantes :

  • type (Chaîne) — Type de mise en page de la diffusion. Les valeurs valides sont : "bestFit" (meilleur ajustement), "custom" (sur mesure), "horizontalPresentation" (présentation horizontale), "pip" (image dans l'image) et "verticalPresentation" (présentation verticale)). Si vous spécifiez un "custom" définir le type de mise en page stylesheet propriété à la feuille de style. (Pour les autres types de mise en page, ne définissez pas la stylesheet propriété.) Pour plus d'informations, consultez Configuration de la disposition vidéo pour la fonctionnalité de diffusion en direct d'OpenTok.
  • feuille de style (Chaîne) — Facultatif. Ne le spécifiez que si vous définissez le type à la propriété "custom". Régler le stylesheet propriété à la feuille de style. (Pour les autres types de mise en page, ne définissez pas la stylesheet propriété.) Pour plus d'informations, consultez Définir des mises en page personnalisées.
  • type de partage d'écran (Chaîne) — Facultatif. Type de mise en page à utiliser lorsqu'un flux de partage d'écran est présent dans la session. Notez que pour utiliser cette propriété, vous devez définir la type à "bestFit" et laisser la propriété stylesheet n'est pas définie. Pour plus d'informations, voir Types de mise en page pour le partage d'écran.

Lorsque vous spécifiez un type de mise en page autre que « Best Fit », veillez à appliquer les classes de mise en page appropriées aux flux de la session OpenTok (voir Attribution de classes de mise en page de diffusion en direct aux flux OpenTok.

Réponse

La réponse HTTP comportera l'un des codes d'état suivants :

  • 200 — Réussite.
  • 400 — Demande non valide. Cette réponse peut indiquer que les données de votre requête ne sont pas au format JSON valide. Elle peut également indiquer que vous avez fourni des options de mise en page non valides.
  • 403 — Erreur d'authentification.
  • 500 — Erreur du serveur OpenTok.

Exemple

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

Modification des classes de mise en page de la diffusion en direct pour un flux OpenTok

Utilisez cette méthode pour modifier les classes de mise en page d'un flux OpenTok. Les classes de mise en page définissent la manière dont le flux s'affiche dans la mise en page du flux de diffusion. Pour plus d'informations, consultez Attribution de classes de mise en page de diffusion en direct aux flux OpenTok.

Requête HTTP PUT vers le flux

Envoyez une requête HTTP PUT à l'URL suivante :

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

Remplacer <apiKey> avec votre clé API OpenTok.

Remplacer <sessionId> avec l'identifiant de session.

Propriétés de l'en-tête PUT

Régler le Content-Type à l'en-tête application/json.

Authentifiez cet appel API à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH — défini sur un jeton Web JSON. Voir Authentification.

Données PUT

Incluez un objet JSON se présentant sous la forme suivante dans le corps de la requête :

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

L'objet JSON contient un items tableau d'objets. Chaque objet définit les classes de mise en page à attribuer à un flux et contient les propriétés suivantes :

  • id (Chaîne) — L'identifiant du flux.
  • layoutClassList (Tableau) — Tableau de classes de mise en page (chacune sous forme de chaîne de caractères) pour le flux.

Vous pouvez mettre à jour la liste des classes de mise en page pour plusieurs flux en transmettant plusieurs objets JSON dans le items de la gamme.

Réponse

La réponse HTTP comportera l'un des codes d'état suivants :

  • 200 — Réussite.
  • 400 — Demande non valide. Cette réponse peut indiquer que les données de votre requête ne sont pas au format JSON valide. Elle peut également indiquer que vous avez fourni des options de mise en page non valides.
  • 403 — Erreur d'authentification.
  • 500 — Erreur du serveur OpenTok.

Exemple

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

Sélection des flux à inclure dans une diffusion en direct

Utilisez cette méthode pour modifier les flux inclus dans une diffusion en direct qui a été lancée avec la commande streamMode fixé à "manual" (voir Lancer une diffusion en direct).

Le compositeur de diffusion inclut les flux ajoutés en fonction de règles de hiérarchisation des cours d'eau.

Requête HTTP PATCH vers broadcast/streams

Envoyez une requête HTTP PATCH à l'URL suivante :

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

Remplacer <apiKey> avec votre clé API OpenTok. Remplacez <broadcastId> avec l'identifiant de diffusion.

Propriétés de l'en-tête PATCH

Régler le Content-Type à l'en-tête application/json.

Authentifiez cet appel API à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH — définir sur un jeton Web JSON. Voir Authentification.

Données PATCH

Pour ajouter un flux à la diffusion, incluez un objet JSON se présentant sous la forme suivante dans le corps de la requête :

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

L'objet JSON contient les propriétés suivantes :

  • addStream (Chaîne) — L'identifiant du flux.
  • hasAudio (Booléen, facultatif) — Indique si la diffusion doit inclure l'audio du flux (true, valeur par défaut) ou non (false).
  • hasVideo (Booléen, facultatif) — Indique si la diffusion doit inclure la vidéo du flux (true, valeur par défaut) ou non (false).

Vous pouvez appeler cette méthode à plusieurs reprises à l'aide de addStream réglé sur le même identifiant de flux, pour activer ou désactiver le son ou la vidéo du flux lors de la diffusion.

Si vous configurez les deux hasAudio et hasVideo à false, vous obtiendrez une réponse d'erreur.

Pour empêcher un flux d'être inclus dans la diffusion, incluez un objet JSON se présentant sous la forme suivante dans le corps de la requête :

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

Régler le removeStream propriété associée à l'identifiant du flux.

Réponse

La réponse HTTP comportera l'un des codes d'état suivants :

  • 204 — Réussite (pas de contenu).
  • 400 — Demande non valide. Cette réponse peut indiquer que les données fournies dans votre demande sont au format JSON non valide, ou que la demande n'a pas pu être traitée car la diffusion a été lancée avec streamMode fixé à "auto", qui ne prend pas en charge la manipulation des flux.
  • 403 — Erreur d'authentification.
  • 404 — Émission ou flux introuvable.
  • 500 — Erreur du serveur OpenTok.

Exemples

Ajouter un flux à une diffusion :

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

Supprimer la vidéo d'un flux pendant une diffusion (tout en conservant le son) :

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

Supprimer un flux d'une diffusion :

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

Lancer les sous-titres en direct

Utilisez cette méthode pour activer les sous-titres en temps réel (« Live Captions ») lors d'une session OpenTok.

La durée maximale autorisée est de 4 heures, après quoi le sous-titrage audio s'arrêtera sans que cela n'ait d'incidence sur la session OpenTok en cours. Les sessions de sous-titrage prendront également fin 60 secondes après la déconnexion du dernier client. Un événement sera envoyé à votre URL de rappel si celle-ci a été fournie lors du lancement du sous-titrage.

Chaque session OpenTok ne prend en charge qu'une seule session de sous-titrage audio.

Pour plus d'informations sur la fonctionnalité « Sous-titres en direct », consultez la Guide du développeur Live Captions.

Requête HTTP POST pour lancer les sous-titres en direct

Envoyez une requête HTTP POST à l'URL suivante :

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

Remplacer <apiKey> avec votre clé API OpenTok.

Régler le Content-Type à l'en-tête application/json.

Authentifiez cet appel API à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH — défini sur un jeton Web JSON. Voir Authentification.

Données POST

Incluez un objet JSON se présentant sous la forme suivante dans le corps de la requête :

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

L'objet JSON comprend les propriétés suivantes :

  • sessionId (Chaîne de caractères) — L'identifiant de la session OpenTok. Le flux audio provenant des diffuseurs participant à cette session sera utilisé pour générer les sous-titres.
  • token(Chaîne de caractères) — Un jeton OpenTok valide dont le rôle est défini sur « Modérateur ».
  • languageCode (Chaîne) — (Facultatif) Le code BCP-47 correspondant à la langue utilisée par Live Captions (voir cette liste des langues prises en charge). La valeur par défaut est « en-US ».
  • maxDuration (Entier) — (Facultatif) Durée maximale du sous-titrage audio, en secondes. La valeur par défaut est de 14 400 secondes (4 heures), ce qui correspond à la durée maximale autorisée. La valeur minimale pour maxDuration est de 300 (300 secondes, soit 5 minutes).
  • partialCaptions (Booléen) — (Facultatif) Indique s'il faut activer cette option pour accélérer la création des sous-titres, au prix d'un certain degré d'imprécision. La valeur par défaut est true.

Réponse

En cas de réussite, les données brutes de la réponse HTTP, avec le code d'état 200, se présentent sous la forme d'un message encodé en JSON, comme suit :

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

L'objet JSON comprend la propriété suivante :

  • captionsId — L'identifiant unique de la session de sous-titrage audio.

La réponse HTTP comportera l'un des codes d'état suivants :

  • 202 — Accepté.
  • 400 — Demande incorrecte ; la réponse peut signaler une erreur liée aux données de la demande, qui ne sont pas acceptables.
  • 403 — Erreur d'authentification. L'identifiant fourni X-OPENTOK-AUTH peut ne pas être valide.
  • 409 — Le sous-titrage en direct a déjà commencé pour cette session OpenTok.
  • 500 — Erreur de la plateforme Video API Vonage.

Exemple


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

Désactiver les sous-titres en direct

Utilisez cette méthode pour désactiver le sous-titrage en direct d'une session.

Requête HTTP POST pour désactiver les sous-titres en direct

Envoyez une requête HTTP POST à l'URL suivante :

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

Remplacer <apiKey> avec votre clé API OpenTok. Remplacez <captionsId> avec l'identifiant renvoyé dans la réponse de l'API « Start Captions ».

Authentifiez cet appel API à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH — défini sur un jeton Web JSON. Voir Authentification.

La réponse HTTP comportera l'un des codes d'état suivants :

  • 202 — Accepté
  • 403 — Erreur d'authentification
  • 404 — Aucun « captionsId » correspondant n'a été trouvé
  • 500 — Erreur de la plateforme Video API Vonage

Exemple

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;

Lancer Experience Composer

Utilisez cette méthode pour créer un Experience Composer pour une session OpenTok. Pour plus d'informations, consultez la Guide du développeur Experience Composer.

Requête HTTP POST pour l'affichage

Envoyez une requête HTTP POST à l'URL suivante :

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

Remplacer <apiKey> avec votre clé API OpenTok.

Propriétés de l'en-tête POST

Régler le Content-Type à l'en-tête application/json.

Authentifiez cet appel API à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH — définir sur un jeton Web JSON. Voir Authentification.

Données POST

Incluez un objet JSON se présentant sous la forme suivante dans le corps de la requête :

{
  "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"
  }
}

L'objet JSON comprend les propriétés suivantes :

  • sessionId (chaîne de caractères) — L'identifiant de la session OpenTok qui inclura le flux d'Experience Composer.
  • token (chaîne de caractères) — Un jeton OpenTok valide doté du rôle « Publisher » et (facultativement) des données de connexion à associer au flux de sortie.
  • url (chaîne de caractères) — Une URL accessible au public, gérée par le client et capable de générer le contenu à afficher sans intervention de l'utilisateur. La longueur minimale de l'URL est de 15 caractères et sa longueur maximale est de 2 048 caractères.
  • maxDuration (entier) — (Facultatif) Durée maximale autorisée pour l’Experience Composer, en secondes. Passé ce délai, il est automatiquement arrêté s’il est toujours en cours d’exécution. La valeur maximale est 36 000 (10 heures), la valeur minimale est 60 (1 minute) et la valeur par défaut est 7 200 (2 heures). Lorsque l’Experience Composer s’arrête, son flux est dépublié et un événement est envoyé à l’URL de rappel, si celle-ci a été configurée dans le portail de l’Account.
  • résolution (chaîne de caractères) — (Facultatif) Résolution de l'Experience Composer : soit « 640x480 » (SD paysage), « 480x640 » (SD portrait), « 1280x720 » (HD paysage), « 720x1280 » (HD portrait), « 1920x1080 » (FHD paysage) ou « 1080x1920 » (FHD portrait). Par défaut, cette résolution est « 1280x720 » (HD paysage, valeur par défaut).
  • propriétés (Objet) — (Facultatif) Configuration initiale des propriétés du Publisher pour le flux de sortie composé. L'objet « propriétés » contient le nom de la clé (chaîne de caractères) qui sert de nom au flux de sortie composé publié vers la session. Le nom doit comporter au minimum 1 caractère et au maximum 200 caractères.

Réponse

Les données brutes de la réponse HTTP, dont le code d'état est 200, constituent un message encodé au format JSON se présentant sous la forme suivante :

{
  "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" 
}

L'objet JSON comprend les propriétés suivantes :

  • id — L'identifiant unique de l'Experience Composer.
  • sessionId — L'identifiant de session OpenTok.
  • projectId — Votre clé API OpenTok.
  • createdAt — Heure de démarrage de l'Experience Composer, exprimée en millisecondes depuis l'époque Unix (1er janvier 1970, 00:00:00 UTC).
  • updatedAt — Il s'agit de l'horodatage UNIX correspondant à la dernière mise à jour du statut d'Experience Composer. Pour cette méthode « start », cet horodatage correspond à l'horodatage « createdAt ».
  • callbackUrl — L'URL de rappel pour les événements d'Experience Composer (si elle a été définie). Voir Configuration des rappels.
  • nom — Le nom de l'Experience Composer (si celui-ci a été spécifié).
  • url — Une URL accessible au public, gérée par le client et capable de générer le contenu à afficher sans intervention de l'utilisateur.
  • résolution — La résolution de l'Experience Composer (soit « 640x480 », « 480x640 », « 1280x720 », « 720x1280 », « 1920x1080 » ou « 1080x1920 »).
  • statut — Pour cette méthode de démarrage, il est défini sur « en cours de démarrage ».
  • streamId — L'identifiant du flux composé en cours de publication.

La réponse HTTP comportera l'un des codes d'état suivants :

  • 202 — Réussite.

  • 400 — Demande non valide. Cette réponse peut indiquer que les données contenues dans votre requête sont au format JSON non valide. Elle peut inclure un code d'erreur ; certains d'entre eux sont répertoriés ci-dessous :

    • 50001 — Structure d'URL de l'application non valide.
    • 50002 — L'URL de l'application est inaccessible.
    • 50005 — Valeur « maxDuration » non valide.
    • 50006 — Résolution non valide fournie.
    • 50007 — Nom de flux non valide.
    • 50008 — Identifiant de session (sessionId) non valide.

  • 403 — Erreur d'authentification. Ce code peut être accompagné d'un code d'erreur ; certains d'entre eux sont répertoriés ci-dessous :

    • 10001 - Format ou signature du jeton non valide.
    • 10002 - Jeton non autorisé.
    • 10003 - Format d'authentification du partenaire non valide.
    • 10004 - Authentification non autorisée d'un partenaire.
    • 10007 - Le jeton ne correspond pas à l'identifiant de session.
    • 10012 - Jeton périmé.

  • 429 — Nombre de requêtes trop élevé. Vous avez dépassé la limite d'utilisation d'Experienced Composer. La réponse comportera un code d'erreur 50004.

  • 500 — Erreur de la plateforme Video API Vonage.

Exemple

  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

Obtenir des informations sur un « Experience Composer »

Utilisez cette méthode pour obtenir des informations détaillées sur un Experience Composer.

Requête HTTP GET pour l'affichage

Envoyez une requête HTTP GET à l'URL suivante :

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

Remplacer <apiKey> avec votre clé API OpenTok. Remplacez <experienceComposerId> avec l'identifiant de l'Experience Composer. Vous obtenez cet identifiant lorsque vous lancez un Experience Composer.

Propriétés de l'en-tête GET

Authentifiez cet appel API à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH — contenant un jeton Web JSON. Voir Authentification.

Réponse

Les données brutes de la réponse HTTP, dont le code d'état est 200, constituent un message encodé au format JSON se présentant sous la forme suivante :

{
  "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"
}

L'objet JSON comprend les propriétés suivantes :

  • id — L'identifiant unique de l'Experience Composer.
  • sessionId — L'identifiant de session OpenTok.
  • projectId — Votre clé API OpenTok.
  • createdAt — Heure de démarrage de l'Experience Composer, exprimée en millisecondes depuis l'époque Unix (1er janvier 1970, 00:00:00 UTC).
  • updatedAt — Pour cette méthode GET, cet horodatage correspond à l'horodatage createdAt.
  • callbackUrl — L'URL de rappel pour les événements de l'URL Experience Composer (si elle a été définie). Voir Configuration des rappels.
  • nom — Le nom de l'Experience Composer (si celui-ci a été spécifié).
  • url — Une URL accessible au public, gérée par le client et capable de générer le contenu à afficher sans intervention de l'utilisateur.
  • résolution — La résolution de l'Experience Composer (soit « 640x480 », « 1280x720 », « 480x640 » ou « 720x1280 »).
  • statut — Statut de l'Experience Composer. Effectuez des requêtes fréquentes pour vérifier les mises à jour de statut. Cette propriété peut prendre l'une des valeurs suivantes :
    • « Démarrage » — La plateforme Video API Vonage est en train de se connecter à l'application distante à l' URL indiquée. Il s'agit de l'état initial.
    • « démarré » — La plateforme Video API Vonage s'est connectée avec succès au serveur d'applications distant, et publie la vue Web sur un flux OpenTok.
    • « arrêté » — L'Experience Composer s'est arrêté.
    • « Échec » — Une erreur s'est produite et Experience Composer n'a pas pu poursuivre l'opération. Cela peut se produire au démarrage si le serveur OpenTok ne parvient pas à se connecter au serveur d'applications distant ou à republier le flux. Cela peut également se produire à tout moment au cours du processus en raison d'une erreur au niveau de la plateforme Video API Vonage.
  • motif — Le champ « Motif » n'est disponible que lorsque le statut est « arrêté » ou « échec ». Si le statut est « arrêté », le champ « Motif » indiquera soit « Durée maximale dépassée », soit « Arrêt demandé ». Si le statut est « échec », le motif contiendra un message d'erreur plus précis.
  • streamId — Identifiant du flux composé en cours de publication. Le streamId n'est pas disponible lorsque le statut est « starting » et peut ne pas être disponible lorsque le statut est « failed ».

La réponse HTTP comportera l'un des codes d'état suivants :

  • 200 — Réussite
  • 400 — Demande non valide
  • 403 — Erreur d'authentification
  • 404 — Aucun compositeur « Experience » correspondant à l'ID spécifié n'a été trouvé.
  • 500 — Erreur de la plateforme Video API Vonage.

Exemple

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;

Obtenir la liste des compositeurs expérimentés

Utilisez cette méthode pour obtenir la liste des « Experience Composers » associés à un projet.

Requête HTTP GET pour l'affichage

Envoyez une requête HTTP GET à l'URL suivante :

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

Remplacer <apiKey> avec votre clé API OpenTok. Les paramètres de requête facultatifs suivants peuvent être ajoutés :

  • décalage — Décalage de départ pour la liste des compositeurs d'Experience. La valeur par défaut est 0.
  • count — Nombre de « Experience Composers » à récupérer à partir du décalage indiqué. La valeur par défaut est 50 et la valeur maximale est 1 000.

Propriétés de l'en-tête GET

Authentifiez cet appel API à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH — contenant un jeton Web JSON. Voir Authentification.

Réponse

Les données brutes de la réponse HTTP, dont le code d'état est 200, constituent un message encodé au format JSON se présentant sous la forme suivante :

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

L'objet JSON comprend les propriétés suivantes :

  • nombre — Nombre total de « Experience Composers ».
  • éléments — Le tableau contenant les « Experience Composers » récupérés. Chaque élément « Experience Composer » comprend les propriétés suivantes :
    • id — L'identifiant unique de l'Experience Composer.
    • sessionId — L'identifiant de session OpenTok.
    • projectId — Votre clé API OpenTok.
    • createdAt — Heure de démarrage de l'Experience Composer, exprimée en millisecondes depuis l'époque Unix (1er janvier 1970, 00:00:00 UTC).
    • updatedAt — Pour cette méthode GET, cet horodatage correspond à l'horodatage createdAt.
    • callbackUrl — L'URL de rappel pour les événements d'Experience Composer (si elle a été définie). Voir Configuration des rappels.
    • nom — Le nom de l'Experience Composer (si celui-ci a été spécifié).
    • url — Une URL accessible au public, gérée par le client et capable de générer le contenu à afficher sans intervention de l'utilisateur.
    • résolution — La résolution de l'Experience Composer (soit « 640x480 », « 1280x720 », « 480x640 » ou « 720x1280 »).
    • statut — Statut de l'Experience Composer. Effectuez des requêtes fréquentes pour vérifier les mises à jour de statut. Cette propriété peut prendre l'une des valeurs suivantes :
      • « Démarrage » — La plateforme Video API Vonage est en train de se connecter à l'application distante à l' URL indiquée. Il s'agit de l'état initial.
      • « démarré » — La plateforme Video API Vonage s'est connectée avec succès au serveur d'applications distant et publie la vue Web sur un flux OpenTok.
      • « arrêté » — L'Experience Composer s'est arrêté.
      • « Échec » — Une erreur s'est produite et Experience Composer n'a pas pu poursuivre l'opération. Cela peut se produire au démarrage si le serveur OpenTok ne parvient pas à se connecter au serveur d'applications distant ou à republier le flux. Cela peut également se produire à tout moment au cours du processus en raison d'une erreur de la plateforme Video API Vonage.
    • motif — Le champ « motif » n'est disponible que lorsque le statut est « arrêté » ou « échec ». Si le statut est « arrêté », le champ « motif » indiquera soit « Durée maximale dépassée », soit « Arrêt demandé ». Si le statut est « échoué », le champ « raison » contiendra un message d'erreur plus précis.
    • streamId — Identifiant du flux composé en cours de publication. Le streamId n'est pas disponible lorsque le statut est « starting » et peut ne pas être disponible lorsque le statut est « failed ».

La réponse HTTP comportera l'un des codes d'état suivants :

  • 200 — Réussite
  • 403 — Erreur d'authentification
  • 500 — Erreur de la plateforme Video API Vonage.

Exemple

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

Arrêter un Experience Composer

Utilisez cette méthode pour arrêter un Experience Composer d'une session OpenTok. Notez que, par défaut, les Experience Composers s'arrêtent automatiquement 2 heures après leur lancement. Vous pouvez également définir une valeur « maxDuration » différente lors de la création de l'Experience Composer. Lorsque l'Experience Composer prend fin, un événement est envoyé à l'URL de rappel, si vous avez en a configuré un pour le projet.

Requête HTTP DELETE pour afficher

Envoyez une requête HTTP DELETE à l'URL suivante :

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

Remplacer <apiKey> avec votre clé API OpenTok. Remplacez <experienceComposerId> en indiquant l'ID de l'Experience Composer que vous souhaitez arrêter. Vous pouvez obtenir l' ID de l'Experience Composer à partir de la réponse reçue lors du démarrage d'un Experience Composer.

Propriétés de l'en-tête DELETE

Authentifiez cet appel API à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH — contenant un jeton Web JSON. Voir Authentification.

Réponse

La réponse HTTP comportera l'un des codes d'état suivants :

  • 204 — Aucun contenu.
  • 400 — Demande non valide.
  • 403 — Erreur d'authentification.
  • 404 — Le « Experience Composer » (dont l'ID est indiqué) est introuvable ou s'est déjà arrêté.
  • 500 — Erreur de la plateforme Video API Vonage.

Exemple

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;/

Établissement d'une connexion WebSocket via Audio Connector

Utilisez cette méthode pour envoyer le flux audio d'une session de la Video API Vonage vers un WebSocket.

Pour plus d'informations, notamment sur les données WebSocket, consultez le Guide du développeur Audio Connector.

Requête HTTP POST pour se connecter

Envoyez une requête HTTP POST à l'URL suivante :

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

Remplacer <apiKey> avec votre clé API OpenTok.

Propriétés de l'en-tête POST

Régler le Content-Type à l'en-tête application/json.

Authentifiez cet appel API à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH — définir sur un jeton Web JSON. Voir Authentification.

Données POST

Incluez un objet JSON se présentant sous la forme suivante dans le corps de la requête :

{
  "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"
    }
  }
}

L'objet JSON comprend les propriétés suivantes :

  • sessionId​ (obligatoire) — L'identifiant de session OpenTok qui regroupe les flux OpenTok que vous souhaitez inclure dans le flux WebSocket. La fonctionnalité « Audio Connector » n'est prise en charge que dans les sessions routées (sessions qui utilisent le Routeur multimédia OpenTok).

  • token​ (obligatoire) — Le jeton OpenTok à utiliser pour la connexion via Audio Connector à la session OpenTok. Vous pouvez ajouter un jeton data pour vérifier que la connexion correspond au point de terminaison Audio Connector ou pour obtenir d'autres données d'identification. (Les bibliothèques client OpenTok incluent des propriétés permettant d'examiner les données de connexion d'un client connecté à une session.) Si vous comptez utiliser Audio Connector pour publier un fichier audio dans la session, définissez le rôle du jeton sur publisher ou moderator. Consultez le Création de jetons guide du développeur.

  • websocket (obligatoire) : Détails inclus pour la WebSocket :

    • uri ​(obligatoire) : une URI WebSocket accessible au public, qui servira de destination au flux audio (par exemple « wss://example.com/ws-endpoint »).

    • streams (facultatif) — Un tableau contenant les identifiants des flux OpenTok que vous souhaitez inclure dans l'audio WebSocket. Si vous omettez cette propriété, tous les flux de la session seront inclus.

    • headers​ (facultatif) - Un objet de paires clé-valeur d'en-têtes à envoyer à votre serveur WebSocket avec chaque message. serveur WebSocket avec chaque message, d'une longueur maximale de 512 octets.

    • audioRate (facultatif) - Un nombre représentant la fréquence d'échantillonnage audio en Hz. Les valeurs acceptées sont 8000, 16000 (par défaut) et 24000.

    • audioTransport (facultatif) - Un objet JSON qui configure la façon dont l'audio est sérialisé sur le câble WebSocket. sur le câble WebSocket. Par défaut, l'audio est envoyé sous forme de trames binaires PCM 16 bits brutes. Définissez ceci pour utiliser de l'audio base64 enveloppé de JSON, ce qui est requis par certains fournisseurs d'IA (par exemple, OpenAI Realtime). L'objet possède les propriétés suivantes :

      • transport (obligatoire) - "binary" (PCM16 brut, par défaut) ou "json".
      • encoding (nécessaire lorsque le transport est "json") - "base64".
      • audio_field (facultatif) - Clé JSON pour les données audio sortantes. La valeur par défaut est "audio".
      • receive_audio_field (facultatif) - Clé JSON pour les données audio entrantes (lorsque la fonction bidirectionnelle est activée). La valeur par défaut est la même que celle de audio_field.
      • static_fields (facultatif) - Un objet de paires clé-valeur supplémentaires incluses dans chaque message audio JSON sortant.

    • bidirectional (facultatif) — (booléen) Indique s'il faut envoyer les données audio provenant de la connexion WebSocket vers un flux publié dans la session. La valeur par défaut est false (le WebSocket n'est pas utilisé pour publier un flux). Pour plus de détails, consultez le Guide du développeur Audio Connector.

Réponse

Un appel réussi génère une réponse HTTP avec le code d'état 200, dont les détails figurent dans les données de réponse au format JSON :

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

Les données de la réponse JSON comprennent les propriétés suivantes :

  • id - ID unique identifiant la connexion WebSocket du connecteur audio.

  • connectionId — L'identifiant de connexion OpenTok correspondant à la connexion WebSocket de l'Audio Connector au sein de la session OpenTok.

En cas d'erreur, la réponse HTTP comportera l'un des codes d'état suivants :

  • 400 — Demande non valide. Cette réponse peut indiquer que les données contenues dans votre requête sont au format JSON non valide, ou qu'une des propriétés JSON est non valide.
  • 403 — Erreur d'authentification.
  • 409 — Seules les sessions acheminées sont autorisées à établir des connexions WebSocket via Audio Connector.
  • 500 — Erreur du serveur OpenTok.

Exemple

Lancement d'un WebSocket 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

Création d'une nouvelle clé API de projet

Utilisez cette méthode pour créer une clé API OpenTok et un secret pour un projet.

Important : Une fois le projet créé, il peut s'écouler jusqu'à 60 secondes avant qu'il ne soit disponible.

Vous pouvez également créer un nouveau projet sur votre Compte Video API de Vonage page.

POST va conclure un partenariat

Envoyez une requête HTTP POST à l'URL suivante :

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

Propriétés de l'en-tête POST

Si vous comptez envoyer des données de requête pour définir un nom (voir la section suivante, « Données POST »), définissez le Content-Type à l'en-tête application/json. Sinon, ne configurez pas le Content-Type l'en-tête.

Authentifiez cet appel API à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Définissez cet en-tête sur un jeton JWT (voir Authentification). Notez que vous devez utiliser le au niveau de l'account Clé API et au niveau de l'account API clé secrète lors de la création du jeton. La clé API et la clé secrète au niveau de l'Account ne sont accessibles qu'aux administrateurs enregistrés de votre compte OpenTok.

Données POST

Incluez un objet JSON se présentant sous la forme suivante dans le corps de la requête :

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

Si vous ne souhaitez pas attribuer de nom au projet, ne saisissez aucun contenu.

Réponse HTTP

La réponse HTTP comportera l'un des codes d'état suivants :

  • 200 — Réussite. Les données de réponse sont un détails du projet objet.

  • 400 — Demande non valide. Cette réponse peut indiquer que les données contenues dans votre demande ne sont pas au format JSON valide.

  • 403 — Erreur d'authentification.

  • 500 — Erreur du serveur OpenTok.

Exemple

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

Modification du statut d'une clé API de projet

Les administrateurs de compte peuvent utiliser cette méthode pour modifier le statut d'un projet. Le statut peut être « actif » ou « suspendu ». Si le statut d'un projet est « suspendu », vous ne pourrez plus utiliser la clé API du projet (ni aucune session OpenTok créée à l'aide de celle-ci).

Vous pouvez faire passer le statut d'un projet de « actif » à « suspendu », et inversement.

PUT à un partenaire

Envoyez une requête HTTP PUT à l'URL suivante :

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

Où <api_key> Il s'agit de la clé API du projet.

Propriétés de l'en-tête PUT

Régler le Content-Type à l'en-tête application/json.

Authentifiez cet appel API à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Définissez cet en-tête sur un jeton JWT (voir Authentification). Notez que vous devez utiliser le au niveau de l'account Clé API et au niveau de l'account API clé secrète lors de la création du jeton. La clé API et la clé secrète au niveau de l'Account ne sont accessibles qu'aux administrateurs enregistrés de votre compte OpenTok.

Données PUT

Incluez un objet JSON se présentant sous la forme suivante dans le corps de la requête :

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

Réponse HTTP

La réponse HTTP comportera l'un des codes d'état suivants :

  • 200 — Réussite. Les données de réponse sont les suivantes : détails du projet objet.

  • 400 — Demande non valide. Cette réponse peut indiquer que les données contenues dans votre demande ne sont pas au format JSON valide.

  • 403 — Erreur d'authentification.

  • 500 — Erreur du serveur OpenTok.

Exemple

L'exemple suivant permet de définir le statut du projet « Acme » sur « suspendu » :

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

Supprimer un projet

Utilisez cette méthode pour supprimer un projet. Cela empêche l'utilisation de la clé API du projet (ainsi que de toutes les sessions OpenTok créées à l'aide de celle-ci).

Vous pouvez également, à titre temporaire, suspendre la clé API d'un projet.

Remarque : Vous pouvez également supprimer un projet sur votre Compte Video API de Vonage page.

SUPPRIMER pour passer à un partenaire

Envoyez une requête HTTP DELETE à l'URL suivante :

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

Où <api_key> Il s'agit de la clé API du projet.

Propriétés de l'en-tête DELETE

Authentifiez cet appel API à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Définissez cet en-tête sur un jeton JWT (voir Authentification). Notez que vous devez utiliser le au niveau de l'account Clé API et au niveau de l'account API clé secrète lors de la création du jeton. La clé API et la clé secrète au niveau de l'Account ne sont accessibles qu'aux administrateurs enregistrés de votre compte OpenTok.

Réponse HTTP

La réponse HTTP comportera l'un des codes d'état suivants :

  • 204 — Réussite (pas de contenu).
  • 403 — Erreur d'authentification.
  • 404 — Page introuvable. Il n'existe aucun projet associé à la clé API fournie.
  • 500 — Erreur du serveur OpenTok.

Exemple

L'exemple suivant permet de supprimer un projet :

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

Obtenir des informations sur les projets

Utilisez cette méthode pour récupérer une fiche détaillée décrivant le projet (ou pour récupérer les fiches de tous les projets). Voir détails du projet objet.

Devenir partenaire de GET

Pour obtenir des informations sur un projet spécifique, envoyez une requête GET à l'URL suivante :

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

Où <api_key> Il s'agit de la clé API du projet.

Pour obtenir des informations sur l'ensemble de vos projets, envoyez une requête GET à l'URL suivante :

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

Propriétés de l'en-tête GET

Authentifiez cet appel API à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Définissez cet en-tête sur un jeton JWT (voir Authentification). Notez que vous devez utiliser le au niveau de l'account Clé API et au niveau de l'account API clé secrète lors de la création du jeton. La clé API et la clé secrète au niveau de l'Account ne sont accessibles qu'aux administrateurs enregistrés de votre compte OpenTok.

Réponse HTTP

La réponse HTTP comportera l'un des codes d'état suivants :

  • 200 — Réussite. Les données de réponse correspondent à l'objet « détails du projet » ou à un tableau d'objets « détails du projet ». Voir détails du projet objet.

  • 403 — Erreur d'authentification.

  • 404 — Page introuvable. Il n'existe aucun projet associé à la clé API fournie.

  • 500 — Erreur du serveur OpenTok.

### Exemple

L'exemple suivant permet d'obtenir des informations détaillées sur un projet spécifique :

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 réponse est au format JSON détails du projet objet.

L'exemple suivant permet d'obtenir des informations détaillées sur tous vos projets :

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 réponse est un tableau de détails du projet objets.

Génération d'un nouveau secret API de projet

Pour des raisons de sécurité, vous pouvez souhaiter générer une nouvelle clé secrète API pour un projet.

Remarque : Utilisez la nouvelle clé secrète de l'API pour tous les appels à l'API REST et avec les SDK côté serveur d'OpenTok. Lorsque vous générez une nouvelle clé secrète de l'API, toutes les clés existantes jetons client ne sont plus valides (et ne peuvent plus être utilisés pour se connecter à des sessions OpenTok) ; utilisez la nouvelle clé secrète de l'API avec le Client SDK serveur OpenTok pour générer des jetons client.

POST pour actualiser Secret

Envoyez une requête HTTP POST à l'URL suivante :

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

Où <api_key> Il s'agit de la clé API du projet.

Propriétés de l'en-tête POST

Authentifiez cet appel API à l'aide d'un en-tête HTTP personnalisé — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Définissez cet en-tête sur un jeton JWT (voir Authentification). Notez que vous devez utiliser le au niveau de l'account Clé API et au niveau de l'account API clé secrète lors de la création du jeton. La clé API et la clé secrète au niveau de l'Account ne sont accessibles qu'aux administrateurs enregistrés de votre compte OpenTok.

Réponse HTTP

La réponse HTTP comportera l'un des codes d'état suivants :

  • 200 — Réussite. Les données de réponse sont les suivantes : détails du projet objet, avec la nouvelle clé secrète de l'API.

  • 403 — Erreur d'authentification.

  • 404 — Page introuvable. Il n'existe aucun projet associé à la clé API fournie.

  • 500 — Erreur du serveur OpenTok.

Exemple

L'exemple suivant permet de générer une nouvelle clé secrète API pour le projet :

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