Vonage Video API – REST-API-Referenz

Verwenden Sie die OpenTok-REST-API, um OpenTok-Sitzungen zu erstellen, mit Archiven zu arbeiten und Live-Streams zu verwalten. Die OpenTok-Server-SDKs (für Java, .NET, Node.js, PHP, Pythonund Rubinrot) implementieren viele der Methoden der REST-API.

Die REST-API umfasst Methoden für folgende Bereiche:

Erstellung von Sitzungen, Signalisierung und Moderation

Archivierung

SIP-Zusammenschaltung

Live-Streaming-Übertragungen

Live-Beschriftungen

Erlebnis-Komponist

Audio-Anschluss

Account management

Die OpenTok-SDKs die OpenTok-REST-API als Wrapper umsetzen, um den Aufruf der OpenTok-Plattform zu vereinfachen.

Authentifizierung

REST-API-Aufrufe müssen mithilfe eines benutzerdefinierten HTTP-Headers authentifiziert werden — X-OPENTOK-AUTH — zusammen mit einem JSON-Web-Token. Erstellen Sie das JWT-Token mit den folgenden Claims:

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

Satz iss für Ihren OpenTok-API-Schlüssel. Verwenden Sie für die meisten REST-API-Aufrufe den API-Schlüssel für das jeweilige Projekt in Ihrem Account. Dieser wird auf der Projektseite Ihres Video API-Konto. Die folgenden REST-Methoden sind jedoch auf registrierte Administratoren des OpenTok-Accounts beschränkt. Um diese Methoden nutzen zu können, müssen Sie iss an den auf Account-Ebene API-Schlüssel, der nur für Account-Administratoren verfügbar ist. (siehe Account Management):

Um den API-Schlüssel und das API-Geheimnis auf Account-Ebene abzurufen, melden Sie sich bei Ihrem Video API-Konto, klicken Account-Einstellungen im Menü auf der linken Seite und dann unter OpenTok REST API, klicken Account-Schlüssel anzeigen.

Für die meisten REST-API-Aufrufe legen Sie Folgendes fest: ist zu "project". Für die folgenden Fälle gilt jedoch Account Management REST-Methoden, set ist zu "account":

Satz iat auf den aktuellen Unix-Epochenzeitstempel (wann das Token erstellt wurde) in Sekunden.

Satz exp auf die Ablaufzeit für das Token. Aus Sicherheitsgründen empfehlen wir, dass Sie eine Ablaufzeit verwenden, die nahe an der Erstellungszeit des Tokens liegt (z. B. 3 Minuten nach der Erstellung) und dass Sie für jeden REST-API-Aufruf ein neues Token erstellen. Die maximal zulässige Ablaufzeitspanne beträgt 5 Minuten.

Satz jti auf einen eindeutigen Bezeichner für das JWT. Dies ist optional. Siehe die JSON-Web-Token-Spezifikation für Einzelheiten.

Verwenden Sie Ihren OpenTok-API-Schlüssel als JWT-Geheimschlüssel und signieren Sie diesen mit dem Verschlüsselungsalgorithmus HMAC-SHA256. Verwenden Sie für die meisten REST-API-Aufrufe den API-Schlüssel für das jeweilige Projekt in Ihrem Account. Dieser wird auf der Projektseite Ihres Video API-Konto. Die folgenden REST-Methoden sind jedoch auf registrierte Administratoren des OpenTok-Accounts beschränkt. Um diese Methoden nutzen zu können, müssen Sie die auf Account-Ebene API Schlüssel und Geheimcode (der nur für Account-Administratoren verfügbar ist) als JWT-Geheimcode (siehe Account Management):

Der folgende Python-Code erstellt beispielsweise ein Token, das in einem OpenTok-REST-API-Aufruf verwendet werden kann:

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

Ersetzen Sie die my-OpenTok-API-key und my-OpenTok-API-secret mit dem OpenTok-API-Schlüssel und dem API-Geheimnis.

Anmerkung: Vor der Verwendung von JSON-Web-Tokens wurden OpenTok-REST-API-Aufrufe mithilfe eines benutzerdefinierten HTTP-Headers authentifiziert: X-TB-PARTNER-AUTH wobei der Wert aus Ihrem OpenTok-API-Schlüssel und Ihrem API-Geheimnis besteht, die durch einen Doppelpunkt verbunden sind:

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

Diese Form der Authentifizierung (unter Verwendung von X-TB-PARTNER-AUTH) ist veraltet, und Sie sollten nun JSON-Web-Tokens für die Authentifizierung verwenden. (Die Nutzung dieser veralteten Authentifizierungsmethode läuft im Juli 2017 aus.)

Erstellen einer Sitzung

Eine neue Sitzung erstellen.

URL der Ressource:

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

Ressourcenverb:

POST

Eigenschaften des POST-Headers

API-Aufrufe müssen mithilfe eines benutzerdefinierten HTTP-Headers authentifiziert werden — X-OPENTOK-AUTH — zusammen mit einem JSON Web Token (JWT). Siehe Authentifizierung.

Setzen Sie die Content-Type Kopfzeile zu application/x-www-form-urlencoded:

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

Setzen Sie die Accept Kopfzeile zu application/json:

Accept:application/json

POST-Parameter

archiveName

Der Name, der für Archive in automatisch archivierten Sitzungen verwendet werden soll. Bei Aktivierung dieser Option wird die archiveMode Die Option muss auf always sonst tritt ein Fehler auf. Der Archivname darf maximal 80 Zeichen lang sein. Aufgrund von Kodierungsbeschränkungen werden die folgenden Sonderzeichen in einen Doppelpunkt (:) umgewandelt: ~, -, _. Wenn Sie keinen Namen festlegen und die archiveMode Die Option ist auf always, ist der Archivname leer.

archiveResolution

Die Auflösung der Archive in einer automatisch archivierten Sitzung. Gültige Werte sind „480x640“, „640x480“ (Standard), „720x1280“, „1280x720“, „1080x1920“ und „1920x1080“. Bei Aktivierung dieser Option wird die archiveMode Die Option muss auf always sonst kommt es zu einem Fehler.

location

Die IP-Adresse, die die Vonage Video API verwendet, um die Sitzung in ihrem globalen Netzwerk zu verorten. Wenn kein Standorthinweis übergeben wird (was empfohlen wird), nutzt die Sitzung einen Medienserver, der auf dem Standort des ersten Clients basiert, der eine Verbindung zur Sitzung herstellt. Übergeben Sie einen Standorthinweis nur dann, wenn Sie die allgemeine geografische Region (und eine repräsentative IP-Adresse) kennen und davon ausgehen, dass sich der erste Client, der eine Verbindung herstellt, möglicherweise nicht in dieser Region befindet. Geben Sie eine IP-Adresse an, die für den geografischen Standort der Sitzung repräsentativ ist.

p2p.preference

Eingestellt auf enabled Wenn Sie möchten, dass Clients versuchen, Audio- und Videostreams direkt an andere Clients zu senden, stellen Sie die Option auf disabled für Sitzungen, die den OpenTok Media Router verwenden. (Optional; die Standardeinstellung lautet disabled -- Die Sitzung nutzt den OpenTok Media Router.)

Die OpenTok Media Router bietet die folgenden Vorteile:

  • Der OpenTok Media Router kann den Bandbreitenverbrauch in Mehrparteien-Sitzungen senken. (Wenn die Eigenschaft „p2p.preference“ auf enabledmuss jeder Client einen separaten Audio-Video-Stream an jeden Client senden, der ihn abonniert).
  • Der OpenTok Media Router kann die Qualität des Nutzererlebnisses verbessern, indem er Audio-Fallback und Video-Wiederherstellung. Dank dieser Funktionen wird das Video auf einem Client unterbrochen (ohne dass andere Clients davon betroffen sind), wenn sich die Verbindung des Clients so weit verschlechtert, dass sie die Wiedergabe des Videos für einen abonnierten Stream nicht mehr unterstützt; der Client empfängt dann nur noch Audio. Verbessert sich die Verbindung des Clients wieder, wird das Video wieder angezeigt.
  • Der OpenTok Media Router unterstützt die Archivierungsfunktion, mit dem Sie OpenTok-Sitzungen aufzeichnen, speichern und abrufen können.

Mit dem p2p.preference Ist diese Eigenschaft auf „enabled“ gesetzt, versucht die Sitzung, Streams direkt zwischen den Clients zu übertragen. Wenn Clients aufgrund von Firewall-Einschränkungen keine Verbindung herstellen können, nutzt die Sitzung den OpenTok-TURN-Server, um Audio- und Videostreams weiterzuleiten.

Beispielanfragen

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

Das folgende Beispiel für eine Befehlszeile erstellt eine Sitzung, die den OpenTok Media Router nutzt und einen Standorthinweis angibt:

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

Das folgende Beispiel für eine Befehlszeile erstellt eine Sitzung, bei der versucht wird, Streams direkt zwischen Clients zu übertragen (ohne Verwendung des OpenTok Media Routers):

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

Das folgende Beispiel für eine Befehlszeile erstellt eine automatisch archivierte Sitzung:

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

Beispielantwort

Die Antwort besteht aus JSON-Daten in folgender Form:

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

Beachten Sie bitte, dass das Antwortformat XML ist, wenn Sie den Header „Accept:application/json“ nicht angeben. Diese XML-Version des API-Aufrufs ist veraltet.

Die HTTP-Antwort enthält den Statuscode 403, wenn Sie einen ungültigen OpenTok-API-Schlüssel oder ein ungültiges JWT-Token übergeben.

Die HTTP-Antwort enthält den Statuscode 500, der auf einen OpenTok-Serverfehler hinweist.

Senden eines Signals vom App-Server an verbundene Clients

Verwenden Sie die Signal-REST-API, um Signale an alle Teilnehmer einer aktiven OpenTok-Sitzung oder an einen bestimmten, mit dieser Sitzung verbundenen Client zu senden. Vom Server gesendete Signale haben einen leeren from Parameter im empfangenen Signal Handler auf den mit der Sitzung verbundenen Clients. Bei einem Signal, das von einem Teilnehmer der Sitzung gesendet wird, wird das from In dieser Eigenschaft wird die Verbindungs-ID des Clients gespeichert, der das Signal gesendet hat; in diesem Fall gibt es jedoch keine zugehörige Verbindung.

Bei den beiden folgenden Signalbeispielen wird der Request-Body verwendet, um sowohl die type und data Felder. Diese entsprechen den Typ- und Datenparametern, die an die Handler für empfangene Client-Signale übergeben werden.

type

Zeichenkette. Die maximale Länge beträgt 128 Byte, und sie darf nur Buchstaben (A–Z und a–z), Numbers (0–9) sowie die Zeichen „-“, „_“ und „~“ enthalten.

data

Zeichenkette. Die maximale Länge beträgt 8 KB.

Alle mit der Sitzung verbundenen Clients benachrichtigen

Sende einen HTTP-POST-Request an die signal Ressource der Sitzung:

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

Anmerkung: Bisher wurde für diese REST-URL Folgendes verwendet: /partner (das inzwischen veraltet ist) anstelle von /project.

Einen bestimmten, mit der Sitzung verbundenen Client kennzeichnen

Sende einen HTTP-POST-Request an die signal Ressource einer bestimmten Verbindungs-ID, die zur Sitzung gehört:

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

Signalisierung von Fehlerreaktionen

Fehler werden in der Antwort als HTTP-Statuscodes zurückgegeben:

  • 400 — Eine der wesentlichen Eigenschaften — data, type, sessionId oder connectionId — ist ungültig.
  • 403 — Sie sind nicht berechtigt, das Signal zu senden. Überprüfen Sie Ihre Anmeldedaten.
  • 404 — Der durch den connectionId Die Eigenschaft ist nicht mit der Sitzung verknüpft.
  • 413 — Die Typzeichenfolge überschreitet die maximale Länge (128 Byte) oder die Datenzeichenfolge überschreitet die maximale Größe (8 kB).

Im Fehlerfall sieht der Antworttext wie folgt aus:

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

Erzwingen der Trennung eines Client-Endpunkts von einer Sitzung

Ihr Anwendungsserver kann einen Client von einer OpenTok-Sitzung trennen, indem er eine HTTP-DELETE-Anfrage an die Ressource für die Verbindung dieses Clients sendet:

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}

Anmerkung: Bisher wurde für diese REST-URL Folgendes verwendet: /partner (das inzwischen veraltet ist) anstelle von /project.

Fehlermeldungen

Fehler werden in der Antwort als HTTP-Statuscodes zurückgegeben:

  • 400 — Eines der Argumente — sessionId oder connectionId — ist ungültig.
  • 403 — Sie sind nicht berechtigt, eine erzwungene Trennung durchzuführen. Überprüfen Sie Ihre Anmeldedaten.
  • 404 — Der durch den connectionId Die Eigenschaft ist nicht mit der Sitzung verknüpft.

Im Fehlerfall sieht der Antworttext wie folgt aus:

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

Stream-Informationen abrufen

Verwenden Sie diese Methode, um Informationen zu einem OpenTok-Stream (oder allen Streams in einer Sitzung) abzurufen.

Sie können diese Methode beispielsweise aufrufen, um Informationen zu den von einem OpenTok-Stream verwendeten Layout-Klassen abzurufen. Die Layout-Klassen legen fest, wie der Stream im Layout eines Broadcast-Streams angezeigt wird. Weitere Informationen finden Sie unter Zuweisung von Layout-Klassen für Live-Streams zu OpenTok- Streams.

HTTP-GET-Anfrage an „session/stream“

Um Informationen zur Layout-Klasse für einen bestimmten Stream abzurufen, senden Sie eine HTTP-GET-Anfrage an die folgende URL:

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

  • Ersetzen Sie <apiKey> mit Ihrem OpenTok-API-Schlüssel.

  • Ersetzen Sie <sessionId> mit der Sitzungs-ID.

  • Ersetzen Sie <streamId> mit der Stream-ID.

Um Informationen zu den Layout-Klassen aller Streams in einer Sitzung abzurufen, senden Sie eine HTTP-GET-Anfrage an die folgende URL (ohne die Stream-ID am Ende):

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

GET-Header-Eigenschaften

Authentifizieren Sie diesen API-Aufruf mithilfe eines benutzerdefinierten HTTP-Headers — X-OPENTOK-AUTH — auf ein JSON-Web-Token gesetzt. Siehe Authentifizierung.

Antwort

Beim Abrufen von Layout-Klasseninformationen für einen einzelnen Stream enthalten die JSON-Daten der Antwort einen layoutClassList Array:

{
  "id": "8b732909-0a06-46a2-8ea8-074e64d43422",
  "videoType": "camera",
  "name": "",
  "layoutClassList": ["full"]
}
  • Die layoutClassList ist ein Array mit den Layout-Klassen für den Stream.
  • Die id Eigenschaft ist die Stream-ID.
  • Die videoType Die Eigenschaft ist auf „camera“, „screen“ oder „custom“ gesetzt. Ein „screen“-Video nutzt die Bildschirmfreigabe auf dem Publisher als Videoquelle; ein „custom“-Video wird von einem Web-Client unter Verwendung eines HTML-VideoTrack-Elements als Videoquelle veröffentlicht.
  • Die name ist der Stream-Name (falls er bei der Veröffentlichung des Streams durch den Client festgelegt wurde).

Beim Abrufen von Layout-Klasseninformationen für mehrere Streams enthalten die JSON-Daten der Antwort einen items Eigenschaft, bei der es sich um ein Array handelt, das Layout-Informationen für Streams in der Sitzung enthält:

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

Die HTTP-Antwort enthält einen der folgenden Statuscodes:

  • 200 – Erfolg.
  • 400 – Ungültige Anfrage. Diese Antwort kann darauf hinweisen, dass die Daten in Ihrer Anfrage ungültiges JSON sind. Oder sie kann darauf hinweisen, dass Sie keine Sitzungs-ID übergeben haben oder eine ungültige Stream-ID übergeben haben.
  • 403 – Sie haben einen ungültigen OpenTok-API-Schlüssel oder ein ungültiges JWT-Token übermittelt.
  • 404 – Die Sitzung existiert, es wurden ihr jedoch noch keine Streams hinzugefügt.
  • 408 — Sie haben eine ungültige Stream-ID übergeben.
  • 500 – OpenTok-Serverfehler.

Beispiel

Das folgende Beispiel für eine Befehlszeile ruft Informationen zur Layoutklasse für einen bestimmten Stream ab:

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
  • Legen Sie den Wert für api_key mit Ihrem OpenTok-API-Schlüssel.
  • Legen Sie den Wert für json_web_token zu einem JSON-Web-Token (siehe Authentifizierung).
  • Setzen Sie die session_id Wert an die Sitzung übergeben.
  • Setzen Sie die stream_id Wert zur Stream-ID hinzufügen.

Das folgende Beispiel für eine Befehlszeile ruft Informationen zu den Layoutklassen aller Streams in einer Sitzung ab:

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/
  • Legen Sie den Wert für api_key mit Ihrem OpenTok-API-Schlüssel.
  • Legen Sie den Wert für json_web_token zu einem JSON-Web-Token (siehe Authentifizierung).
  • Setzen Sie die session_id Wert an die Sitzung übergeben.

Einen einzelnen Stream zwingen, veröffentlichtes Audio stummzuschalten

Mithilfe der OpenTok-REST-API können Sie einen Publisher eines bestimmten Streams dazu zwingen, dessen Ton stummzuschalten.

POST an session/stream/mute

Senden Sie eine HTTP-POST-Anfrage an die folgende URL:

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

Ersetzen Sie <api_key> mit dem API-Schlüssel des OpenTok-Projekts (siehe die Projektseite Ihres Video API-Konto). Ersetzen Sie <session_id> mit der Sitzungs-ID der Sitzung, die den Stream enthält. Ersetzen Sie <stream_id> mit der Stream-ID.

Eigenschaften des POST-Headers

Authentifizieren Sie diesen API-Aufruf mithilfe eines benutzerdefinierten HTTP-Headers — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Setzen Sie diesen Header auf ein JWT-Token (siehe Authentifizierung).

HTTP-Antwort

Die HTTP-Antwort enthält einen der folgenden Statuscodes:

  • 200 – Erfolg. Die Antwortdaten sind ein Projektdetails Objekt.

  • 400 – Ungültige Anfrage.

  • 403 – Authentifizierungsfehler.

  • 404 – Nicht gefunden. Die Sitzung oder der Stream wurde nicht gefunden.

  • 500 – OpenTok-Serverfehler.

Beispiel

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

Streams in einer Sitzung zwangsweise stummschalten, um veröffentlichtes Audio zu unterdrücken

Mithilfe der OpenTok-REST-API können Sie für alle Streams (mit Ausnahme einer optionalen Liste von Streams) in einer Sitzung die Stummschaltung des veröffentlichten Audios erzwingen. Sie können diese Methode auch verwenden, um den erzwungenen Stummschaltstatus einer Sitzung aufzuheben (siehe unten).

POST an session/mute

Senden Sie eine HTTP-POST-Anfrage an die folgende URL:

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

Ersetzen Sie <api_key> mit dem API-Schlüssel des OpenTok-Projekts (siehe die Projektseite Ihres Video API-Konto). Ersetzen Sie <session_id> mit der Sitzungs-ID.

Eigenschaften des POST-Headers

Setzen Sie die Content-Type Kopfzeile zu application/json.

Authentifizieren Sie diesen API-Aufruf mithilfe eines benutzerdefinierten HTTP-Headers — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Setzen Sie diesen Header auf ein JWT-Token (siehe Authentifizierung).

POST-Daten

Fügen Sie ein JSON-Objekt in der folgenden Form als Inhalt des Request-Bodys ein:

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

Die JSON-Daten enthalten die folgenden Eigenschaften:

  • active (Boolescher Wert, erforderlich) — Gibt an, ob die Streams in der Sitzung stummgeschaltet werden sollen (true) und den Stummschaltungsstatus der Sitzung aktivieren oder den Stummschaltungsstatus der Sitzung deaktivieren (false). Wenn der Stummschaltungsmodus aktiviert ist (true), alle aktuellen und zukünftigen Streams, die in der Sitzung veröffentlicht werden (mit Ausnahme der Streams im excludedStreamIds array) werden stummgeschaltet. Wenn Sie diese Methode mit dem active Eigenschaft eingestellt auf false, werden zukünftige Streams, die in der Sitzung veröffentlicht werden, nicht stummgeschaltet (bereits stummgeschaltete Streams bleiben jedoch weiterhin stummgeschaltet).

  • excludedStreamIds (Zeichenfolgen-Array, optional) — Die Stream-IDs der Streams, die nicht stummgeschaltet werden sollen. Dies ist eine optionale Eigenschaft. Wenn Sie diese Eigenschaft weglassen, werden alle Streams in der Sitzung stummgeschaltet. Diese Eigenschaft gilt nur, wenn die active Eigenschaft wird auf true. Wenn die active Eigenschaft wird auf false, wird es ignoriert.

    Die Elemente in der excludedStreamIds Das Array enthält die Stream-IDs (Zeichenketten) der Streams, die Sie von der Stummschaltung ausschließen möchten.

    Wenn Sie kein Array mit ausgeschlossenen Streams angeben möchten, lassen Sie den Inhalt des Hauptteils leer.

HTTP-Antwort

Die HTTP-Antwort enthält einen der folgenden Statuscodes:

  • 200 – Erfolg. Die Antwortdaten sind ein Projektdetails Objekt.

  • 400 – Ungültige Anfrage. Diese Antwort kann darauf hindeuten, dass die Daten in Ihrer Anfrage ungültiges JSON sind.

  • 403 – Authentifizierungsfehler.

  • 404 – Nicht gefunden. Die Sitzung wurde nicht gefunden.

  • 500 – OpenTok-Serverfehler.

Beispiel

Die folgenden Befehle veranlassen alle Streams (mit Ausnahme einer optionalen Liste von Streams) in einer Sitzung, das veröffentlichte Audio stummzuschalten:

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

Um den Stummschaltstatus der Sitzung aufzuheben (damit zukünftige Streams nicht mehr stummgeschaltet werden), rufen Sie die Methode erneut mit dem active Eigenschaft eingestellt auf 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

Verbindungen in einer Sitzung auflisten

Verwenden Sie diese Methode, um die Verbindungen einer OpenTok-Sitzung aufzulisten, die einem Projekt zugeordnet ist.

HTTP-GET-Anfrage an „session/connection“

Senden Sie eine HTTP-GET-Anfrage an die folgende URL:

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

Ersetzen Sie <api_key> mit Ihrem OpenTok-API-Schlüssel. Weitere Informationen finden Sie auf der Projektseite in Ihrem Video API-Konto.

Ersetzen Sie <sessionId> mit der Sitzungs-ID der Sitzung, die die Verbindungen enthält.

Sie können optionale Abfrageparameter hinzufügen, um die Ergebnisse zu filtern:

  • offset (Ganzzahl, optional): Der nullbasierte Index der ersten zurückzugebenden Verbindung. Der Standardwert ist 0 (die älteste Verbindung).
  • count (Ganzzahl, optional): Die maximale Anzahl der zurückzugebenden Verbindungen. Der Standardwert beträgt 50; der Höchstwert liegt bei 1000.

Der folgende Aufruf ruft beispielsweise 20 Verbindungen ab, beginnend bei Position 400:

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

GET-Header-Eigenschaften

API-Aufrufe müssen mithilfe eines benutzerdefinierten HTTP-Headers – X-OPENTOK-AUTH – sowie eines JSON-Web-Tokens (JWT) authentifiziert werden. Siehe Authentifizierung.

Antwort

Die Rohdaten der HTTP-Antwort mit dem Statuscode 200 sind eine JSON-kodierte Nachricht in folgender Form:

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

Das JSON-Objekt enthält die folgenden Eigenschaften:

  • count — Die Gesamtzahl der Verbindungen in der Sitzung.
  • projectId — Ihr OpenTok-API-Schlüssel.
  • sessionId — Die Sitzungs-ID.
  • Elemente — Ein Array von Objekten, die jede abgerufene Verbindung definieren. Die Verbindungen werden in der Rückgabemenge von der ältesten zur neuesten aufgelistet.

Jedes Element im Array „items“ steht für eine Verbindung und verfügt über die folgenden Eigenschaften:

  • connectionId — Die Verbindungs-ID.
  • connectionState – Der Status der Verbindung:
    • „Verbinden“ – Die Verbindung befindet sich noch in der Aufbauphase und ist noch nicht vollständig hergestellt.
    • „Verbunden“ – Die Verbindung ist vollständig hergestellt und mit der Sitzung verbunden.
  • createdAt — Der Zeitstempel für den Zeitpunkt der Verbindungsherstellung, ausgedrückt in Millisekunden seit der Unix-Epoche (1. Januar 1970, 00:00:00 UTC).

Die HTTP-Antwort enthält einen der folgenden Statuscodes:

  • 200 – Erfolg. Die Antwortdaten enthalten die Verbindungsliste einer OpenTok-Sitzung.
  • 400 – Ungültige Anfrage. Diese Antwort kann darauf hindeuten, dass ein Parameter Ihrer Abfrage ungültig ist.
  • 403 – Authentifizierungsfehler.
  • 404 – Die Sitzung wurde nicht gefunden.
  • 500 – OpenTok-Serverfehler.

Beispiel

In den folgenden Beispielen:

  • Setzen Sie den Wert für „API_KEY“ auf Ihren OpenTok-API-Schlüssel.
  • Setzen Sie den Wert für „JWT“ auf ein gültiges JSON-Web-Token (siehe Authentifizierung).
  • Setzen Sie den Wert für SESSION_ID auf Ihre OpenTok-Sitzungs-ID.

Das folgende Beispiel für eine Befehlszeile ruft die ersten 50 Verbindungen der Sitzung ab:

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

Das folgende Befehlszeilenbeispiel ruft die erste in der Sitzung erstellte Verbindung ab:

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

Das folgende Beispiel für eine Befehlszeile ruft zwei Verbindungen ab, beginnend mit der fünften Verbindung, die in der Sitzung erstellt wurde:

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

Im folgenden Beispiel werden keine Verbindungen abgerufen, da der Offset größer ist als die Anzahl der Verbindungen in der Sitzung:

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

Eine Sitzung migrieren

Verwenden Sie diese Methode, um eine Sitzung bei Bedarf auf einen anderen Server zu migrieren. Eine Migration ist nur möglich, wenn für die Sitzung derzeit keine Migration läuft und wenn die Sitzung nicht erst kürzlich erstellt oder migriert wurde. (Siehe die Server-Rotation und Sitzungsmigration Entwicklerhandbuch.)

Anmerkung: Wenn die Migration ausgelöst wird, werden alle Verbindungen, die über die Funktion „migrate“ verfügen, auf den neuen Server migriert. Alle Verbindungen ohne die Funktion „migrate“ werden im Rahmen des Migrationsprozesses geschlossen. (Siehe Ermöglichung der Sitzungsmigration in Clients.)

URL der Ressource:

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

Ersetzen Sie <api_key> mit dem API-Schlüssel des OpenTok-Projekts (siehe die Projektseite Ihres Video API-Konto). Ersetzen Sie <session_id> mit der Sitzungs-ID der Sitzung, die auf einen anderen Server migriert werden soll.

Ressourcenverb:

POST

Eigenschaften des POST-Headers

Setzen Sie die Content-Type Kopfzeile zu application/json.

Authentifizieren Sie diesen API-Aufruf mithilfe eines benutzerdefinierten HTTP-Headers — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Setzen Sie diesen Header auf ein JWT-Token (siehe Authentifizierung).

HTTP-Antwort

Bei einigen Fehlerantworten enthält der Antworttext zusätzlich zum HTTP-Antwortcode einen code Feld zur Angabe des genauen Grundes für den Fehler. Die HTTP-Antwort enthält einen der folgenden Statuscodes:

  • 202 – Akzeptiert. Die Anfrage ist gültig und die Sitzung wird migriert.

  • 400 – Ungültige Anfrage. Diese Antwort kann darauf hinweisen, dass in der Anfrage einige Informationen fehlen.

  • 403 – Authentifizierungsfehler. Grund: Nicht autorisiertes oder ungültiges Token

  • 404 – Nicht gefunden. Die Sitzung wurde nicht gefunden.

  • 409 – Konflikt. Die Sitzung kann derzeit nicht migriert werden. Dies kann auf einen der folgenden Gründe zurückzuführen sein:

    • Code 15214: Für die Sitzung läuft bereits eine Migration.
    • Code 15215: Die Sitzung wurde kürzlich erstellt oder migriert.

  • 500 – Interner Serverfehler bei OpenTok.

Musteranfrage

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
  • Legen Sie den Wert für API_KEY mit Ihrem OpenTok-API-Schlüssel.
  • Legen Sie den Wert für JWT zu einem JSON-Web-Token (siehe Authentifizierung).
  • Setzen Sie die SESSION_ID Wert für die ID der zu migrierenden Sitzung.

Beispielantwort

Antwort bei Authentifizierungsfehler:

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

Starten einer Archivaufzeichnung

Um die Aufzeichnung einer OpenTok-Sitzung zu starten, senden Sie eine HTTP-POST-Anfrage.

Um die Aufzeichnung eines Archivs erfolgreich zu starten, muss mindestens ein Client mit der Sitzung verbunden sein.

Sie können nur Sitzungen archivieren, bei denen der OpenTok Media Router verwendet wird (und der Medienmodus auf „routed“ eingestellt ist); Sitzungen, bei denen der Medienmodus auf „relayed“ eingestellt ist, können nicht archiviert werden. (Siehe Der OpenTok Media Router und die Medienmodi.)

Weitere Informationen finden Sie in der OpenTok-Entwicklerhandbuch zur Archivierung.

HTTP-POST an das Archiv

Senden Sie eine HTTP-POST-Anfrage an die folgende URL:

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

Ersetzen Sie <api_key> mit Ihrem OpenTok-API-Schlüssel. Weitere Informationen finden Sie auf der Projektseite Ihres Video API-Konto.

Anmerkung: Bisher wurde für diese REST-URL Folgendes verwendet: /partner (das inzwischen veraltet ist) anstelle von /project.

Eigenschaften des POST-Headers

API-Aufrufe müssen mithilfe eines benutzerdefinierten HTTP-Headers authentifiziert werden — X-OPENTOK-AUTH — zusammen mit einem JSON Web Token (JWT). Siehe Authentifizierung.

Setzen Sie den „Content-Type“-Header auf „application/json“:

Content-Type:application/json

POST-Daten

Fügen Sie ein JSON-Objekt in der folgenden Form als POST-Daten ein:

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

Das JSON-Objekt enthält die folgenden Eigenschaften:

  • sessionId (Zeichenkette) — (Erforderlich) Die Sitzungs-ID der OpenTok-Sitzung, deren Archivierung Sie starten möchten
  • hasAudio (Boolescher Wert) — (Optional) Gibt an, ob das Archiv Audio aufzeichnen soll (true, Standard) oder nicht (false). Wenn Sie beide hasAudio und hasVideo auf „false“ gesetzt ist, führt der Aufruf dieser Methode zu einem Fehler.
  • hasVideo (Boolescher Wert) — (Optional) Gibt an, ob das Archiv Videoaufnahmen machen soll (true, Standard) oder nicht (false). Wenn Sie beide hasAudio und hasVideo auf „false“ gesetzt ist, führt der Aufruf dieser Methode zu einem Fehler.
  • layout (Objekt) — Optional. Geben Sie dies an, um den anfänglichen Layouttyp für das Archiv festzulegen. Dies gilt nur für zusammengestellte Archive. Dieses Objekt hat drei Eigenschaften: type, stylesheetund screenshareType, die jeweils Zeichenfolgen sind. Gültige Werte für die layout Eigenschaften sind "bestFit" (beste Anpassung), "custom" (Gewohnheit), "horizontalPresentation" (horizontale Darstellung), "pip" (Bild-in-Bild), und "verticalPresentation" (vertikale Darstellung)). Wenn Sie einen "custom" Layout-Typ, setzen Sie die stylesheet Eigenschaft der layout dem Stylesheet hinzufügen. (Bei anderen Layouttypen darf kein stylesheet Eigenschaft.) Legen Sie die screenshareType Eigenschaft für den Layout-Typ, der verwendet werden soll, wenn in der Sitzung ein Bildschirmfreigabe-Stream vorliegt. (Diese Eigenschaft ist optional.) Hinweis: Wenn Sie die screenshareType Eigenschaft, müssen Sie die type Eigenschaft auf "bestFit" und lassen Sie die stylesheet Eigenschaft nicht festgelegt. Wenn Sie keinen anfänglichen Layouttyp angeben, verwendet das Archiv den am besten geeigneten Layouttyp. Weitere Informationen finden Sie unter Anpassen des Videolayouts für zusammengestellte Archive.
  • maxBitrate (optional) — Die maximale Video-Bitrate für das Archiv in Bit pro Sekunde. Der Mindestwert beträgt 100.000, der Höchstwert 6.000.000. Diese Option gilt nur für zusammengesetzte Archive. Legen Sie die maximale Video-Bitrate fest, um die Größe des zusammengesetzten Archivs zu steuern. Diese maximale Bitrate gilt ausschließlich für die Video-Bitrate. Wenn das Ausgabearchiv Audio enthält, werden diese Bits von der Begrenzung ausgenommen. Wenn Sie die maxBitrate Eigenschaft verwendet das Archiv eine konstante Bitrate. Sie können nicht sowohl die maxBitrate Eigenschaft und die quantizationParameter Eigenschaften – dies führt zu einem Fehler.
  • multiArchiveTag (Zeichenkette) — (Optional) Aktivieren Sie diese Option, um die gleichzeitige Aufzeichnung mehrerer Archive für dieselbe Sitzung zu unterstützen. Legen Sie hierfür für jedes gleichzeitig laufende Archiv einer laufenden Sitzung eine eindeutige Zeichenkette fest. Sie müssen diese Option auch aktivieren, wenn Sie ein Archiv in einer Sitzung manuell starten, die automatisch archiviert. Wenn Sie keinen eindeutigen multiArchiveTag, Sie können pro Sitzung jeweils nur ein Archiv aufzeichnen. Siehe Gleichzeitige Archive.
  • name (Zeichenkette) — (Optional) Der Name des Archivs (zur eigenen Identifizierung). Die maximale Länge des Archivnamens beträgt 255 Zeichen.
  • outputMode (Zeichenkette) — (Optional) Gibt an, ob alle Streams im Archiv in einer einzigen Datei aufgezeichnet werden ("composed", die Standardeinstellung) oder auf einzelne Dateien ("individual"). Siehe Einzelne Streams und zusammengesetzte Archive.
  • quantizationParameter (Zahl) — (Optional) Der Quantisierungsparameter (QP) für ein zusammengesetztes Archiv, der das Verhältnis zwischen Videoqualität und Dateigröße steuert. Durch die Festlegung des Quantisierungsparameters verwendet das Archiv eine variable Bitrate und eine konstante Kompressionsquantisierung, was zu einem gleichbleibenden Qualitätsniveau über Szenenwechsel hinweg führt. Gültige Werte liegen zwischen 15 und 40; Werte zwischen 20 und 30 liefern angemessene Ergebnisse ohne großen wahrnehmbaren Qualitätsunterschied. Niedrigere QP-Werte führen zu einer feineren Quantisierung bei der Videokomprimierung, was eine höhere Videoqualität (mit mehr Bilddetails) und eine größere Dateigröße zur Folge hat. Höhere QP-Werte führen zu einer gröberen Quantisierung bei der Videokomprimierung, wodurch die Videoqualität abnimmt und die Dateigröße kleiner wird. Sie können einen Quantisierungsparameter nur für ein zusammengesetztes Archiv festlegen – die Einstellung quantizationParameter Das Abrufen der Archivdaten eines einzelnen Streams führt zu einem Fehler. Sie können nicht sowohl die quantizationParameter Eigenschaft und die maxBitrate Eigenschaft - dies führt zu einem Fehler.
  • resolution (Zeichenkette) — (Optional) Die Auflösung des Archivs, entweder "640x480" (SD-Querformat, Standardeinstellung), "1280x720" (HD Querformat), "1920x1080" (FHD im Querformat), "480x640" (SD-Porträt), "720x1280" (HD-Hochformat) oder "1080x1920" (FHD im Hochformat). Möglicherweise möchten Sie ein Hochformat für Archive verwenden, die Videostreams von Mobilgeräten enthalten (die häufig das Hochformat verwenden). Diese Eigenschaft gilt nur für zusammengesetzte Archive. Wenn Sie diese Eigenschaft festlegen und die outputMode Eigenschaft zu "individual", führt der Aufruf der REST-Methode zu einem Fehler.
  • streamMode (Zeichenkette) — (Optional) Gibt an, ob die im Archiv enthaltenen Streams automatisch ausgewählt werden ("auto", die Standardeinstellung) oder manuell ("manual"). Wenn Streams automatisch ausgewählt werden ("auto"), können alle Streams der Sitzung in das Archiv aufgenommen werden. Wenn Streams manuell ausgewählt werden ("manual"), legen Sie die einzubeziehenden Streams anhand von Aufrufen von diese REST-Methode. Sie können festlegen, ob Audio, Video oder beides eines Streams in das Archiv aufgenommen werden sollen. Bei zusammengesetzten Archiven – sowohl im automatischen als auch im manuellen Modus – fügt der Archiv-Generator Streams auf der Grundlage von Strompriorisierungsregeln.

Die Rohdaten der HTTP-Antwort mit dem Statuscode 200 sind eine JSON-kodierte Nachricht in folgender Form:

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

Das JSON-Objekt enthält die folgenden Eigenschaften:

  • createdAt — Der Zeitstempel für den Zeitpunkt, zu dem das Archiv mit der Aufzeichnung begonnen hat, ausgedrückt in Millisekunden seit der Unix-Epoche (1. Januar 1970, 00:00:00 UTC).
  • hasAudio — Gibt das Archiv Audiodaten auf (wahr) oder nicht (falsch)?
  • hasVideo — Gibt das Archiv Videos auf (wahr) oder nicht (falsch)?
  • id — Die eindeutige Archiv-ID. Speichern Sie diesen Wert für die spätere Verwendung (zum Beispiel, um Die Aufnahme beenden).
  • multiArchiveTag — Die eindeutige Kennung für gleichzeitige Archive (sofern eine festgelegt wurde).
  • name — Der von Ihnen angegebene Name des Archivs (dies ist optional).
  • outputMode — Entweder "composed" oder "individual". Siehe Einzelne Streams und zusammengesetzte Archive.
  • projectId — Ihr OpenTok-API-Schlüssel.
  • resolution — Die Auflösung des Archivs (entweder „640x480“, „1280x720“, „1920x1080“, „480x640“, „720x1280“ oder „1080x1920“). Diese Eigenschaft wird nur für zusammengesetzte Archive festgelegt.
  • sessionId — Die Sitzungs-ID der OpenTok-Sitzung, die archiviert wird.
  • status - Diese ist eingestellt auf "started".
  • streamMode — Ob die im Archiv enthaltenen Streams automatisch ausgewählt werden ("auto", die Standardeinstellung) oder manuell ("manual").
  • streams — Ein Array von Objekten, die den derzeit archivierten Streams entsprechen. Dies wird nur für ein Archiv mit dem status eingestellt auf "started" und die streamMode eingestellt auf "manual". Jedes Objekt im Array enthält die folgenden Eigenschaften:
    • streamId — Die Stream-ID des im Archiv enthaltenen Streams.
    • hasAudio — Ob der Ton des Streams im Archiv enthalten ist.
    • hasVideo — Ob das Video des Streams im Archiv enthalten ist.

Die HTTP-Antwort weist in den folgenden Fällen den Statuscode 400 auf:

  • Sie geben keine Sitzungs-ID an oder Sie geben eine ungültige Sitzungs-ID an.
  • Derzeit sind keine Clients aktiv mit der OpenTok-Sitzung verbunden.
  • Sie geben einen ungültigen Wert an resolution Wert.
  • Die outputMode Eigenschaft wird auf "individual" und du legst die resolution Eigenschaft und (die in einzelnen Stream-Archiven nicht unterstützt wird).
  • Sie geben einen ungültigen Wert an maxBitrate Wert oder Sie geben einen maxBitrate Wert für ein einzelnes Stream-Archiv. (maxBitrate wird nur für zusammengesetzte Archive unterstützt.)
  • Sie geben einen ungültigen Wert an quantizationParameter Wert oder Sie geben einen quantizationParameter Wert für ein einzelnes Stream-Archiv. (quantizationParameter wird nur für zusammengesetzte Archive unterstützt.)
  • Sie geben sowohl ein maxBitrate und eine quantizationParameter Eigentum.

Die HTTP-Antwort enthält den Statuscode 403, wenn Sie einen ungültigen OpenTok-API-Schlüssel oder ein ungültiges JWT-Token übergeben.

Die HTTP-Antwort enthält den Statuscode 404, wenn die Sitzung nicht existiert oder wenn die Sitzung zwar existiert, aber keine Clients mit ihr verbunden sind.

Die HTTP-Antwort enthält den Statuscode 409, wenn Sie versuchen, ein Archiv für eine Sitzung zu erstellen, die nicht den OpenTok Media Router verwendet. Oder wenn Sie versuchen, ein Archiv für eine Sitzung zu erstellen, die bereits aufgezeichnet wird, ohne die multiArchiveTag Option. Oder wenn Sie versuchen, ein gleichzeitiges Archiv für eine Sitzung zu starten, ohne eine eindeutige multiArchiveTag Wert.

Die HTTP-Antwort enthält den Statuscode 500, der auf einen OpenTok-Serverfehler hinweist.

Beispiel

Das folgende Beispiel für eine Befehlszeile startet die Aufzeichnung eines Archivs für eine OpenTok-Sitzung:

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
  • Legen Sie den Wert für api_key mit Ihrem OpenTok-API-Schlüssel.
  • Legen Sie den Wert für json_web_token in ein JSON-Web-Token (siehe Authentifizierung).
  • Setzen Sie die session_id Wert für die Sitzungs-ID der OpenTok-Sitzung, die Sie archivieren möchten.
  • Setzen Sie die name Wert zum Archivnamen hinzufügen (dies ist optional).

Anhalten einer Archivaufzeichnung

Um die Aufzeichnung eines Archivs zu beenden, senden Sie eine HTTP-POST-Anfrage.

Archive stellen die Aufzeichnung nach 4 Stunden (14.400 Sekunden) ein, oder 60 Sekunden, nachdem sich der letzte Client von der Sitzung getrennt hat, oder 60 Minuten, nachdem der letzte Client die Veröffentlichung beendet hat. Allerdings, automatische Archive Die Aufzeichnung in mehreren aufeinanderfolgenden Dateien mit einer Länge von jeweils bis zu 4 Stunden fortsetzen. Weitere Informationen finden Sie unter Archivierungsdauer

Aufruf dieser Methode für automatische Archive hat keine Auswirkung. Bei automatischen Archiven wird die Aufzeichnung in mehreren aufeinanderfolgenden Dateien mit einer Länge von jeweils bis zu 4 Stunden (14.400 Sekunden) fortgesetzt, bis 60 Sekunden nach der Trennung des letzten Clients von der Sitzung oder 60 Minuten nach dem Ende der Stream-Übertragung des letzten Clients an die Sitzung.

HTTP-POST an das Archiv

Senden Sie eine HTTP-POST-Anfrage an die folgende URL:

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

Ersetzen Sie <api_key> mit Ihrem OpenTok-API-Schlüssel. Weitere Informationen finden Sie auf Ihrer Projektseite unter Video API-Konto.

Ersetzen Sie <archive_id> mit der Archiv-ID. Die Archiv-ID entnehmen Sie bitte der Antwort auf den API-Aufruf an Mit der Aufzeichnung des Archivs beginnen.

Anmerkung: Bisher wurde für diese REST-URL Folgendes verwendet: /partner (das inzwischen veraltet ist) anstelle von /project.

Eigenschaften des POST-Headers

API-Aufrufe müssen mithilfe eines benutzerdefinierten HTTP-Headers authentifiziert werden — X-OPENTOK-AUTH — zusammen mit einem JSON Web Token (JWT). Siehe Authentifizierung.

Antwort

Die Rohdaten der HTTP-Antwort mit dem Statuscode 200 sind eine JSON-kodierte Nachricht in folgender Form:

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

Das JSON-Objekt enthält die folgenden Eigenschaften:

  • createdAt — Der Zeitstempel für den Zeitpunkt, zu dem das Archiv mit der Aufzeichnung begonnen hat, ausgedrückt in Millisekunden seit der Unix-Epoche (1. Januar 1970, 00:00:00 UTC).
  • hasAudio — Gibt das Archiv Audiodaten auf (wahr) oder nicht (falsch)?
  • hasVideo — Gibt das Archiv Videos auf (wahr) oder nicht (falsch)?
  • id — Die eindeutige Archiv-ID.
  • multiArchiveTag — Die eindeutige Kennung für gleichzeitige Archive (sofern eine festgelegt wurde).
  • outputMode — Entweder "composed" oder "individual". Siehe Einzelne Streams und zusammengesetzte Archive.
  • projectId — Ihr OpenTok-API-Schlüssel.
  • resolution — Die Auflösung des Archivs (entweder „640x480“, „1280x720“, „1920x1080“, „480x640“, „720x1280“ oder „1080x1920“). Diese Eigenschaft wird nur für zusammengesetzte Archive festgelegt.
  • sessionId — Die Sitzungs-ID der archivierten OpenTok-Sitzung.
  • name — Der von Ihnen angegebene Name des Archivs (dies ist optional)
  • size — Wenn das Archiv angehalten wird (und noch nicht erstellt wurde), wird die Größe auf 0 gesetzt.
  • status - Diese ist eingestellt auf "stopped".
  • streamMode — Ob die im Archiv enthaltenen Streams automatisch ausgewählt werden ("auto", die Standardeinstellung) oder manuell ("manual").
  • streams — Ein Array von Objekten, die den derzeit archivierten Streams entsprechen. Dies wird nur für ein Archiv mit dem status eingestellt auf "started" und die streamMode eingestellt auf "manual". Jedes Objekt im Array enthält die folgenden Eigenschaften:
    • streamId — Die Stream-ID des im Archiv enthaltenen Streams.
    • hasAudio — Ob der Ton des Streams im Archiv enthalten ist.
    • hasVideo — Ob das Video des Streams im Archiv enthalten ist.

Die HTTP-Antwort enthält den Statuscode 400, wenn Sie keine Sitzungs-ID übergeben oder eine ungültige Sitzungs-ID übergeben.

Die HTTP-Antwort enthält den Statuscode 403, wenn Sie einen ungültigen OpenTok-API-Schlüssel oder ein ungültiges JWT-Token übergeben.

Die HTTP-Antwort enthält den Statuscode 404, wenn Sie eine ungültige Archiv-ID übergeben.

Die HTTP-Antwort enthält den Statuscode 409, wenn Sie versuchen, ein Archiv zu stoppen, das gerade nicht aufgezeichnet wird.

Die HTTP-Antwort enthält den Statuscode 500, der auf einen OpenTok-Serverfehler hinweist.

Beispiel

Das folgende Beispiel für eine Befehlszeile beendet die Aufzeichnung eines Archivs für eine OpenTok-Sitzung:

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
  • Legen Sie den Wert für api_key mit Ihrem OpenTok-API-Schlüssel.
  • Legen Sie den Wert für json_web_token in ein JSON-Web-Token (siehe Authentifizierung).
  • Setzen Sie die id Wert an die Archiv-ID. Die Archiv-ID können Sie der Antwort auf den API-Aufruf an Mit der Aufzeichnung des Archivs beginnen.

Archiv der Einträge

Um die Archive für Ihren API-Schlüssel aufzulisten – sowohl abgeschlossene als auch noch laufende –, senden Sie eine HTTP-GET-Anfrage.

Anmerkung: Archivdaten sind bis zu 12 Monate lang verfügbar.

HTTP-GET-Anfrage an das Archiv

Senden Sie eine HTTP-GET-Anfrage an die folgende URL:

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

Ersetzen Sie <api_key> mit Ihrem OpenTok-API-Schlüssel. Weitere Informationen finden Sie auf der Projektseite in Ihrem Video API-Konto.

Anmerkung: Bisher wurde für diese REST-URL Folgendes verwendet: /partner (das inzwischen veraltet ist) anstelle von /project.

Sie können Abfrageparameter hinzufügen, um die Ergebnisse zu filtern (diese sind optional):

  • Lege ein offset Abfrageparameter zur Angabe des Index-Offsets des ersten Archivs. 0 ist der Offset des zuletzt gestarteten Archivs (gelöschte Archive ausgenommen). 1 ist der Offset des Archivs, das vor dem zuletzt gestarteten Archiv begonnen hat. Der Standardwert ist 0.

  • Einstellen count Abfrageparameter zur Begrenzung der Anzahl der zurückzugebenden Archive. Standardmäßig werden 50 Archive zurückgegeben (oder weniger, falls weniger als 50 Archive vorhanden sind). Die maximale Anzahl der Archive, die der Aufruf zurückgibt, beträgt 1000.

  • Einstellen sessionId Abfrageparameter zum Auflisten von Archiven für eine bestimmte Sitzungs-ID. (Dies ist nützlich, wenn mehrere Archive für eine automatisch archiviert Sitzung.)

Der folgende Aufruf legt beispielsweise einen count und offset Werte:

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

Der folgende Aufruf legt einen (fiktiven) sessionId Wert:

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

Gelöschte Archive werden in den Ergebnissen dieses API-Aufrufs nicht berücksichtigt.

Ersetzen Sie <api_key> mit Ihrem OpenTok-API-Schlüssel. Weitere Informationen finden Sie auf der Projektseite in Ihrem Video API-Konto.

GET-Header-Eigenschaften

API-Aufrufe müssen mithilfe eines benutzerdefinierten HTTP-Headers authentifiziert werden — X-OPENTOK-AUTH — zusammen mit einem JSON Web Token (JWT). Siehe Authentifizierung.

Antwort

Die Rohdaten der HTTP-Antwort mit dem Statuscode 200 sind eine JSON-kodierte Nachricht in folgender Form:

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

Das JSON-Objekt enthält die folgenden Eigenschaften:

  • count — Die Gesamtzahl der Archive für den API-Schlüssel.
  • items — Ein Array von Objekten, die jedes abgerufene Archiv definieren. Die Archive werden in der Rückgabemenge vom neuesten zum ältesten aufgelistet.

Jedes Archivobjekt (Element) verfügt über die folgenden Eigenschaften:

  • createdAt — Der Zeitstempel für den Zeitpunkt, zu dem das Archiv mit der Aufzeichnung begonnen hat, ausgedrückt in Millisekunden seit der Unix-Epoche (1. Januar 1970, 00:00:00 UTC).
  • duration — Die Dauer des Archivs in Sekunden. Bei Archiven, die gerade aufgezeichnet werden (und bei denen die Eigenschaft „status“ auf „started“ gesetzt ist), wird dieser Wert auf 0 gesetzt.
  • hasAudio — Gibt das Archiv Audiodaten auf (wahr) oder nicht (falsch)?
  • hasVideo — Gibt das Archiv Videos auf (wahr) oder nicht (falsch)?
  • id — Die eindeutige Archiv-ID.
  • multiArchiveTag — Die eindeutige Kennung für gleichzeitige Archive (sofern eine festgelegt wurde).
  • name — Der von Ihnen angegebene Name des Archivs (dies ist optional)
  • outputMode — Entweder "composed" oder "individual". Siehe Einzelne Streams und zusammengesetzte Archive.
  • projectId — Ihr OpenTok-API-Schlüssel.
  • reason — Für Archive mit dem Status "stopped"kann dieser Wert auf "maximum duration exceeded", "maximum idle time exceeded", "session ended", "user initiated". Für Archive mit dem Status "failed"kann dieser Wert auf "failure".
  • sessionId — Die Sitzungs-ID der archivierten OpenTok-Sitzung.
  • status — Der Status des Archivs:

    • "available" — Das Archiv steht in der OpenTok-Cloud zum Download bereit.

    • "expired" — Das Archiv steht in der OpenTok-Cloud nicht mehr zum Herunterladen zur Verfügung.

    • "failed" — Die Archivierung ist fehlgeschlagen.

    • "paused" — Wenn ein Archiv angehalten wird, wird nichts aufgezeichnet. Das Archiv wird angehalten, wenn eine der folgenden Bedingungen eintritt:

      • Es gibt keine Clients, die Streams an die Sitzung senden. In diesem Fall gilt eine Zeitüberschreitung von 60 Minuten; danach wird die Archivierung beendet und der Archivierungsstatus ändert sich zu "stopped".
      • Alle Clients trennen die Verbindung zur Sitzung. Nach 60 Sekunden wird die Archivierung beendet und der Archivierungsstatus ändert sich zu "stopped".

      Wenn ein Client die Veröffentlichung fortsetzt, während sich das Archiv im Status „angepausiert“ befindet, wird die Archivaufzeichnung fortgesetzt und der Status ändert sich wieder zu "started".

    • "started" — Das Archiv wurde eingerichtet und wird derzeit erfasst.

    • "stopped" — Das Archiv hat die Aufzeichnung beendet.

    • "uploaded" — Das Archiv steht im S3-Bucket zum Download bereit, den Sie in Ihrer Video API-Konto.

  • streamMode — Ob die im Archiv enthaltenen Streams automatisch ausgewählt werden ("auto", die Standardeinstellung) oder manuell ("manual").
  • resolution — Die Auflösung des Archivs (entweder „640x480“, „1280x720“, „1920x1080“, „480x640“, „720x1280“ oder „1080x1920“). Diese Eigenschaft wird nur für zusammengesetzte Archive festgelegt.
  • size — Die Größe der Archivdatei. Bei noch nicht erstellten Archiven ist dieser Wert auf 0 gesetzt.
  • streamMode — Ob alle Streams im Archiv enthalten sind ("auto") oder Sie wählen die Streams aus, die in das Archiv aufgenommen werden sollen ("manual"). Siehe Auswahl der in ein Archiv aufzunehmenden Streams.
  • streams — Ein Array von Objekten, die den derzeit archivierten Streams entsprechen. Dies wird nur für ein Archiv mit dem status eingestellt auf "started" und die streamMode eingestellt auf "manual". Jedes Objekt im Array enthält die folgenden Eigenschaften:
    • streamId — Die Stream-ID des im Archiv enthaltenen Streams.
    • hasAudio — Ob der Ton des Streams im Archiv enthalten ist.
    • hasVideo — Ob das Video des Streams im Archiv enthalten ist.
  • url — Die Download-URL der verfügbaren Archivdatei. Diese wird nur für ein Archiv festgelegt, dessen Status auf "available"für andere Archive (einschließlich Archive mit dem Status "uploaded") Diese Eigenschaft ist auf „null“ gesetzt. Die Download-URL ist verschleiert, und die Datei ist nur 10 Minuten lang über diese URL verfügbar. Um eine neue URL zu generieren, verwenden Sie die REST-API für Abrufen von Archivinformationen oder Angebotsarchiv.

Die HTTP-Antwort enthält den Statuscode 403, wenn Sie einen ungültigen OpenTok-API-Schlüssel oder ein ungültiges JWT-Token übergeben.

Die HTTP-Antwort enthält den Statuscode 500, der auf einen OpenTok-Serverfehler hinweist.

Beispiel

Das folgende Beispiel für eine Befehlszeile ruft Informationen zu allen Archiven ab:

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
  • Legen Sie den Wert für api_key mit Ihrem OpenTok-API-Schlüssel.
  • Legen Sie den Wert für json_web_token in ein JSON-Web-Token (siehe Authentifizierung).

Abrufen von Archivinformationen

Um Informationen zu einem bestimmten Archiv abzurufen, senden Sie eine HTTP-GET-Anfrage.

Anmerkung: Archivdaten sind bis zu 12 Monate lang verfügbar.

Sie können auch Informationen zu mehreren Archiven abrufen. Siehe Archiv der Einträge.

HTTP-GET-Anfrage an das Archiv

Senden Sie eine HTTP-GET-Anfrage an die folgende URL:

https://api.opentok.com/v2/project/<api_key>/archive/<archive_id>
  • Ersetzen Sie <api_key> mit Ihrem OpenTok-API-Schlüssel. Weitere Informationen finden Sie auf der Projektseite Ihres Video API-Konto.
  • Ersetzen Sie <archive_id mit der Archiv-ID.

Anmerkung: Bisher wurde für diese REST-URL Folgendes verwendet: /partner (das inzwischen veraltet ist) anstelle von /project.

GET-Header-Eigenschaften

API-Aufrufe müssen mithilfe eines benutzerdefinierten HTTP-Headers authentifiziert werden — X-OPENTOK-AUTH — zusammen mit einem JSON Web Token (JWT). Siehe Authentifizierung.

Antwort

Die Rohdaten der HTTP-Antwort mit dem Statuscode 200 sind eine JSON-kodierte Nachricht in folgender Form:

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

Das JSON-Objekt enthält die folgenden Eigenschaften:

  • createdAt — Der Zeitstempel für den Zeitpunkt, zu dem das Archiv mit der Aufzeichnung begonnen hat, ausgedrückt in Millisekunden seit der Unix-Epoche (1. Januar 1970, 00:00:00 UTC).
  • duration — Die Dauer des Archivs in Sekunden. Bei Archiven, die gerade aufgezeichnet werden (und bei denen die Eigenschaft „status“ auf „started“ gesetzt ist), wird dieser Wert auf 0 gesetzt.
  • hasAudio — Gibt das Archiv Audiodaten auf (wahr) oder nicht (falsch)?
  • hasVideo — Gibt das Archiv Videos auf (wahr) oder nicht (falsch)?
  • id — Die eindeutige Archiv-ID.
  • multiArchiveTag — Die eindeutige Kennung für gleichzeitige Archive (sofern eine festgelegt wurde).
  • name — Der von Ihnen angegebene Name des Archivs (dies ist optional)
  • outputMode — Entweder "composed" oder "individual". Siehe Einzelne Streams und zusammengesetzte Archive.
  • projectId — Ihr OpenTok-API-Schlüssel.
  • reason — Für Archive mit dem Status "stopped"kann dieser Wert auf "maximum duration exceeded", "maximum idle time exceeded", "session ended", "user initiated". Für Archive mit dem Status "failed"kann dieser Wert auf "failure".
  • resolution — Die Auflösung des Archivs (entweder „640x480“, „1280x720“, „1920x1080“, „480x640“, „720x1280“ oder „1080x1920“). Diese Eigenschaft wird nur für zusammengesetzte Archive festgelegt.
  • sessionId — Die Sitzungs-ID der archivierten OpenTok-Sitzung.
  • status — Der Status des Archivs:

    • "available" — Das Archiv steht in der OpenTok-Cloud zum Download bereit.

    • "deleted" — Das Archiv wurde gelöscht.

    • "expired" — Das Archiv steht in der OpenTok-Cloud nicht mehr zum Herunterladen zur Verfügung.

    • "failed" — Die Archivierung ist fehlgeschlagen.

    • "paused" — Wenn ein Archiv angehalten wird, wird nichts aufgezeichnet. Das Archiv wird angehalten, wenn eine der folgenden Bedingungen eintritt:

      • Es gibt keine Clients, die Streams an die Sitzung senden. In diesem Fall gilt eine Zeitüberschreitung von 60 Minuten; danach wird die Archivierung beendet und der Archivierungsstatus ändert sich zu "stopped".
      • Alle Clients trennen die Verbindung zur Sitzung. Nach 60 Sekunden wird die Archivierung beendet und der Archivierungsstatus ändert sich zu "stopped".

      Wenn ein Client die Veröffentlichung wieder aufnimmt, während sich das Archiv im "paused" Zustand: Die Archivaufzeichnung wird fortgesetzt und der Status wechselt zurück zu "started".

    • "started" — Das Archiv wurde eingerichtet und wird derzeit erfasst.

    • "stopped" — Das Archiv hat die Aufzeichnung beendet.

    • "uploaded" — Das Archiv steht im S3-Bucket zum Download bereit, den Sie in Ihrer Video API-Konto.

  • size — Die Größe der Archivdatei. Bei noch nicht erstellten Archiven ist dieser Wert auf 0 gesetzt.
  • streamMode — Ob alle Streams im Archiv enthalten sind ("auto") oder Sie wählen die Streams aus, die in das Archiv aufgenommen werden sollen ("manual"). Siehe Auswahl der in ein Archiv aufzunehmenden Streams.
  • streams — Ein Array von Objekten, die den derzeit archivierten Streams entsprechen. Dies wird nur für ein Archiv gesetzt, dessen Status auf "started" und die streamMode eingestellt auf "manual". Jedes Objekt im Array enthält die folgenden Eigenschaften:
    • streamId — Die Stream-ID des im Archiv enthaltenen Streams.
    • hasAudio — Ob der Ton des Streams im Archiv enthalten ist.
    • hasVideo — Ob das Video des Streams im Archiv enthalten ist.
  • url — Die Download-URL der verfügbaren Archivdatei. Diese wird nur für ein Archiv festgelegt, dessen Status auf "available"für andere Archive (einschließlich Archive mit dem Status "uploaded") Diese Eigenschaft ist auf „null“ gesetzt. Die Download-URL ist verschleiert, und die Datei ist nur 10 Minuten lang über diese URL verfügbar. Um eine neue URL zu generieren, verwenden Sie die REST-API für Abrufen von Archivinformationen oder Angebotsarchiv.

Die HTTP-Antwort enthält den Statuscode 400, wenn Sie keine Sitzungs-ID übergeben oder eine ungültige Archiv-ID übergeben.

Die HTTP-Antwort enthält den Statuscode 403, wenn Sie einen ungültigen OpenTok-API-Schlüssel oder ein ungültiges JWT-Token übergeben.

Die HTTP-Antwort enthält den Statuscode 500, der auf einen OpenTok-Serverfehler hinweist.

Beispiel

Das folgende Beispiel für eine Befehlszeile ruft Informationen zu einem Archiv ab:

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
  • Legen Sie den Wert für api_key mit Ihrem OpenTok-API-Schlüssel.
  • Legen Sie den Wert für json_web_token in ein JSON-Web-Token (siehe Authentifizierung).
  • Setzen Sie die id Wert zur Archiv-ID hinzufügen.

Löschen eines Archivs

Um ein Archiv zu löschen, senden Sie eine HTTP-DELETE-Anfrage.

Sie können nur ein Archiv löschen, das den Status "available" oder "uploaded". Durch das Löschen eines Archivs wird dessen Eintrag aus der Liste der Archive entfernt (siehe Archiv der Einträge). Für eine "available" Archiv; dabei wird auch die Archivdatei gelöscht, sodass sie nicht mehr zum Herunterladen zur Verfügung steht.

HTTP-DELETE zum Archivieren

Senden Sie eine HTTP-DELETE-Anfrage an die folgende URL:

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

Ersetzen Sie <api_key> mit Ihrem OpenTok-API-Schlüssel. Weitere Informationen finden Sie auf der Projektseite Ihres Video API-Konto.

Ersetzen Sie <archive_id> mit der Archiv-ID.

Anmerkung: Bisher wurde für diese REST-URL Folgendes verwendet: /partner (das inzwischen veraltet ist) anstelle von /project.

DELETE-Header-Eigenschaften

API-Aufrufe müssen mithilfe eines benutzerdefinierten HTTP-Headers authentifiziert werden — X-OPENTOK-AUTH — zusammen mit einem JSON Web Token (JWT). Siehe Authentifizierung.

Antwort

Eine HTTP-Antwort mit dem Statuscode 204 zeigt an, dass das Archiv gelöscht wurde.

Die HTTP-Antwort enthält den Statuscode 403, wenn Sie einen ungültigen OpenTok-API-Schlüssel, ein ungültiges JWT-Token oder eine ungültige Archiv-ID übergeben.

Die HTTP-Antwort enthält den Statuscode 409, wenn der Status des Archivs nicht "uploaded", "available", oder "deleted".

Die HTTP-Antwort enthält den Statuscode 500, der auf einen OpenTok-Serverfehler hinweist.

Beispiel

Das folgende Beispiel für eine Befehlszeile löscht ein Archiv:

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
  • Legen Sie den Wert für api_key mit Ihrem OpenTok-API-Schlüssel.
  • Legen Sie den Wert für json_web_token in ein JSON-Web-Token (siehe Authentifizierung).
  • Setzen Sie die id Wert für die ID des zu löschenden Archivs.

Ein S3- oder Azure-Archivierungsziel für den Upload festlegen

Bei einem OpenTok-Projekt können Sie OpenTok damit beauftragen, fertige Archive in einen Amazon S3-Bucket (oder einen S3-kompatiblen Speicheranbieter) oder einen Windows Azure-Container hochzuladen.

Anmerkung: Sie können außerdem ein Ziel für den Archiv-Upload auf Ihrem Vonage Video API-Konto Seite.

Für Amazon S3 müssen Sie Vonage die Berechtigung zum Hochladen in den Amazon S3-Bucket erteilen. Wenn Sie einen S3-IAM-Benutzer verwenden möchten, weisen Sie diesem die folgende Benutzerrichtlinie zu:

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

Um ein Ziel für den Archiv-Upload festzulegen, senden Sie eine HTTP-PUT-Anfrage.

Wenn Sie ein Upload-Ziel festlegen, wird jede fertige Archivdatei als Datei mit dem Namen „archive.mp4“ in den Pfad /projectKey/archiveId/ des Ziel-Buckets, wobei projectKey ist der API-Schlüssel des Projekts, und archiveId ist die Archiv-ID.

Wenn Sie bereits ein Ziel für den Upload der Archivdateien eines Projekts festgelegt haben, können Sie eine weitere PUT-Anfrage senden, um ein neues Upload-Ziel zu registrieren.

Weitere Informationen zur Archivierung finden Sie in der Archivierungsprogrammierung Leitfaden.

HTTP-PUT an das Archiv

Senden Sie eine HTTP PUT-Anfrage an die folgende URL:

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

Ersetzen Sie <api_key> mit dem API-Schlüssel des OpenTok-Projekts.

PUT-Header-Eigenschaften

Authentifizieren Sie diesen API-Aufruf mithilfe eines benutzerdefinierten HTTP-Headers — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Setzen Sie diesen Header auf ein JWT-Token (siehe Authentifizierung).

Setzen Sie die Content-type Kopfzeile zu application/json:

Content-Type:application/json

PUT-Daten

Für einen Amazon S3-Bucket fügen Sie ein JSON-Objekt in der folgenden Form als PUT-Daten ein:

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

Das JSON-Objekt enthält die folgenden Eigenschaften:

  • type - "s3" (für Amazon S3)

  • config — Einstellungen für den Amazon Web Services-Account:

  • accessKey — Der Amazon Web Services-Zugriffsschlüssel

  • secretKey — Der geheime Schlüssel für Amazon Web Services

  • bucket — Der Name des S3-Buckets.

  • endpoint (optional) — Ein S3-Endpunkt. Dies ist optional. Der Standard- Endpunkt lautet http://s3.amazonaws.com (der Endpunkt für Amazon S3). Geben Sie diesen an, wenn Sie eine S3-kompatible Speicherlösung (außer Amazon S3) verwenden möchten. Legen Sie hier die Basis-URL des Endpunkts fest, einschließlich des Protokolls (http oder https), zum Beispiel "https://s3.cloudianhyperstore.com" oder "https://storage.googleapis.com". Wir unterstützen Cloudian und Google Cloud Storage (Zugriff über die AWS-S3-API) als S3-kompatible Speicherlösungen. Bei anderen S3-kompatiblen Diensten können Funktionseinschränkungen bestehen.

  • fallback — Stellen Sie dies auf "opentok" damit das Archiv im OpenTok-Dashboard verfügbar ist, falls der Upload fehlschlägt. Setzen Sie diese Option auf "none" (oder lassen Sie die Eigenschaft weg), um zu verhindern, dass Archivdateien in der OpenTok-Cloud gespeichert werden, falls der Upload fehlschlägt.

Bei einem Windows Azure-Container fügen Sie ein JSON-Objekt in der folgenden Form als PUT-Daten ein:

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

Das JSON-Objekt enthält die folgenden Eigenschaften:

  • type - "azure" (für Microsoft Azure)

  • config — Einstellungen für den Windows Azure-Account:

  • accountName — Der Name des Windows Azure-Accounts

  • accountKey — Der Windows Azure-Account-Schlüssel

  • container — Der Name des Windows Azure-Containers.

  • domain (optional) — Die Windows Azure-Domäne, in der sich der Container befindet.

  • fallback — Stellen Sie dies auf "opentok" damit das Archiv im OpenTok-Dashboard verfügbar ist, falls der Upload fehlschlägt. Setzen Sie diese Option auf "none" (oder lassen Sie die Eigenschaft weg) um zu verhindern, dass Archivdateien in der OpenTok-Cloud gespeichert werden, falls der Upload fehlschlägt.

HTTP-Antwort

Die HTTP-Antwort enthält einen der folgenden Statuscodes:

  • 200 – Erfolg. Der Antworttext stimmt mit den von Ihnen übermittelten Daten überein.

  • 400 – Ungültige Anfrage. Diese Antwort kann auf Folgendes hinweisen:

  • Der Typ ist nicht definiert.

  • Der Typ wird nicht unterstützt (er ist nicht "s3" oder "azure").

  • Die Konfiguration ist nicht definiert.

  • Der Konfigurationswert überschreitet die Größenbeschränkung. Wir verschlüsseln die Konfigurationseinstellung beim Speichern, und die verschlüsselte Größe darf maximal 2.048 Zeichen betragen.

  • Ihre Anfragedaten enthalten ungültiges JSON.

    • 403 – Authentifizierungsfehler. Sie haben ein ungültiges Token in der X-OPENTOK-AUTH Kopfzeile.

Beispiel

Das folgende Beispiel für eine Befehlszeile legt einen S3-Bucket für ein Projekt fest:

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

  • Legen Sie den Wert für token in ein gültiges OpenTok-JWT-Token.

  • Legen Sie den Wert für projectKey zum API-Schlüssel des Projekts.

  • Setzen Sie die storage_type Wert für "s3".

  • Setzen Sie die access_key Wert für den Zugriffsschlüssel Ihres Amazon Web Services- Accounts.

  • Setzen Sie die secret_key Wert für den geheimen Schlüssel Ihres Amazon Web Services- Accounts.

  • Setzen Sie die bucket Wert an den Bucket-Namen anhängen.

Ein Archivierungs-Upload-Ziel löschen

Wenn Sie für die Archivdateien eines Projekts ein Ziel für den Archiv-Upload festgelegt haben, können Sie dieses löschen.

Anmerkung: Sie können ein Ziel für den Archiv-Upload auch auf Ihrem Vonage Video API-Konto Seite.

HTTP-DELETE zum Archivieren

Senden Sie eine HTTP-DELETE-Anfrage an die folgende URL:

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

Ersetzen Sie <project_key> mit dem API-Schlüssel des Projekts.

DELETE-Header-Eigenschaften

Authentifizieren Sie diesen API-Aufruf mithilfe eines benutzerdefinierten HTTP-Headers – X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Setzen Sie diesen Header auf ein JWT-Token (siehe Authentifizierung).

Antwort

Die HTTP-Antwort enthält einen der folgenden Statuscodes:

  • 204 – Erfolg (kein Inhalt).

  • 403 – Authentifizierungsfehler. Sie haben im Header „X-OPENTOK-AUTH“ ein ungültiges Token übergeben.

  • 404 – Es gibt kein Ziel für den Upload.

### Beispiel

Das folgende Beispiel für eine Befehlszeile löscht ein Upload-Ziel für ein Projekt:

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

  • Legen Sie den Wert für token in ein gültiges OpenTok-JWT-Token.

  • Legen Sie den Wert für projectKey zum API-Schlüssel des Projekts.

Dynamische Änderung des Layouttyps eines zusammengesetzten Archivs

Sie können den Layouttyp eines zusammengesetzten Archivs während der Aufzeichnung dynamisch ändern.

Weitere Informationen zur zusammengesetzten Archivierung finden Sie im OpenTok-Entwicklerhandbuch zur Archivierung und Anpassen des Videolayouts für zusammengesetzte Archive.

HTTP-PUT an das Archiv

Senden Sie eine HTTP PUT-Anfrage an die folgende URL:

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

Ersetzen Sie <apiKey> mit Ihrem OpenTok-API-Schlüssel.

Ersetzen Sie <archiveId> mit der Archiv-ID.

PUT-Header-Eigenschaften

Setzen Sie die Content-Type Kopfzeile zu application/json.

Authentifizieren Sie diesen API-Aufruf mithilfe eines benutzerdefinierten HTTP-Headers — X-OPENTOK-AUTH — auf ein JSON-Web-Token gesetzt. Siehe Authentifizierung.

PUT-Daten

Fügen Sie ein JSON-Objekt in der folgenden Form als Inhalt des Request-Bodys ein:

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

Das JSON-Objekt enthält die folgenden Eigenschaften:

  • Typ (Zeichenkette) — Der Layouttyp für das Archiv. Gültige Werte sind "bestFit" (beste Übereinstimmung), "custom" (benutzerdefiniert), "horizontalPresentation" (horizontale Darstellung), "pip" (Bild-in-Bild) und "verticalPresentation" (vertikale Darstellung). Wenn Sie einen "custom" Layout-Typ, setzen Sie die stylesheet Eigenschaft im Stylesheet. (Bei anderen Layouttypen darf die stylesheet Eigenschaft.) Weitere Informationen finden Sie unter Anpassen des Videolayouts für zusammengestellte Archive.

    Wenn Sie einen anderen Layouttyp als „Best Fit“ festlegen, achten Sie darauf, die entsprechenden Layoutklassen für die Streams in der OpenTok-Sitzung anzuwenden (siehe Zuweisung von Layout-Klassen für Live-Streams zu OpenTok- Streams).

  • Stylesheet (Zeichenkette) — Optional. Geben Sie dies nur an, wenn Sie die type Eigenschaft zu "custom". Setzen Sie die stylesheet Eigenschaft zum Stylesheet hinzufügen. (Bei anderen Layouttypen darf die stylesheet Eigenschaft.) Weitere Informationen finden Sie unter Definieren benutzerdefinierter Layouts.

  • screenshareType (Zeichenkette) — Optional. Der Layouttyp, der verwendet werden soll, wenn in der Sitzung ein Bildschirmfreigabestream vorhanden ist. Beachten Sie, dass Sie zur Verwendung dieser Eigenschaft die type Eigenschaft auf "bestFit" und lassen Sie die stylesheet Eigenschaft nicht festgelegt. Weitere Informationen finden Sie unter Layout-Typen für die Bildschirmfreigabe.

Antwort

Die HTTP-Antwort enthält einen der folgenden Statuscodes:

  • 200 – Erfolg.
  • 400 – Ungültige Anfrage. Diese Antwort kann darauf hindeuten, dass die Daten in Ihrer Anfrage ungültiges JSON sind. Sie kann auch darauf hindeuten, dass Sie ungültige Layout-Optionen übergeben haben.
  • 403 – Authentifizierungsfehler.
  • 500 – OpenTok-Serverfehler.

Beispiel

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

Ändern der Layoutklassen für zusammengesetzte Archive bei einem OpenTok-Stream

Verwenden Sie diese Methode, um die Layout-Klassen für einen OpenTok-Stream zu ändern. Die Layout-Klassen legen fest, wie der Stream im Layout eines zusammengesetzten OpenTok-Archivs angezeigt wird. Weitere Informationen finden Sie unter Zuweisung von Layout-Klassen für Live-Streams zu OpenTok- Streams.

HTTP-PUT an den Stream

Senden Sie eine HTTP PUT-Anfrage an die folgende URL:

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

Ersetzen Sie <apiKey> mit Ihrem OpenTok-API-Schlüssel. Ersetzen Sie <sessionId> mit der Sitzungs-ID.

PUT-Header-Eigenschaften

Setzen Sie die Content-Type Kopfzeile zu application/json.

Authentifizieren Sie diesen API-Aufruf mithilfe eines benutzerdefinierten HTTP-Headers — X-OPENTOK-AUTH — auf ein JSON-Web-Token gesetzt. Siehe Authentifizierung.

PUT-Daten

Fügen Sie ein JSON-Objekt in der folgenden Form als Inhalt des Request-Bodys ein:

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

Das JSON-Objekt enthält ein items Objekt-Array. Jedes Objekt definiert die Layout-Klassen, die einem Stream zugewiesen werden sollen, und enthält folgende Eigenschaften:

  • id (Zeichenkette) — Die Stream-ID.
  • layoutClassList (Array) — Ein Array von Layout-Klassen (jeweils als Zeichenfolge) für den Stream.

Sie können die Liste der Layout-Klassen für mehrere Streams aktualisieren, indem Sie mehrere JSON-Objekte in der items Array.

Antwort

Die HTTP-Antwort enthält einen der folgenden Statuscodes:

  • 200 – Erfolg.
  • 400 – Ungültige Anfrage. Diese Antwort kann darauf hindeuten, dass die Daten in Ihrer Anfrage ungültiges JSON sind. Sie kann auch darauf hindeuten, dass Sie ungültige Layout-Optionen übergeben haben.
  • 403 – Authentifizierungsfehler.
  • 500 – OpenTok-Serverfehler.

Beispiel

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

Auswahl der in ein Archiv aufzunehmenden Streams

Verwenden Sie diese Methode, um die in einem zusammengesetzten Archiv enthaltenen Streams zu ändern, das mit dem Befehl streamMode eingestellt auf "manual" (siehe Starten einer Archivaufzeichnung).

Der Archiv-Generator fügt Streams hinzu, die auf folgenden Grundlagen basieren: Strompriorisierungsregeln.

HTTP-PATCH an „archive/streams“

Senden Sie eine HTTP-PATCH-Anfrage an die folgende URL:

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

Ersetzen Sie <apiKey> mit Ihrem OpenTok-API-Schlüssel. Ersetzen Sie <archiveId> mit der Archiv-ID.

Eigenschaften des PATCH-Headers

Setzen Sie die Content-Type Kopfzeile zu application/json.

Authentifizieren Sie diesen API-Aufruf mithilfe eines benutzerdefinierten HTTP-Headers — X-OPENTOK-AUTH — auf ein JSON-Web-Token gesetzt. Siehe Authentifizierung.

PATCH-Daten

Um einen Stream zum Archiv hinzuzufügen, fügen Sie ein JSON-Objekt in der folgenden Form als Inhalt des Request-Bodies ein:

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

Das JSON-Objekt enthält die folgenden Eigenschaften:

  • addStream (Zeichenkette) — Die Stream-ID.
  • hasAudio (Boolescher Wert, optional) — Gibt an, ob das zusammengesetzte Archiv den Audio-Stream enthalten soll (true, die Standardeinstellung) oder nicht (false).
  • hasVideo (Boolescher Wert, optional) — Gibt an, ob das zusammengesetzte Archiv das Videomaterial des Streams enthalten soll (true, die Standardeinstellung) oder nicht (false).

Sie können die Methode wiederholt aufrufen mit addStream auf dieselbe Stream-ID setzen, um die Audio- oder Videoausgabe des Streams im Archiv umzuschalten.

Wenn Sie beides einstellen hasAudio und hasVideo zu false, erhalten Sie eine Fehlermeldung.

Um zu verhindern, dass ein Stream in das Archiv aufgenommen wird, fügen Sie ein JSON-Objekt in der folgenden Form als Inhalt des Request-Bodys ein:

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

Setzen Sie die removeStream Eigenschaft der Stream-ID.

Antwort

Die HTTP-Antwort enthält einen der folgenden Statuscodes:

  • 204 – Erfolg (kein Inhalt).
  • 400 – Ungültige Anfrage. Diese Antwort kann darauf hinweisen, dass die in Ihrer Anfrage angegebenen Daten ein ungültiges JSON sind oder dass die Anfrage nicht bearbeitet werden konnte, da das Archiv gestartet wurde mit streamMode eingestellt auf "auto", das keine Stream-Bearbeitung unterstützt.
  • 403 – Authentifizierungsfehler.
  • 404 – Archiv oder Stream nicht gefunden.
  • 500 – OpenTok-Serverfehler.

Beispiele

Einen Stream zu einem Archiv hinzufügen:

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

Das Video eines Streams aus einem Archiv entfernen (den Ton jedoch beibehalten):

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

Einen Stream aus einem Archiv entfernen:

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

Einleiten eines SIP-Anrufs

Um Ihre SIP-Plattform mit einer OpenTok-Sitzung zu verbinden, senden Sie eine HTTP-POST-Anfrage an die dial Methode. Der Ton von Ihrer Seite des SIP-Anrufs wird der OpenTok-Sitzung als reiner Audio-Stream hinzugefügt. Der OpenTok Media Router mischt den Ton mit dem aus anderen Streams in der Sitzung und sendet den gemischten Ton an Ihren SIP-Endpunkt.

Der Anruf wird beendet, wenn Ihr SIP-Server eine BYE Meldung (zum Beenden des Anrufs). Sie können einen Anruf auch mithilfe der OpenTok-REST-API-Methode beenden, um einen Client von einer Sitzung trennen. Das OpenTok-SIP-Gateway beendet einen Anruf automatisch nach 5 Minuten Inaktivität (5 Minuten ohne empfangene Medien). Außerdem beendet das OpenTok-SIP-Gateway aus Sicherheitsgründen jeden SIP-Anruf, der länger als 6 Stunden dauert.

Für die SIP-Verbindungsfunktion müssen Sie eine OpenTok-Sitzung verwenden, die das OpenTok Media Router (eine Sitzung, bei der der Medienmodus auf „geroutet“ eingestellt ist).

Weitere Informationen, einschließlich technischer Details und Sicherheitsüberlegungen, finden Sie in der OpenTok SIP-Anbindung Leitfaden für Entwickler.

HTTP-POST-Anfrage an „dial“

Senden Sie eine HTTP-POST-Anfrage an die folgende URL:

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

Ersetzen Sie <api_key> mit Ihrem OpenTok-API-Schlüssel. Weitere Informationen finden Sie auf der Projektseite Ihres Video API-Konto.

Anmerkung: Bisher wurde für diese REST-URL Folgendes verwendet: /partner (das inzwischen veraltet ist) anstelle von /project.

Eigenschaften des POST-Headers

API-Aufrufe müssen mithilfe eines benutzerdefinierten HTTP-Headers authentifiziert werden — X-OPENTOK-AUTH — zusammen mit einem JSON Web Token (JWT). Siehe Authentifizierung.

Setzen Sie den „Content-Type“-Header auf „application/json“:

Content-Type:application/json

POST-Daten

Fügen Sie ein JSON-Objekt in der folgenden Form als POST-Daten ein:

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

Das JSON-Objekt enthält die folgenden Eigenschaften:

  • sessionId​ (erforderlich) — Die OpenTok-Sitzungs-ID für den SIP-Anruf, an dem teilgenommen werden soll.
  • token​ (erforderlich) — Das OpenTok-Token, das für den angerufenen Teilnehmer verwendet werden soll. Sie können ein Token hinzufügen data um festzustellen, ob sich der Teilnehmer an einem SIP-Endpunkt befindet, oder um andere identifizierende Daten wie beispielsweise Telefonnummern zu ermitteln. (Die OpenTok-Client-Bibliotheken enthalten Eigenschaften zur Überprüfung der Verbindungsdaten eines mit einer Sitzung verbundenen Clients.) Siehe die Token-Erstellung Leitfaden für Entwickler.

  • SIP uri​ ​(erforderlich) — Die SIP-URI, die als Ziel des von OpenTok an Ihre SIP-Plattform initiierten SIP-Anrufs verwendet werden soll.

    Wenn das SIP ​uri​ enthält ein ​transport=tls​ Header: Die Aushandlung zwischen Vonage und dem SIP-Endpunkt erfolgt sicher. Beachten Sie, dass dies nur für die Aushandlung selbst gilt, nicht jedoch für die Audioübertragung. Wenn Sie auch die Audioübertragung verschlüsseln möchten, setzen Sie den ​secure​ Eigenschaft von ​true​.

    Dies ist ein Beispiel für eine sichere Anrufaushandlung:

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

    Dies ist ein Beispiel für eine unsichere Anrufaushandlung:

    "sip:user@sip.partner.com"

  • from ​(optional): Die Nummer oder Zeichenfolge, die als Anrufer an die endgültige SIP-Nummer gesendet wird. Es muss sich um eine Zeichenfolge im Format from@example.com, wobei from kann eine Zeichenkette sein, die aus Buchstaben (a–z, A–Z, 0–9) oder den Zeichen _, +, !, %, `, ', ~, oder -.

    Wenn from auf eine Zahl gesetzt wird (zum Beispiel, "<14155550101@example.com>"), wird sie auf Festnetztelefonen als anrufende Nummer angezeigt. Wenn from ist nicht definiert oder auf eine Zeichenkette gesetzt (zum Beispiel, "<joe@example.com>"), wird +00000000 auf PSTN-Telefonen als eingehende Nummer angezeigt.

    Wenn from undefiniert ist oder auf eine Zeichenkette gesetzt ist (zum Beispiel, "<joe@example.com>"), d. h. eine unbekannte oder nicht autorisierte Nummer, wird diese in den meisten Fällen umgewandelt in "Unknown" bevor die Anfrage von SIP-Anbietern an einen Netzbetreiber zur Terminierung im Festnetz weitergeleitet wird. Je nach Anbieter, "Unknown" wird auf PSTN-Telefonen als eingehende Nummer angezeigt. In einigen Fällen können Anbieter diese Anrufe aus Sicherheitsgründen zurückweisen, um Probleme wie Nummernfälschung zu vermeiden. Falls der Anruf von den Anbietern nicht zurückgewiesen wird, wird +00000000 auf PSTN-Telefonen als eingehende Nummer angezeigt.

    Eine Nummer gilt als nicht erkannt, wenn sie nicht dem E.164-Standard entspricht oder keine Vonage virtuelle Nummer Wenn eine Verbindung zum Vonage Voice API, zum Beispiel.

  • SIP headers​​ (optional) — Dieses Objekt definiert benutzerdefinierte Header, die dem SIP-Request hinzugefügt werden sollen ​INVITE​ Anfrage, die von OpenTok an Ihre SIP-Plattform gesendet wird.

  • SIP auth​ (optional) — Dieses Objekt enthält den Benutzernamen und das Passwort, die im SIP verwendet werden sollen INVITE​ Anfrage für die HTTP-Digest-Authentifizierung, wenn dies von Ihrer SIP-Plattform verlangt wird.

  • secure​ (optional) — Ein boolescher Schalter, der angibt, ob die Medien verschlüsselt übertragen werden müssen (​true​) oder nicht (​false​(die Standardeinstellung).

  • video (optional) — Ein boolescher Flag, der angibt, ob der SIP-Anruf Video enthält (​true​) oder nicht (​false​(Standard). Wenn Video enthalten ist, wird das Video des SIP-Clients in den OpenTok-Stream eingebunden, der an die OpenTok-Sitzung gesendet wird. SIP-Video ist auf 480p bei 800 kbps begrenzt. Der SIP-Client erhält ein einziges zusammengesetztes Video aus den veröffentlichten Streams in der OpenTok-Sitzung.

  • observeForceMute (optional) Ein boolescher Flag, der angibt, ob der SIP-Endpunkt Stummschaltung der Moderation erzwingen (true) oder nicht (false(die Standardeinstellung). Auch mit observeForceMute eingestellt auf true, kann der Anrufer „*6“ drücken, um die Stummschaltung des übertragenen Tons aufzuheben bzw. zu aktivieren. Damit die Stummschaltung per „*6“ funktioniert, muss der SIP-Anrufer RFC2833-DTMFs (RFC2833/RFC4733-Ziffern) aushandeln. Die Stummschaltfunktion wird bei SIP-INFO oder In-Band-DTMFs nicht unterstützt. Dem Anrufer wird eine Ansage (auf Englisch) vorgespielt, wenn er die Stummschaltung aktiviert oder aufhebt oder wenn der SIP-Client durch eine erzwungene Stummschaltung stummgeschaltet wird.

  • streams (optional) — Ein Array mit Stream-IDs für Streams, die in den SIP-Anruf einbezogen werden sollen. Wenn Sie diese Eigenschaft nicht festlegen, werden alle Streams der Sitzung in den Anruf einbezogen.

Antwort

Die Rohdaten der HTTP-Antwort mit dem Statuscode 200 sind eine JSON-kodierte Nachricht in folgender Form:

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

Das JSON-Objekt enthält die folgenden Eigenschaften:

  • id - Eine eindeutige ID für den SIP-Anruf.
  • connectionId — Die OpenTok-Verbindungs-ID für die SIP-Verbindung innerhalb der OpenTok-Sitzung. Mit dieser Verbindungs-ID können Sie den SIP-Anruf über die OpenTok-REST-API beenden.
  • streamId — Die OpenTok-Stream-ID für den Stream des SIP-Anrufs in der OpenTok-Sitzung.

Die HTTP-Antwort weist in den folgenden Fällen den Statuscode 400 auf:

  • Sie geben keine Sitzungs-ID an oder Sie geben eine ungültige Sitzungs-ID an.

Die HTTP-Antwort enthält den Statuscode 403, wenn Sie einen ungültigen OpenTok-API-Schlüssel oder ein ungültiges JSON-Web-Token übergeben.

Die HTTP-Antwort enthält den Statuscode 404, wenn die Sitzung nicht existiert.

Die HTTP-Antwort enthält den Statuscode 409, wenn Sie versuchen, einen SIP-Anruf für eine Sitzung zu starten, die nicht den OpenTok Media Router nutzt.

Die HTTP-Antwort enthält den Statuscode 500, der auf einen OpenTok-Serverfehler hinweist.

Beispiel

Das folgende Beispiel für eine Befehlszeile verbindet Ihren SIP-Endpunkt mit einer OpenTok-Sitzung:

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
  • Legen Sie den Wert für api_key mit Ihrem OpenTok-API-Schlüssel.
  • Legen Sie den Wert für json_web_token in ein JSON-Web-Token (siehe Authentifizierung).
  • Setzen Sie die session_id Wert für die Sitzungs-ID der OpenTok-Sitzung, die Sie mit Ihrer SIP-Plattform verbinden möchten.
  • Setzen Sie die sip_uri Wert für die SIP-URI Ihres SIP-Endpunkts.
  • Setzen Sie die token Eigenschaft der data JSON in ein gültiges OpenTok-Verbindungstoken für den angerufenen Teilnehmer (siehe die Token-Erstellung Entwicklerhandbuch).
  • Setzen Sie die username und password Eigenschaften der data JSON mit dem Benutzernamen und dem Passwort für Ihren SIP-Endpunkt. (Dies ist optional.)

Senden von DTMF-Ziffern an SIP-Clients

Verwenden Sie die „play-dtmf“-REST-API, um DTMF-Ziffern an alle Teilnehmer einer aktiven OpenTok-Sitzung oder an einen bestimmten, mit dieser Sitzung verbundenen Client zu senden.

Telefonie-Ereignisse werden über SDP ausgehandelt und als RFC4733/RFC2833-Digits an den entfernten Endpunkt übertragen.

DTMF-Ziffern an alle mit der Sitzung verbundenen Clients senden

Senden Sie eine HTTP-POST-Anfrage an die folgende URL:

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

Ersetzen Sie <api_key> mit Ihrem OpenTok-API-Schlüssel. Weitere Informationen finden Sie auf der Projektseite Ihres Video API-Konto. Ersetzen Sie <session_id> mit der Sitzungs-ID der Sitzung, an die Sie das DTMF-Signal senden.

Die DTMF-Nachricht wird von Clients ignoriert, die DTMF nicht unterstützen (z. B. Nicht-SIP-Clients).

Eigenschaften des POST-Headers

API-Aufrufe müssen mithilfe eines benutzerdefinierten HTTP-Headers – X-OPENTOK-AUTH – sowie eines JSON-Web-Tokens (JWT) authentifiziert werden. Siehe Authentifizierung.

Setzen Sie die Content-type Kopfzeile zu application/json:

Content-Type:application/json

POST-Daten

Fügen Sie ein JSON-Objekt in der folgenden Form als POST-Daten ein:

{ "digits": "1713" }

Das JSON-Objekt enthält ein digits Eigenschaft. Dies ist die Zeichenfolge der zu sendenden DTMF-Ziffern. Diese kann Folgendes enthalten: 0-9, „*“, „#“ und „p“. A p bedeutet eine Pause von 500 ms (falls Sie eine Verzögerung beim Senden der Ziffern einfügen müssen).

Antwort

Bei einem erfolgreichen Aufruf enthält die Antwort den HTTP-Statuscode 200.

Im Falle von Fehlern enthält die Antwort einen der folgenden HTTP-Statuscodes:

  • 400 — Eine der Immobilien — digits oder sessionId — ist ungültig.

  • 403 — Authentifizierungsfehler. Dieser kann auftreten, wenn Sie einen ungültigen OpenTok-API-Schlüssel oder ein ungültiges JSON-Web-Token verwenden

  • 404 — Die angegebene Sitzung existiert nicht.

Im Fehlerfall besteht der Antworttext aus JSON mit einem code und message Eigentum:

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

Beispiel

Der folgende Code sendet eine HTTP-POST-Anfrage an die play-dtmf Ressource der Sitzung:

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

DTMF-Töne an einen bestimmten, mit der Sitzung verbundenen Client senden

Senden Sie eine HTTP-POST-Anfrage an die folgende URL:

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

Ersetzen Sie <api_key> mit Ihrem OpenTok-API-Schlüssel. Weitere Informationen finden Sie auf der Projektseite Ihres Video API-Konto. Ersetzen Sie <session_id> mit der Sitzungs- ID der Sitzung, an die Sie das DTMF-Signal senden. Ersetzen Sie <connection_id> mit der Verbindungs-ID des Clients, an den Sie das DTMF-Signal senden.

Die Verbindungs-ID eines SIP-Clients können Sie der Antwort auf den REST-API-Aufruf an den SIP-Anruf einleiten.

Wenn Sie DTMF-Ziffern an einen Client senden, der DTMF nicht unterstützt (z. B. einen Nicht-SIP-Client), ignoriert der Client die Anfrage.

Eigenschaften des POST-Headers

API-Aufrufe müssen mithilfe eines benutzerdefinierten HTTP-Headers – X-OPENTOK-AUTH – sowie eines JSON-Web-Tokens (JWT) authentifiziert werden. Siehe Authentifizierung.

Setzen Sie die Content-type Kopfzeile zu application/json:

Content-Type:application/json

POST-Daten

Fügen Sie ein JSON-Objekt in der folgenden Form als POST-Daten ein:

{ "digits": "1713" }

Das JSON-Objekt enthält ein digits Eigenschaft. Dies ist die Zeichenfolge der zu sendenden DTMF-Ziffern. Diese kann Folgendes enthalten: 0-9, „*“, „#“ und „p“. A p bedeutet eine Pause von 500 ms (falls Sie eine Verzögerung beim Senden der Ziffern einfügen müssen).

Antwort

Bei einem erfolgreichen Aufruf enthält die Antwort den HTTP-Statuscode 200.

Im Falle von Fehlern enthält die Antwort einen der folgenden HTTP-Statuscodes:

  • 400 — Eine der Immobilien — digits oder sessionId — ist ungültig.

  • 403 — Authentifizierungsfehler. Dieser kann auftreten, wenn Sie einen ungültigen OpenTok-API-Schlüssel oder ein ungültiges JSON-Web-Token verwenden

  • 404 — Die angegebene Sitzung existiert nicht oder der durch das connectionId Die Eigenschaft ist nicht mit der Sitzung verknüpft.

Im Fehlerfall besteht der Antworttext aus JSON mit einem code und message Eigentum:

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

Beispiel

Sende einen HTTP-POST-Request an die play-dtmf Ressource mit einer bestimmten Verbindungs-ID, die zur Sitzung gehört:

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

Eine Live-Streaming-Übertragung starten

Verwenden Sie diese Methode, um eine Live-Streaming-Übertragung für eine OpenTok-Sitzung zu starten. Dadurch wird die Sitzung als HLS-Stream (HTTP Live Streaming) oder als RTMP-Stream übertragen.

Um die Übertragung einer Sitzung erfolgreich zu starten, muss mindestens ein Client mit der Sitzung verbunden sein.

Die Live-Streaming-Übertragung kann pro Sitzung auf einen HLS-Endpunkt und bis zu fünf RTMP-Server gleichzeitig ausgerichtet sein. Sie können Live-Streaming nur für Sitzungen starten, die den OpenTok Media Router verwenden (wobei der Medienmodus auf „routed“ eingestellt ist); bei Sitzungen, bei denen der Medienmodus auf „relayed“ eingestellt ist, können Sie Live-Streaming nicht nutzen. (Siehe Der OpenTok Media Router und die Medienmodi.)

Weitere Informationen zum Live-Streaming mit OpenTok finden Sie unter Leitfaden für Entwickler im Bereich Rundfunk.

HTTP-POST zur Übertragung

Senden Sie eine HTTP-POST-Anfrage an die folgende URL:

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

Ersetzen Sie <apiKey> mit Ihrem OpenTok-API-Schlüssel.

Anmerkung: Bisher wurde für diese REST-URL Folgendes verwendet: /partner (das inzwischen veraltet ist) anstelle von /project.

Eigenschaften des POST-Headers

Setzen Sie die Content-Type Kopfzeile zu application/json.

Authentifizieren Sie diesen API-Aufruf mithilfe eines benutzerdefinierten HTTP-Headers — X-OPENTOK-AUTH — auf ein JSON-Web-Token gesetzt. Siehe Authentifizierung.

POST-Daten

Fügen Sie ein JSON-Objekt in der folgenden Form als Inhalt des Request-Bodys ein:

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

Das JSON-Objekt enthält die folgenden Eigenschaften:

  • sessionId (Zeichenkette) — Geben Sie hier die Sitzungs-ID der OpenTok-Sitzung ein, die Sie übertragen möchten.

  • hasAudio (Boolescher Wert) — (Optional) Gibt an, ob die Übertragung Audio enthält (true, Standard) oder nicht (false). Wenn Sie beide festlegen hasAudio und hasVideo auf „false“ gesetzt ist, führt der Aufruf dieser Methode zu einem Fehler.

  • hasVideo (Boolescher Wert) — (Optional) Gibt an, ob die Übertragung Video enthält (true, Standard) oder nicht (false). Wenn Sie beide festlegen hasAudio und hasVideo auf „false“ gesetzt ist, führt der Aufruf dieser Methode zu einem Fehler.

    Anmerkung: bei der Einstellung hasVideo Wird der Wert auf „false“ gesetzt, enthält die Übertragung in RTMP-Streams Videobilder mit schwarzen Frames im Format 160×120. Einige Endpunkte, wie beispielsweise YouTube und Facebook, lehnen reine Audio-RTMP-Streams ab.

  • layout (Objekt) — Optional. Geben Sie dies an, um den anfänglichen Layouttyp für die Übertragung festzulegen. Dieses Objekt verfügt über drei Eigenschaften: type, stylesheetund screenshareType, die jeweils Zeichenfolgen sind. Gültige Werte für die layout Eigenschaften sind "bestFit" (beste Anpassung), "custom" (Gewohnheit), "horizontalPresentation" (horizontale Darstellung), "pip" (Bild-in-Bild), und "verticalPresentation" (vertikale Darstellung)). Wenn Sie einen "custom" Layout-Typ, setzen Sie die stylesheet Eigenschaft der layout dem Stylesheet hinzufügen. (Bei anderen Layouttypen darf kein stylesheet Eigenschaft.) Legen Sie die screenshareType Eigenschaft für den Layout-Typ, der verwendet werden soll, wenn in der Sitzung ein Bildschirmfreigabe-Stream vorliegt. (Diese Eigenschaft ist optional.) Hinweis: Wenn Sie die screenshareType Eigenschaft, müssen Sie die type Eigenschaft auf "bestFit" und lassen Sie die stylesheet Eigenschaft nicht festgelegt. Wenn Sie keinen anfänglichen Layouttyp angeben, verwendet der Broadcast-Stream den Layouttyp „Best Fit“. Weitere Informationen finden Sie unter Konfigurieren des Video-Layouts für die OpenTok-Live-Streaming-Funktion.

  • multiBroadcastTag (Zeichenkette) — (Optional) Legen Sie diesen Wert fest, um mehrere gleichzeitige Übertragungen für dieselbe Sitzung zu unterstützen. Verwenden Sie für jede gleichzeitige Übertragung einer laufenden Sitzung eine eindeutige Zeichenkette. Siehe Gleichzeitige Sendungen.

  • maxBitrate (optional) — Die maximale Bitrate für den/die Broadcast-Stream(s) in Bit pro Sekunde. Der Mindestwert beträgt 100.000, der Höchstwert 6.000.000.

  • maxDuration (Ganzzahl) — Optional. Die maximale Dauer der Übertragung in Sekunden. Die Übertragung wird automatisch beendet, sobald die maximale Dauer erreicht ist. Sie können die maximale Dauer auf einen Wert zwischen 60 (60 Sekunden) und 36.000 (10 Stunden) festlegen. Die standardmäßige maximale Dauer beträgt 4 Stunden (14.400 Sekunden).

  • outputs (Objekt) — Erforderlich. Dieses Objekt definiert die Arten von Übertragungsströmen, die Sie starten möchten (sowohl HLS als auch RTMP). Sie können HLS, RTMP oder beides als Übertragungsströme einbeziehen. Wenn Sie RTMP-Streaming einbeziehen, können Sie bis zu fünf RTMP-Zielströme (oder auch nur einen) angeben.

    Geben Sie für jeden RTMP-Stream Folgendes an: serverUrl (die URL des RTMP-Servers), streamName (den Stream-Namen, z. B. den Namen des YouTube-Live-Streams oder den Facebook-Stream-Schlüssel) sowie (optional) id (eine eindeutige ID für den Stream). Achten Sie darauf, den Port für den serverUrl, wie in "rtmps://myfooserver:443/myfooapp" (anstelle von "rtmps://myfooserver/myfooapp"). Wenn Sie eine ID angeben, wird diese in die Antwort des REST-Aufrufs aufgenommen und die REST-Methode zum Abrufen von Informationen zu einer Live-Streaming-Übertragung. Vonage überträgt die Sitzung an jede von Ihnen angegebene RTMP-URL. Beachten Sie, dass OpenTok-Live-Streaming sowohl RTMP als auch RTMPS unterstützt.

    Für HLS fügen Sie eine einzige hls Eigenschaft in der outputs Objekt. Dieses Objekt enthält die folgenden optionalen Eigenschaften:

    • dvr (Boolesch) — Ob aktiviert werden soll DVR-Funktionalität — Zurückspulen, Anhalten und Fortsetzen — in Abspielprogrammen, die diese Funktionen unterstützen (true), oder auch nicht (false(Standard). Bei aktiviertem DVR enthält die HLS-URL einen ?DVR Abfragezeichenfolge an das Ende angehängt.
    • lowLatency (Boolesch) — Ob aktiviert werden soll Low-Latency-Modus für den HLSstream. Einige HLS-Player unterstützen den Low-Latency-Modus nicht. Diese Funktion ist mit HLS-Übertragungen im DVR-Modus nicht kompatibel.

    Die HLS-URL wird in der Antwort sowie in der REST-Methode zum Abrufen von Informationen zu einer Live-Streaming-Übertragung zurückgegeben.

  • resolution (Zeichenkette) — Die Auflösung der Übertragung: entweder "640x480" (SD-Querformat, Standardeinstellung), "1280x720" (HD Querformat), "1920x1080" (FHD im Querformat), "480x640" (SD-Porträt), "720x1280" (HD-Hochformat) oder "1080x1920" (FHD im Hochformat). Für Sendungen, die Videostreams von Mobilgeräten enthalten (die häufig das Hochformat verwenden), empfiehlt es sich, ein Hochformat zu verwenden. Diese Eigenschaft ist optional.

  • streamMode (Zeichenkette) — (Optional) Gibt an, ob die in der Übertragung enthaltenen Streams automatisch ausgewählt werden ("auto", die Standardeinstellung) oder manuell ("manual"). Wenn Streams automatisch ausgewählt werden ("auto"), können alle Streams der Sitzung in die Übertragung einbezogen werden. Wenn Streams manuell ausgewählt werden ("manual"), legen Sie anhand von Aufrufen von diese REST-Methode. Sie können festlegen, ob Audio, Video oder beides eines Streams in die Übertragung einbezogen werden sollen. Sowohl im automatischen als auch im manuellen Modus bezieht der Übertragungs-Editor Streams auf der Grundlage von Strompriorisierungsregeln.

Wenn Sie nur eine RTMP-URL unterstützen müssen, können Sie ein Objekt (anstelle eines Arrays von Objekten) für die rtmp Der Wert des Attributs in den POST-Daten, die Sie beim Aufruf der REST-Methode übermitteln. Die folgenden POST-Daten geben beispielsweise eine RTMP-Ausgabe-URL an (und enthalten keine HLS-Ausgabe):

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

Antwort

Die Rohdaten der HTTP-Antwort mit dem Statuscode 200 sind eine JSON-kodierte Nachricht in folgender Form:

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

Das JSON-Objekt enthält die folgenden Eigenschaften:

  • id — Die eindeutige ID für die Übertragung
  • sessionId — Die OpenTok-Sitzungs-ID
  • projectId — Ihr OpenTok-API-Schlüssel
  • createdAt — Der Zeitpunkt des Sendebeginns, ausgedrückt in Millisekunden seit der Unix-Epoche (1. Januar 1970, 00:00:00 UTC)
  • updatedAt — Bei dieser Startmethode stimmt dieser Zeitstempel mit dem „createdAt“-Zeitstempel überein.
  • resolution — Die Auflösung der Übertragung (entweder „640x480“, „1280x720“, „1920x1080“, „480x640“, „720x1280“ oder „1920x1080“).
  • status - Diese ist eingestellt auf "started".
  • streamMode - ob alle Streams in die Übertragung einbezogen werden ("auto") oder Sie wählen Streams aus, die in die Übertragung einbezogen werden sollen ("manual").
  • streams - Ein Array von Objekten, die den Streams entsprechen, die gerade übertragen werden. Dies wird nur für eine Übertragung mit der Option status eingestellt auf "started" und die streamMode eingestellt auf "manual". Jedes Objekt im Array enthält die folgenden Eigenschaften:
    • streamId - Die Stream-ID des in der Übertragung enthaltenen Streams.
    • hasAudio - Ob der Ton des Streams in der Übertragung enthalten ist.
    • hasVideo - Ob das Video des Streams in der Sendung enthalten ist.
  • maxDuration — Die maximale Dauer der Übertragung (sofern festgelegt) in Sekunden.
  • multiBroadcastTag - Der eindeutige Tag für gleichzeitige Übertragungen (falls einer festgelegt wurde).
  • broadcastUrls — Ein Objekt, das Details zu den HLS- und RTMP-Übertragungen enthält.

Wenn Sie einen HLS-Endpunkt angegeben haben, enthält das Objekt ein hls Eigenschaft und eine hlsStatus Eigenschaft. Die hls Die Eigenschaft ist auf die URL für die HLS-Übertragung gesetzt. Beachten Sie, dass diese HLS-Übertragungs-URL auf eine Indexdatei verweist, eine Wiedergabeliste im .M3U8-Format, die eine Liste von URLs zu .ts-Mediensegmentdateien (MPEG-2-Transportstromdateien) enthält. Zwar werden die URLs sowohl der Playlist-Indexdatei als auch der Mediensegmentdateien sofort nach Rückgabe der HTTP-Antwort bereitgestellt, doch sollte der Zugriff auf diese URLs erst 15 bis 20 Sekunden später, nach dem Start der HLS-Übertragung, erfolgen, da zwischen der HLS-Übertragung und den Live-Streams in der OpenTok-Sitzung eine Verzögerung besteht. Siehe https://developer.apple.com/library/ios/technotes/tn2288/_index.html Weitere Informationen zur Playlist-Indexdatei und zu den Mediensegmentdateien für HLS. Die hlsStatus auf eine der folgenden Eigenschaften eingestellt ist:

  • "connecting" — Der OpenTok-Server ist gerade dabei, die Transcoder zu starten. Dies ist der Ausgangszustand.
  • "ready" — Der OpenTok-Server wurde erfolgreich initialisiert, aber das CDN ruft keine Medien ab.
  • "live" — Der OpenTok-Server wurde erfolgreich initialisiert, und das CDN ruft Medien ab.
  • "ended" - Der Quellstream wurde beendet. Wenn DVR aktiviert ist und voraufgezeichnete Medien angefordert werden, wechselt der Status zu "live".
  • "error" — Auf der OpenTok-Plattform ist ein Fehler aufgetreten.

Wenn Sie RTMP-Stream-Endpunkte angegeben haben, enthält das Objekt ein rtmp Eigenschaft. Hierbei handelt es sich um ein Array von Objekten, die Informationen zu jedem der RTMP-Streams enthalten. Jedes dieser Objekte verfügt über die folgenden Eigenschaften: id (die ID, die Sie dem RTMP-Stream zugewiesen haben), serverUrl (die Server-URL), streamName (der Name des Streams) und status Eigenschaft (die auf "connecting"). Sie können die OpenTok-REST-Methode zur Abfrage von Statusaktualisierungen für die Übertragung.

Die HTTP-Antwort enthält einen der folgenden Statuscodes:

  • 200 – Erfolg.
  • 400 – Ungültige Anfrage. Diese Antwort kann darauf hindeuten, dass die Daten in Ihrer Anfrage ungültiges JSON sind. Sie kann auch darauf hindeuten, dass Sie ungültige Layout-Optionen übergeben haben. Oder Sie haben das Limit von fünf gleichzeitigen RTMP-Streams für eine OpenTok-Sitzung überschritten. Oder Sie haben eine ungültige Auflösung angegeben.
  • 403 – Authentifizierungsfehler.
  • 409 — Die Übertragung für die Sitzung hat bereits begonnen. Oder wenn Sie versuchen, eine gleichzeitige Übertragung für eine Sitzung zu starten, ohne eine eindeutige multiBroadcastTag Wert.
  • 500 – OpenTok-Serverfehler.

Beispiel

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

Eine Live-Streaming-Übertragung beenden

Verwenden Sie diese Methode, um eine Live-Übertragung einer OpenTok-Sitzung zu beenden.

Beachten Sie, dass eine Übertragung automatisch beendet wird, sobald 60 Sekunden vergangen sind, nachdem sich der letzte Client von der Sitzung getrennt hat. Außerdem gilt für jeden HLS- und RTMP-Stream eine standardmäßige maximale Dauer von 4 Stunden (14.400 Sekunden) (die Live-Übertragung wird automatisch beendet, sobald diese Dauer erreicht ist). Sie können die maximale Dauer der Übertragung ändern, indem Sie die maxDuration Eigenschaft, wenn Sie Starten Sie die Sendung REST-Methode.

HTTP-POST an broadcast//stop

Senden Sie eine HTTP-POST-Anfrage an die folgende URL:

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

Ersetzen Sie <apiKey> mit Ihrem OpenTok-API-Schlüssel. Ersetzen Sie <broadcastId> mit der ID der Übertragung, die Sie beenden möchten. Die Übertragungs-ID erhalten Sie beim Starten einer Übertragung.

Eigenschaften des POST-Headers

Authentifizieren Sie diesen API-Aufruf mithilfe eines benutzerdefinierten HTTP-Headers — X-OPENTOK-AUTH — auf ein JSON-Web-Token gesetzt. Siehe Authentifizierung.

Anmerkung: Bisher wurde für diese REST-URL Folgendes verwendet: /partner (das inzwischen veraltet ist) anstelle von /project.

Antwort

Die Rohdaten der HTTP-Antwort mit dem Statuscode 200 sind eine JSON-kodierte Nachricht in folgender Form:

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

Das JSON-Objekt enthält die folgenden Eigenschaften:

  • id — Die eindeutige ID für die Übertragung
  • sessionId — Die ID der OpenTok-Sitzung, die gerade übertragen wird
  • projectId — Ihr OpenTok-API-Schlüssel
  • createdAt — Der Zeitpunkt des Sendebeginns, ausgedrückt in Sekunden seit der Unix-Epoche (1. Januar 1970, 00:00:00 UTC)
  • updatedAt — Der Zeitpunkt, zu dem die Übertragung beendet wurde, ausgedrückt in Sekunden seit der Unix-Epoche (1. Januar 1970, 00:00:00 UTC)
  • resolution - Die Auflösung der Sendung (entweder "640x480", "1280x720", "1920x1080", "480x640", "720x1280", oder "1080x1920").
  • status - Diese ist eingestellt auf "stopped".
  • streamMode - ob alle Streams in die Übertragung einbezogen werden ("auto") oder Sie wählen Streams aus, die in die Übertragung einbezogen werden sollen ("manual").
  • streams — Ein Array von Objekten, die den derzeit übertragenen Streams entsprechen. Bei der Methode „stop“ ist dies ein leeres Array.
  • maxDuration — Die maximale Dauer der Übertragung (sofern festgelegt) in Sekunden.
  • multiBroadcastTag - Der eindeutige Tag für gleichzeitige Übertragungen (falls einer festgelegt wurde).
  • broadcastUrls — Für die „stop“-Methode wird dieser Wert auf „null“ gesetzt.

Die HTTP-Antwort enthält einen der folgenden Statuscodes:

  • 200 – Erfolg.
  • 400 – Ungültige Anfrage. Diese Antwort kann darauf hindeuten, dass die Daten in Ihrer Anfrage ungültiges JSON sind.
  • 403 – Authentifizierungsfehler.
  • 404 – Die Sendung (mit der angegebenen ID) wurde nicht gefunden oder ist bereits beendet.
  • 500 – OpenTok-Serverfehler.

Beispiel

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

Auflistung von Live-Streaming-Übertragungen

Verwenden Sie diese Methode, um Details zu laufenden und bereits gestarteten Übertragungen abzurufen. Abgeschlossene Übertragungen sind in der Auflistung nicht enthalten.

HTTP-GET-Anfrage an den Broadcast

Senden Sie eine HTTP-GET-Anfrage an die folgende URL:

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

Ersetzen Sie <apiKey> mit Ihrem OpenTok-API-Schlüssel.

Die folgenden Abfrageparameter werden akzeptiert:

  • offset (optional) — Der Startversatz in der Liste der vorhandenen Sendungen
  • count (optional, Standardwert: 50, Höchstwert: 1000) — Die Anzahl der Broadcasts, die ab dem Offset abgerufen werden sollen
  • sessionId (optional): Nur Broadcasts für eine bestimmte Sitzungs-ID abrufen

GET-Header-Eigenschaften

Authentifizieren Sie diesen API-Aufruf mithilfe eines benutzerdefinierten HTTP-Headers — X-OPENTOK-AUTH — auf ein JSON-Web-Token gesetzt. Siehe Authentifizierung.

Antwort

Die Rohdaten der HTTP-Antwort mit dem Statuscode 200 sind eine JSON-kodierte Nachricht in folgender Form:

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

Das JSON-Objekt enthält die folgenden Eigenschaften:

  • count — Die Gesamtzahl der Sendungen in den Ergebnissen.
  • items — Ein Array von Objekten, die die jeweils abgerufenen Sendungen definieren. Die Sendungen werden in der Rückgabemenge von der neuesten zur ältesten aufgelistet.

Jedes Sendeobjekt (Element) verfügt über die folgenden Eigenschaften:

  • id — Die eindeutige ID für die Übertragung

  • sessionId — Die OpenTok-Sitzungs-ID

  • projectId — Ihr OpenTok-API-Schlüssel

  • createdAt — Der Zeitpunkt des Sendebeginns, ausgedrückt in Millisekunden seit der Unix-Epoche (1. Januar 1970, 00:00:00 UTC)

  • updatedAt — Bei dieser GET-Methode stimmt dieser Zeitstempel mit dem „createdAt“- Zeitstempel überein.

  • resolution — Die Auflösung der Übertragung (entweder „640x480“, „1280x720“, „1920x1080“, „480x640“, „720x1280“ oder „1080x1920“).

  • status — Der Status der Übertragung. Diese Methode gibt nur Übertragungen zurück, deren Status auf "started".

  • maxDuration — Die maximale Dauer der Übertragung (sofern festgelegt) in Sekunden.

  • multiBroadcastTag - Der eindeutige Tag für gleichzeitige Übertragungen (falls einer festgelegt wurde).

  • broadcastUrls - Einzelheiten zu den HLS- und RTMP-Übertragungsströmen.

    Bei einem HLS-Stream wird die URL als hls Eigenschaft. Siehe die OpenTok-Entwicklerhandbuch für Live-Streaming Weitere Informationen zur Verwendung dieser URL. Die hlsStatus auf eine der folgenden Eigenschaften eingestellt ist:

    • "connecting" — Der OpenTok-Server ist gerade dabei, die Transcoder zu starten. Dies ist der Ausgangszustand.
    • "ready" — Der OpenTok-Server wurde erfolgreich initialisiert, aber das CDN ruft keine Medien ab.
    • "live" — Der OpenTok-Server wurde erfolgreich initialisiert und das CDN ruft Medien ab.
    • "ended" — Der Quell-Stream ist beendet. Wenn die DVR-Funktion aktiviert ist und voraufgezeichnete Inhalte angefordert werden, wechselt der Status zu live".
    • "error" — Auf der OpenTok-Plattform ist ein Fehler aufgetreten.

    Für jeden RTMP-Stream werden die RTMP-Server-URL und der Stream-Name sowie der Status des RTMP- Streams angegeben. Die status auf eine der folgenden Eigenschaften eingestellt ist:

    • connecting — Die OpenTok-Plattform stellt gerade eine Verbindung zum externen RTMP-Server her. Dies ist der Ausgangszustand, der angezeigt wird, wenn Sie die Sitzung starten und noch keine Streams in der Sitzung veröffentlicht sind. Der Status wechselt zu „live“, sobald Streams vorhanden sind (oder zu einem der anderen Zustände).
    • live — Die OpenTok-Plattform hat erfolgreich eine Verbindung zum entfernten RTMP-Server hergestellt, und die Medien werden gestreamt.
    • offline — Die OpenTok-Plattform konnte keine Verbindung zum entfernten RTMP-Server herstellen. Dies liegt an einem nicht erreichbaren Server oder einem Fehler beim RTMP-Handshake. Mögliche Ursachen sind unter anderem abgelehnte RTMP-Verbindungen, nicht vorhandene RTMP-Applications, abgelehnte Stream-Namen, Authentifizierungsfehler usw. Überprüfen Sie, ob der Server online ist und ob Sie die richtige Server-URL und den richtigen Stream-Namen angegeben haben.
    • error — Auf der OpenTok-Plattform ist ein Fehler aufgetreten.

  • settings - Weitere Einzelheiten zum HLS-Übertragungsstrom. Diese settings Objekt enthält ein hls mit den folgenden Eigenschaften:

  • streamMode - ob alle Streams in die Übertragung einbezogen werden ("auto") oder Sie wählen die Streams aus, die in die Übertragung einbezogen werden sollen ("manual"). Siehe Auswahl der Streams, die in eine Live-Streaming-Übertragung einbezogen werden sollen.

  • streams — Für eine Sendung mit "manual" streamMode und eine status eingestellt auf "started", Dies ist ein Array von Objekten, die den derzeit ausgestrahlten Streams entsprechen. Jedes Objekt im Array enthält die folgenden Eigenschaften:

    • streamId - Die Stream-ID des in der Übertragung enthaltenen Streams.
    • hasAudio - Ob der Ton des Streams in der Übertragung enthalten ist.
    • hasVideo - Ob das Video des Streams in der Sendung enthalten ist.

Die HTTP-Antwort enthält einen der folgenden Statuscodes:

  • 200 – Erfolg
  • 403 – Authentifizierungsfehler
  • 500 – OpenTok-Serverfehler

Beispiele

Alle Sendungen auflisten (bis zu 50):

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

Auflistung verschiedener Sendungen:

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

Auflistung der Übertragungen für eine bestimmte Sitzungs-ID:

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

Informationen zu einer Live-Übertragung abrufen

Verwenden Sie diese Methode, um Details zu einer laufenden Übertragung abzurufen.

HTTP-GET-Anfrage an den Broadcast

Senden Sie eine HTTP-GET-Anfrage an die folgende URL:

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

Ersetzen Sie <apiKey> mit Ihrem OpenTok-API-Schlüssel. Ersetzen Sie <broadcastId> mit der ID der Übertragung. Die Übertragungs-ID erhalten Sie, wenn Sie eine Übertragung starten.

Anmerkung: Bisher wurde für diese REST-URL Folgendes verwendet: /partner (das inzwischen veraltet ist) anstelle von /project.

GET-Header-Eigenschaften

Authentifizieren Sie diesen API-Aufruf mithilfe eines benutzerdefinierten HTTP-Headers — X-OPENTOK-AUTH — auf ein JSON-Web-Token gesetzt. Siehe Authentifizierung.

Antwort

Die Rohdaten der HTTP-Antwort mit dem Statuscode 200 sind eine JSON-kodierte Nachricht in folgender Form:

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

Das JSON-Objekt enthält die folgenden Eigenschaften:

  • id — Die eindeutige ID für die Übertragung

  • sessionId — Die OpenTok-Sitzungs-ID

  • projectId — Ihr OpenTok-API-Schlüssel

  • createdAt — Der Zeitpunkt des Sendebeginns, ausgedrückt in Millisekunden seit der Unix-Epoche (1. Januar 1970, 00:00:00 UTC)

  • updatedAt - Bei dieser GET-Methode stimmt dieser Zeitstempel mit dem Zeitstempel createdAt überein.

  • resolution - Die Auflösung der Sendung (entweder "640x480", "1280x720", "1920x1080", "480x640", "720x1280", oder "1080x1920").

  • status — Der Status der Sendung: entweder "started" oder "stopped".

  • broadcastUrls - Einzelheiten zu den HLS- und RTMP-Übertragungsströmen.

    Bei einem HLS-Stream wird die URL als hls Eigentum. Siehe die OpenTok-Entwicklerhandbuch für Live-Streaming für weitere Informationen über die Verwendung dieser URL. Die hlsStatus auf eine der folgenden Eigenschaften eingestellt ist:

  • "connecting" — Der OpenTok-Server ist gerade dabei, die Transcoder zu starten. Dies ist der Ausgangszustand.
  • "ready" — Der OpenTok-Server wurde erfolgreich initialisiert, aber das CDN ruft keine Medien ab.
  • "live" — Der OpenTok-Server wurde erfolgreich initialisiert, und das CDN ruft Medien ab.
  • "ended" - Der Quellstream wurde beendet. Wenn DVR aktiviert ist und voraufgezeichnete Medien angefordert werden, wechselt der Status zu "live".
  • "error" — Auf der OpenTok-Plattform ist ein Fehler aufgetreten.

Für jeden RTMP-Stream werden die URL des RTMP-Servers und der Stream-Name sowie der Status des RTMP-Streams angegeben.

  • status — Der Status des RTMP-Streams. Führen Sie regelmäßig Abfragen durch, um Statusaktualisierungen zu überprüfen. Diese Eigenschaft kann einen der folgenden Werte annehmen:

    • connecting — Die OpenTok-Plattform stellt gerade eine Verbindung zum externen RTMP-Server her. Dies ist der Ausgangszustand, der angezeigt wird, wenn Sie die Sitzung starten und noch keine Streams veröffentlicht wurden. Der Status wechselt zu „live“, sobald Streams vorhanden sind (oder zu einem der anderen Zustände).
    • live — Die OpenTok-Plattform hat erfolgreich eine Verbindung zum externen RTMP-Server hergestellt, und die Medien werden gestreamt.
    • offline — Die OpenTok-Plattform konnte keine Verbindung zum entfernten RTMP-Server herstellen. Dies liegt an einem nicht erreichbaren Server oder einem Fehler beim RTMP-Handshake. Mögliche Ursachen sind abgelehnte RTMP-Verbindungen, nicht vorhandene RTMP-Applications, abgelehnte Stream-Namen, Authentifizierungsfehler usw. Überprüfen Sie, ob der Server online ist und ob Sie die richtige Server-URL und den richtigen Stream-Namen angegeben haben.
    • error — Auf der OpenTok-Plattform ist ein Fehler aufgetreten.

  • settings - Weitere Einzelheiten zum HLS-Übertragungsstrom. Diese properties Objekt enthält ein hls mit den folgenden Eigenschaften:

  • multiBroadcastTag - Der eindeutige Tag für gleichzeitige Übertragungen (falls einer festgelegt wurde).

  • streamMode - ob alle Streams in die Übertragung einbezogen werden ("auto") oder Sie wählen Streams aus, die in die Übertragung einbezogen werden sollen ("manual"). Siehe Auswahl von Streams für eine Live-Streaming-Übertragung.

  • streams - Ein Array von Objekten, die den Streams entsprechen, die gerade übertragen werden. Dies wird nur für eine Übertragung mit der Option status eingestellt auf "started" und die streamMode eingestellt auf "manual". Jedes Objekt im Array enthält die folgenden Eigenschaften:

    • streamId - Die Stream-ID des in der Übertragung enthaltenen Streams.
    • hasAudio - Ob der Ton des Streams in der Übertragung enthalten ist.
    • hasVideo - Ob das Video des Streams in der Sendung enthalten ist.

Die HTTP-Antwort enthält einen der folgenden Statuscodes:

  • 200 – Erfolg
  • 400 – Ungültige Anfrage
  • 403 – Authentifizierungsfehler
  • 404 – Es wurde keine passende Sendung gefunden (mit der angegebenen ID)
  • 500 – OpenTok-Serverfehler

Beispiel

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

Dynamische Änderung des Layout-Typs während einer Live-Streaming-Übertragung

Sie können den Layouttyp einer Live-Streaming-Übertragung dynamisch ändern.

Weitere Informationen zu Live-Streaming-Übertragungen mit OpenTok finden Sie unter Leitfaden für Entwickler im Bereich Rundfunk.

HTTP-PUT zur Übertragung

Senden Sie eine HTTP PUT-Anfrage an die folgende URL:

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

Ersetzen Sie <apiKey> mit Ihrem OpenTok-API-Schlüssel.

Ersetzen Sie <broadcastId> mit der Sendungs-ID.

PUT-Header-Eigenschaften

Setzen Sie die Content-Type Kopfzeile zu application/json.

Authentifizieren Sie diesen API-Aufruf mithilfe eines benutzerdefinierten HTTP-Headers — X-OPENTOK-AUTH — auf ein JSON-Web-Token gesetzt. Siehe Authentifizierung.

PUT-Daten

Fügen Sie ein JSON-Objekt in der folgenden Form als Inhalt des Request-Bodys ein:

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

Das JSON-Objekt enthält die folgenden Eigenschaften:

  • Typ (Zeichenkette) — Der Layouttyp für die Sendung. Gültige Werte sind "bestFit" (beste Anpassung), "custom" (Gewohnheit), "horizontalPresentation" (horizontale Darstellung), "pip" (Bild-in-Bild), und "verticalPresentation" (vertikale Darstellung)). Wenn Sie einen "custom" Layout-Typ, setzen Sie die stylesheet Eigenschaft zum Stylesheet hinzufügen. (Bei anderen Layouttypen darf die stylesheet Eigenschaft.) Weitere Informationen finden Sie unter Konfigurieren des Video-Layouts für die OpenTok-Live-Streaming-Funktion.
  • Stylesheet (Zeichenkette) — Optional. Geben Sie dies nur an, wenn Sie die type Eigenschaft zu "custom". Setzen Sie die stylesheet Eigenschaft zum Stylesheet hinzufügen. (Bei anderen Layouttypen darf die stylesheet Eigenschaft.) Weitere Informationen finden Sie unter Definieren benutzerdefinierter Layouts.
  • screenshareType (Zeichenkette) — Optional. Der Layouttyp, der verwendet werden soll, wenn in der Sitzung ein Bildschirmfreigabestream vorliegt. Beachten Sie, dass Sie zur Verwendung dieser Eigenschaft die type Eigenschaft auf "bestFit" und lassen Sie die stylesheet Eigenschaft nicht gesetzt. Für weitere Informationen, siehe Layout-Typen für die Bildschirmfreigabe.

Wenn Sie einen anderen Layouttyp als „Best Fit“ festlegen, achten Sie darauf, für die Streams in der OpenTok-Sitzung die entsprechenden Layoutklassen anzuwenden (siehe Zuweisung von Live-Streaming-Layout-Klassen zu OpenTok-Streams.

Antwort

Die HTTP-Antwort enthält einen der folgenden Statuscodes:

  • 200 – Erfolg.
  • 400 – Ungültige Anfrage. Diese Antwort kann darauf hindeuten, dass die Daten in Ihrer Anfrage ungültiges JSON sind. Sie kann auch darauf hindeuten, dass Sie ungültige Layout-Optionen übergeben haben.
  • 403 – Authentifizierungsfehler.
  • 500 – OpenTok-Serverfehler.

Beispiel

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

Ändern der Layout-Klassen für einen OpenTok-Live-Stream

Verwenden Sie diese Methode, um die Layout-Klassen für einen OpenTok-Stream zu ändern. Die Layout-Klassen legen fest, wie der Stream im Layout des Übertragungsstroms angezeigt wird. Weitere Informationen finden Sie unter Zuweisung von Live-Streaming-Layout-Klassen zu OpenTok-Streams.

HTTP-PUT an den Stream

Senden Sie eine HTTP PUT-Anfrage an die folgende URL:

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

Ersetzen Sie <apiKey> mit Ihrem OpenTok-API-Schlüssel.

Ersetzen Sie <sessionId> mit der Sitzungs-ID.

PUT-Header-Eigenschaften

Setzen Sie die Content-Type Kopfzeile zu application/json.

Authentifizieren Sie diesen API-Aufruf mithilfe eines benutzerdefinierten HTTP-Headers — X-OPENTOK-AUTH — auf ein JSON-Web-Token gesetzt. Siehe Authentifizierung.

PUT-Daten

Fügen Sie ein JSON-Objekt in der folgenden Form als Inhalt des Request-Bodys ein:

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

Das JSON-Objekt enthält ein items Objekt-Array. Jedes Objekt definiert die Layout-Klassen, die einem Stream zugewiesen werden sollen, und enthält folgende Eigenschaften:

  • id (Zeichenkette) — Die Stream-ID.
  • layoutClassList (Array) — Ein Array von Layout-Klassen (jeweils als Zeichenfolge) für den Stream.

Sie können die Liste der Layout-Klassen für mehrere Streams aktualisieren, indem Sie mehrere JSON-Objekte in der items Array.

Antwort

Die HTTP-Antwort enthält einen der folgenden Statuscodes:

  • 200 – Erfolg.
  • 400 – Ungültige Anfrage. Diese Antwort kann darauf hindeuten, dass die Daten in Ihrer Anfrage ungültiges JSON sind. Sie kann auch darauf hindeuten, dass Sie ungültige Layout-Optionen übergeben haben.
  • 403 – Authentifizierungsfehler.
  • 500 – OpenTok-Serverfehler.

Beispiel

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

Auswahl von Streams für eine Live-Streaming-Übertragung

Verwenden Sie diese Methode, um die in einer Live-Streaming-Übertragung enthaltenen Streams zu ändern, die mit dem streamMode eingestellt auf "manual" (siehe Eine Live-Streaming-Übertragung starten).

Der Broadcast-Komponist bezieht zusätzliche Streams auf der Grundlage von Strompriorisierungsregeln.

HTTP-PATCH an „broadcast/streams“

Senden Sie eine HTTP-PATCH-Anfrage an die folgende URL:

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

Ersetzen Sie <apiKey> mit Ihrem OpenTok-API-Schlüssel. Ersetzen Sie <broadcastId> mit der Sendungs-ID.

Eigenschaften des PATCH-Headers

Setzen Sie die Content-Type Kopfzeile zu application/json.

Authentifizieren Sie diesen API-Aufruf mithilfe eines benutzerdefinierten HTTP-Headers — X-OPENTOK-AUTH — auf ein JSON-Web-Token gesetzt. Siehe Authentifizierung.

PATCH-Daten

Um einen Stream zur Übertragung hinzuzufügen, fügen Sie ein JSON-Objekt in der folgenden Form als Inhalt des Request-Bodys ein:

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

Das JSON-Objekt enthält die folgenden Eigenschaften:

  • addStream (Zeichenkette) — Die Stream-ID.
  • hasAudio (Boolescher Wert, optional) – Gibt an, ob die Übertragung den Ton des Streams enthalten soll (true, die Standardeinstellung) oder nicht (false).
  • hasVideo (Boolescher Wert, optional) – Gibt an, ob die Übertragung das Videomaterial des Streams enthalten soll (true, die Standardeinstellung) oder nicht (false).

Sie können die Methode wiederholt aufrufen mit addStream auf dieselbe Stream-ID setzen, um die Audio- bzw. Videoübertragung des Streams in der Sendung umzuschalten.

Wenn Sie beides einstellen hasAudio und hasVideo zu false, erhalten Sie eine Fehlermeldung.

Um zu verhindern, dass ein Stream in die Übertragung einbezogen wird, fügen Sie ein JSON-Objekt in folgender Form als Inhalt des Request-Bodys ein:

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

Setzen Sie die removeStream Eigenschaft der Stream-ID.

Antwort

Die HTTP-Antwort enthält einen der folgenden Statuscodes:

  • 204 – Erfolg (kein Inhalt).
  • 400 – Ungültige Anfrage. Diese Antwort kann darauf hindeuten, dass die in Ihrer Anfrage angegebenen Daten ein ungültiges JSON sind oder dass die Anfrage nicht bearbeitet werden konnte, da der Broadcast gestartet wurde mit streamMode eingestellt auf "auto", das keine Stream-Bearbeitung unterstützt.
  • 403 – Authentifizierungsfehler.
  • 404 – Sendung oder Stream nicht gefunden.
  • 500 – OpenTok-Serverfehler.

Beispiele

Einen Stream zu einer Übertragung hinzufügen:

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

Das Video eines Streams während einer Übertragung entfernen (den Ton jedoch beibehalten):

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

Einen Stream aus einer Übertragung entfernen:

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

Live-Untertitel starten

Verwenden Sie diese Methode, um Echtzeit-Live-Untertitel für eine OpenTok-Sitzung zu aktivieren.

Die maximal zulässige Dauer beträgt 4 Stunden. Danach wird die Audio-Untertitelung beendet, ohne dass dies Auswirkungen auf die laufende OpenTok-Sitzung hat. Untertitelungssitzungen werden außerdem 60 Sekunden nach der Trennung des letzten Clients beendet. Ein Ereignis wird an Ihre Callback-URL gesendet, sofern diese beim Start der Untertitelung angegeben wurde.

Jede OpenTok-Sitzung unterstützt nur eine Audio-Untertitelungssitzung.

Weitere Informationen zur Funktion „Live-Untertitel“ finden Sie unter Live Captions Entwicklerhandbuch.

HTTP-POST zum Starten der Live-Untertitel

Senden Sie eine HTTP-POST-Anfrage an die folgende URL:

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

Ersetzen Sie <apiKey> mit Ihrem OpenTok-API-Schlüssel.

Setzen Sie die Content-Type Kopfzeile zu application/json.

Authentifizieren Sie diesen API-Aufruf mithilfe eines benutzerdefinierten HTTP-Headers — X-OPENTOK-AUTH — auf ein JSON-Web-Token gesetzt. Siehe Authentifizierung.

POST-Daten

Fügen Sie ein JSON-Objekt in der folgenden Form als Inhalt des Request-Bodys ein:

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

Das JSON-Objekt enthält die folgenden Eigenschaften:

  • sessionId (Zeichenkette) — Die Sitzungs-ID der OpenTok-Sitzung. Das Audiomaterial der Publisher, die in diese Sitzung senden, wird zur Erstellung der Untertitel verwendet.
  • token(Zeichenkette) – Ein gültiges OpenTok-Token, dessen Rolle auf „Moderator“ gesetzt ist.
  • languageCode (Zeichenkette) — (Optional) Der BCP-47-Code für die von „Live Captions“ verwendete Sprache (siehe diese Liste der unterstützten Sprachen). Der Standardwert lautet „en-US“.
  • maxDuration (Ganzzahl) — (Optional) Die maximale Dauer der Audio-Untertitelung in Sekunden. Der Standardwert beträgt 14.400 Sekunden (4 Stunden), was der maximal zulässigen Dauer entspricht. Der Mindestwert für maxDuration beträgt 300 (300 Sekunden oder 5 Minuten).
  • partialCaptions (Boolescher Wert) — (Optional) Gibt an, ob diese Option aktiviert werden soll, um die Untertitelung zu beschleunigen, wobei dies mit gewissen Ungenauigkeiten einhergeht. Der Standardwert ist true.

Antwort

Im Erfolgsfall bestehen die Rohdaten der HTTP-Antwort mit dem Statuscode 200 aus einer JSON-kodierten Nachricht in folgender Form:

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

Das JSON-Objekt enthält die folgende Eigenschaft:

  • captionsId — Die eindeutige ID für die Audio-Untertitel-Sitzung.

Die HTTP-Antwort enthält einen der folgenden Statuscodes:

  • 202 — Angenommen.
  • 400 – Ungültige Anfrage; Die Antwort weist möglicherweise auf einen Fehler in den Daten der Anfrage hin, der nicht akzeptabel ist.
  • 403 – Authentifizierungsfehler. Die angegebene X-OPENTOK-AUTH ist möglicherweise ungültig.
  • 409 — Die Live-Untertitel für diese OpenTok-Sitzung haben bereits begonnen.
  • 500 – Fehler der Vonage Video API-Plattform.

Beispiel


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

Live-Untertitel anhalten

Verwenden Sie diese Methode, um die Live-Untertitel für eine Sitzung zu deaktivieren.

HTTP-POST-Anfrage zum Beenden der Live-Untertitel

Senden Sie eine HTTP-POST-Anfrage an die folgende URL:

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

Ersetzen Sie <apiKey> mit Ihrem OpenTok-API-Schlüssel. Ersetzen Sie <captionsId> mit der ID, die in der Antwort der Start-Captions-API zurückgegeben wurde.

Authentifizieren Sie diesen API-Aufruf mithilfe eines benutzerdefinierten HTTP-Headers — X-OPENTOK-AUTH — auf ein JSON-Web-Token gesetzt. Siehe Authentifizierung.

Die HTTP-Antwort enthält einen der folgenden Statuscodes:

  • 202 — Angenommen
  • 403 – Authentifizierungsfehler
  • 404 – Es wurde keine übereinstimmende „captionsId“ gefunden
  • 500 – Fehler der Vonage Video API-Plattform

Beispiel

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;

Experience Composer starten

Verwenden Sie diese Methode, um einen Experience Composer für eine OpenTok-Sitzung zu erstellen. Weitere Informationen finden Sie in der Entwicklerhandbuch zu Experience Composer.

HTTP-POST zum Rendern

Senden Sie eine HTTP-POST-Anfrage an die folgende URL:

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

Ersetzen Sie <apiKey> mit Ihrem OpenTok-API-Schlüssel.

Eigenschaften des POST-Headers

Setzen Sie die Content-Type Kopfzeile zu application/json.

Authentifizieren Sie diesen API-Aufruf mithilfe eines benutzerdefinierten HTTP-Headers — X-OPENTOK-AUTH — auf ein JSON-Web-Token gesetzt. Siehe Authentifizierung.

POST-Daten

Fügen Sie ein JSON-Objekt in der folgenden Form als Inhalt des Request-Bodys ein:

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

Das JSON-Objekt enthält die folgenden Eigenschaften:

  • sessionId (String) – Die Sitzungs-ID der OpenTok-Sitzung, in die der Stream aus dem Experience Composer eingebunden wird.
  • Token (String) – Ein gültiges OpenTok-Token mit der Rolle „Publisher“ und (optional) Verbindungsdaten, die dem Ausgabestream zugeordnet werden sollen.
  • url (Zeichenkette) – Eine öffentlich zugängliche URL, die vom Kunden verwaltet wird und in der Lage ist, den darzustellenden Inhalt ohne Benutzereingriff zu generieren. Die Mindestlänge der URL beträgt 15 Zeichen, die Höchstlänge 2048 Zeichen.
  • maxDuration (Ganzzahl) — (Optional) Die maximal zulässige Laufzeit des Experience Composers in Sekunden. Nach Ablauf dieser Zeit wird er automatisch beendet, sofern er noch läuft. Der Maximalwert beträgt 36000 (10 Stunden), der Mindestwert 60 (1 Minute) und der Standardwert 7200 (2 Stunden). Wenn der Experience Composer beendet wird, wird sein Stream deaktiviert und ein Ereignis an die Callback-URL gesendet, sofern diese im Account-Portal konfiguriert wurde.
  • Auflösung (Zeichenkette) — (Optional) Die Auflösung des Experience Composers, entweder „640x480“ (SD Querformat), „480x640“ (SD Hochformat), „1280x720“ (HD Querformat), „720x1280“ (HD Hochformat), „1920x1080“ (FHD Querformat) oder „1080x1920“ (FHD Hochformat). Standardmäßig ist diese Auflösung „1280x720“ (HD Querformat, die Standardeinstellung).
  • Eigenschaften (Objekt) — (Optional) Die Anfangskonfiguration der Publisher-Eigenschaften für den zusammengesetzten Ausgabestrom. Das Eigenschaftenobjekt enthält den Schlüssel „name“ (Zeichenkette), der als Name des zusammengesetzten Ausgabestroms dient, der an die Sitzung veröffentlicht wird. Der Name muss mindestens 1 und höchstens 200 Zeichen lang sein.

Antwort

Die Rohdaten der HTTP-Antwort mit dem Statuscode 200 sind eine JSON-kodierte Nachricht in der folgenden Form:

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

Das JSON-Objekt enthält die folgenden Eigenschaften:

  • id — Die eindeutige ID für den Experience Composer.
  • sessionId — Die OpenTok-Sitzungs-ID.
  • projectId — Ihr OpenTok-API-Schlüssel.
  • createdAt – Der Zeitpunkt, zu dem der Experience Composer gestartet wurde, ausgedrückt in Millisekunden seit der Unix-Epoche (1. Januar 1970, 00:00:00 UTC).
  • updatedAt — Dies ist der UNIX-Zeitstempel, zu dem der Status des Experience Composers zuletzt aktualisiert wurde. Bei dieser Startmethode stimmt dieser Zeitstempel mit dem „createdAt“-Zeitstempel überein.
  • callbackUrl – Die Callback-URL für Experience Composer-Ereignisse (sofern eine festgelegt wurde). Siehe Konfigurieren von Rückrufen.
  • name — Der Name des Experience Composer (sofern einer angegeben wurde).
  • url — Eine öffentlich zugängliche URL, die vom Kunden verwaltet wird und in der Lage ist, den darzustellenden Inhalt ohne Benutzereingriff zu generieren.
  • Auflösung – Die Auflösung des Experience Composer (entweder „640x480“, „480x640“, „1280x720“, „720x1280“, „1920x1080“ oder „1080x1920“).
  • Status — Bei dieser Startmethode ist dieser Wert auf „starting“ gesetzt.
  • streamId — Die ID des zusammengesetzten Streams, der veröffentlicht wird.

Die HTTP-Antwort enthält einen der folgenden Statuscodes:

  • 202 – Erfolg.

  • 400 – Ungültige Anfrage. Diese Antwort kann darauf hinweisen, dass die Daten in Ihrer Anfrage ungültiges JSON sind. Sie kann einen Fehlercode enthalten, von denen einige im Folgenden aufgeführt sind:

    • 50001 – Ungültige URL-Struktur der Anwendung.
    • 50002 – Die URL der Anwendung ist nicht erreichbar.
    • 50005 — Ungültiger „maxDuration“-Wert angegeben.
    • 50006 — Ungültige Auflösung angegeben.
    • 50007 — Es wurde ein ungültiger Stream-Name angegeben.
    • 50008 — Es wurde eine ungültige sessionId angegeben.

  • 403 – Authentifizierungsfehler. Dieser Fehler kann einen Fehlercode enthalten, von denen einige im Folgenden aufgeführt sind:

    • 10001 – Ungültiges Token-Format oder ungültige Signatur.
    • 10002 – Ungültiges Token.
    • 10003 – Ungültiges Format der Partnerauthentifizierung.
    • 10004 – Unzulässige Partnerauthentifizierung.
    • 10007 – Das Token stimmt nicht mit der Sitzungs-ID überein.
    • 10012 – Token abgelaufen.

  • 429 – Zu viele Anfragen. Sie haben das Nutzungslimit für „Experienced Composer“ überschritten. Die Antwort enthält den Fehlercode 50004.

  • 500 – Fehler der Vonage Video API-Plattform.

Beispiel

  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

Informationen zu einem Experience Composer abrufen

Verwenden Sie diese Methode, um Details zu einem Experience Composer abzurufen.

HTTP-GET-Aufruf zum Rendern

Senden Sie eine HTTP-GET-Anfrage an die folgende URL:

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

Ersetzen Sie <apiKey> mit Ihrem OpenTok-API-Schlüssel. Ersetzen Sie <experienceComposerId> mit der ID des Experience Composers. Die ID des Experience Composers erhalten Sie, wenn Sie einen Experience Composer starten.

GET-Header-Eigenschaften

Authentifizieren Sie diesen API-Aufruf mithilfe eines benutzerdefinierten HTTP-Headers – X-OPENTOK-AUTH –, der auf ein JSON-Web-Token gesetzt ist. Siehe Authentifizierung.

Antwort

Die Rohdaten der HTTP-Antwort mit dem Statuscode 200 sind eine JSON-kodierte Nachricht in der folgenden Form:

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

Das JSON-Objekt enthält die folgenden Eigenschaften:

  • id — Die eindeutige ID für den Experience Composer.
  • sessionId — Die OpenTok-Sitzungs-ID.
  • projectId — Ihr OpenTok-API-Schlüssel.
  • createdAt – Der Zeitpunkt, zu dem der Experience Composer gestartet wurde, ausgedrückt in Millisekunden seit der Unix-Epoche (1. Januar 1970, 00:00:00 UTC).
  • updatedAt — Bei dieser GET-Methode entspricht dieser Zeitstempel dem createdAt-Zeitstempel.
  • callbackUrl — Der Callback für Ereignisse des URL Experience Composer (sofern einer festgelegt wurde). Siehe Konfigurieren von Rückrufen.
  • name — Der Name des Experience Composer (sofern einer angegeben wurde).
  • url — Eine öffentlich zugängliche URL, die vom Kunden verwaltet wird und die den darzustellenden Inhalt ohne Benutzereingriff generieren kann.
  • Auflösung — Die Auflösung des Experience Composer (entweder „640x480“, „1280x720“, „480x640“ oder „720x1280“).
  • status — Der Status des Experience Composers. Führen Sie regelmäßig Abfragen durch, um Statusaktualisierungen zu überprüfen. Diese Eigenschaft kann einen der folgenden Werte annehmen:
    • „startend“ – Die Vonage Video API-Plattform stellt gerade eine Verbindung zur Remote-Anwendung unter der angegebenen URL her. Dies ist der Anfangszustand.
    • „gestartet“ – Die Vonage Video API-Plattform hat erfolgreich eine Verbindung zum Remote-Anwendungsserver hergestellt und veröffentlicht die Webansicht in einem OpenTok-Stream.
    • „beendet“ – Der Experience Composer wurde beendet.
    • „fehlgeschlagen“ – Es ist ein Fehler aufgetreten, und der Experience Composer konnte nicht fortfahren. Dies kann beim Start auftreten, wenn der OpenTok- Server keine Verbindung zum Remote-Anwendungsserver herstellen oder den Stream nicht erneut veröffentlichen kann. Es kann auch zu jedem beliebigen Zeitpunkt während des Vorgangs aufgrund eines Fehlers in der Vonage Video API-Plattform auftreten.
  • Grund — Das Feld „Grund“ ist nur verfügbar, wenn der Status entweder „gestoppt“ oder „fehlgeschlagen“ lautet. Bei dem Status „gestoppt“ enthält das Feld „Grund“ entweder den Eintrag „Maximale Dauer überschritten“ oder „Stopp angefordert“. Bei dem Status „fehlgeschlagen“ enthält das Feld „Grund“ eine genauere Fehlermeldung.
  • streamId – Die ID des zusammengesetzten Streams, der veröffentlicht wird. Die streamId ist nicht verfügbar, wenn der Status „starting“ lautet, und ist möglicherweise nicht verfügbar, wenn der Status „failed“ lautet.

Die HTTP-Antwort enthält einen der folgenden Statuscodes:

  • 200 – Erfolg
  • 400 – Ungültige Anfrage
  • 403 – Authentifizierungsfehler
  • 404 – Es wurde kein Komponist mit der angegebenen ID gefunden.
  • 500 – Fehler der Vonage Video API-Plattform.

Beispiel

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;

Eine Liste erfahrener Komponisten abrufen

Verwenden Sie diese Methode, um eine Liste der mit einem Projekt verknüpften Experience-Entwickler abzurufen.

HTTP-GET-Aufruf zum Rendern

Senden Sie eine HTTP-GET-Anfrage an die folgende URL:

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

Ersetzen Sie <apiKey> mit Ihrem OpenTok-API-Schlüssel. Die folgenden optionalen Abfrageparameter können hinzugefügt werden:

  • offset — Der Start-Offset für die Liste der „Experience Composers“. Der Standardwert ist 0.
  • count — Die Anzahl der „Experience Composers“, die ab dem Offset abgerufen werden sollen. Der Standardwert beträgt 50, und der Maximalwert liegt bei 1000.

GET-Header-Eigenschaften

Authentifizieren Sie diesen API-Aufruf mithilfe eines benutzerdefinierten HTTP-Headers – X-OPENTOK-AUTH –, der auf ein JSON-Web-Token gesetzt ist. Siehe Authentifizierung.

Antwort

Die Rohdaten der HTTP-Antwort mit dem Statuscode 200 sind eine JSON-kodierte Nachricht in der folgenden Form:

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

Das JSON-Objekt enthält die folgenden Eigenschaften:

  • Anzahl — Die Gesamtzahl der Experience Composers.
  • Elemente — Das Array, das die abgerufenen Experience Composers enthält. Jedes Experience-Composer-Element umfasst die folgenden Eigenschaften:
    • id — Die eindeutige ID für den Experience Composer.
    • sessionId — Die OpenTok-Sitzungs-ID.
    • projectId — Ihr OpenTok-API-Schlüssel.
    • createdAt – Der Zeitpunkt, zu dem der Experience Composer gestartet wurde, ausgedrückt in Millisekunden seit der Unix-Epoche (1. Januar 1970, 00:00:00 UTC).
    • updatedAt — Bei dieser GET-Methode entspricht dieser Zeitstempel dem createdAt-Zeitstempel.
    • callbackUrl – Die Callback-URL für Experience Composer-Ereignisse (sofern eine festgelegt wurde). Siehe Konfigurieren von Rückrufen.
    • name — Der Name des Experience Composer (sofern einer angegeben wurde).
    • url — Eine öffentlich zugängliche URL, die vom Kunden verwaltet wird und die den darzustellenden Inhalt ohne Benutzereingriff generieren kann.
    • Auflösung — Die Auflösung des Experience Composer (entweder „640x480“, „1280x720“, „480x640“ oder „720x1280“).
    • status — Der Status des Experience Composers. Führen Sie regelmäßig Abfragen durch, um Statusaktualisierungen zu überprüfen. Diese Eigenschaft kann einen der folgenden Werte annehmen:
      • „startend“ – Die Vonage Video API-Plattform stellt gerade eine Verbindung zur Remote-Anwendung unter der angegebenen URL her. Dies ist der Anfangszustand.
      • „gestartet“ – Die Vonage Video API-Plattform hat erfolgreich eine Verbindung zum Remote-Anwendungsserver hergestellt und veröffentlicht die Webansicht in einem OpenTok-Stream.
      • „beendet“ – Der Experience Composer wurde beendet.
      • „fehlgeschlagen“ – Es ist ein Fehler aufgetreten, und der Experience Composer konnte nicht fortfahren. Dies kann beim Start auftreten, wenn der OpenTok- Server keine Verbindung zum Remote-Anwendungsserver herstellen oder den Stream nicht erneut veröffentlichen kann. Es kann auch zu jedem beliebigen Zeitpunkt während des Vorgangs aufgrund eines Fehlers der Vonage Video API-Plattform auftreten.
    • Grund — Das Feld „Grund“ ist nur verfügbar, wenn der Status entweder „gestoppt“ oder „fehlgeschlagen“ lautet. Wenn der Status „gestoppt“ lautet, enthält das Feld „Grund“ entweder „Maximale Dauer überschritten“ oder „Stopp angefordert“. Wenn der Status „fehlgeschlagen“ lautet, enthält das Feld „Grund“ eine genauere Fehlermeldung.
    • streamId – Die ID des zusammengesetzten Streams, der veröffentlicht wird. Die streamId ist nicht verfügbar, wenn der Status „starting“ lautet, und ist möglicherweise nicht verfügbar, wenn der Status „failed“ lautet.

Die HTTP-Antwort enthält einen der folgenden Statuscodes:

  • 200 – Erfolg
  • 403 – Authentifizierungsfehler
  • 500 – Fehler der Vonage Video API-Plattform.

Beispiel

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

Einen Experience Composer beenden

Verwenden Sie diese Methode, um einen Experience Composer einer OpenTok-Sitzung zu beenden. Beachten Sie, dass Experience Composer standardmäßig automatisch 2 Stunden nach ihrem Start beendet werden. Sie können beim Erstellen des Experience Composers auch einen anderen Wert für „maxDuration“ festlegen. Wenn der Experience Composer beendet wird, wird ein Ereignis an die Callback-URL gesendet, sofern Sie eine für das Projekt eingerichtet.

HTTP-DELETE zum Rendern

Senden Sie eine HTTP-DELETE-Anfrage an die folgende URL:

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

Ersetzen Sie <apiKey> mit Ihrem OpenTok-API-Schlüssel. Ersetzen Sie <experienceComposerId> mit der ID des Experience Composers, den Sie beenden möchten. Die Experience Composer-ID entnehmen Sie der Antwort, die Sie beim Starten eines Experience Composers erhalten haben.

DELETE-Header-Eigenschaften

Authentifizieren Sie diesen API-Aufruf mithilfe eines benutzerdefinierten HTTP-Headers – X-OPENTOK-AUTH –, der auf ein JSON-Web-Token gesetzt ist. Siehe Authentifizierung.

Antwort

Die HTTP-Antwort enthält einen der folgenden Statuscodes:

  • 204 – Kein Inhalt.
  • 400 – Ungültige Anfrage.
  • 403 – Authentifizierungsfehler.
  • 404 – Der Experience Composer (mit der angegebenen ID) wurde nicht gefunden oder wurde bereits beendet.
  • 500 – Fehler der Vonage Video API-Plattform.

Beispiel

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

Eine Audio-Connector-WebSocket-Verbindung herstellen

Verwenden Sie diese Methode, um Audio aus einer Vonage Video API-Sitzung an einen WebSocket zu senden.

Weitere Informationen, einschließlich Einzelheiten zu den WebSocket-Daten, finden Sie in der Audio Connector Entwicklerhandbuch.

HTTP-POST zum Herstellen einer Verbindung

Senden Sie eine HTTP-POST-Anfrage an die folgende URL:

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

Ersetzen Sie <apiKey> mit Ihrem OpenTok-API-Schlüssel.

Eigenschaften des POST-Headers

Setzen Sie die Content-Type Kopfzeile zu application/json.

Authentifizieren Sie diesen API-Aufruf mithilfe eines benutzerdefinierten HTTP-Headers — X-OPENTOK-AUTH — auf ein JSON-Web-Token gesetzt. Siehe Authentifizierung.

POST-Daten

Fügen Sie ein JSON-Objekt in der folgenden Form als Inhalt des Request-Bodys ein:

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

Das JSON-Objekt enthält die folgenden Eigenschaften:

  • sessionId​ (erforderlich) — Die OpenTok-Sitzungs-ID, die die OpenTok-Streams enthält, die Sie in den WebSocket-Stream einbinden möchten. Die Audio-Connector-Funktion wird nur in gerouteten Sitzungen unterstützt (Sitzungen, die die OpenTok Media Router).

  • token​ (erforderlich) — Das OpenTok-Token, das für die Verbindung des Audio Connectors zur OpenTok-Sitzung verwendet werden soll. Sie können ein Token hinzufügen data um festzustellen, ob es sich bei der Verbindung um den Endpunkt „Audio Connector“ handelt, oder um andere identifizierende Daten zu ermitteln. (Die OpenTok-Client-Bibliotheken enthalten Eigenschaften, mit denen die Verbindungsdaten eines mit einer Sitzung verbundenen Clients überprüft werden können.) Wenn Sie den Audio Connector verwenden möchten, um Audio in die Sitzung einbinden, setze die Rolle des Tokens auf publisher oder moderator. Siehe die Token-Erstellung Leitfaden für Entwickler.

  • websocket (erforderlich): Enthaltene Details für den WebSocket:

    • uri ​(erforderlich): Eine öffentlich erreichbare WebSocket-URI, die als Ziel für den Audiostream verwendet werden soll (z. B. „wss://example.com/ws-endpoint“).

    • streams (optional) — Ein Array mit Stream-IDs für die OpenTok-Streams, die Sie in das WebSocket-Audio einbinden möchten. Wenn Sie diese Eigenschaft weglassen, werden alle Streams der Sitzung einbezogen.

    • headers​ (optional) - Ein Objekt mit Schlüssel-Wert-Paaren von Kopfzeilen, die mit jeder Nachricht an Ihren WebSocket-Server gesendet werden, mit einer maximalen Länge von 512 Bytes.

    • audioRate (optional) - Eine Zahl, die die Audio-Abtastrate in Hz angibt. Akzeptierte Werte sind 8000, 16000 (Standard) und 24000.

    • audioTransport (optional) - Ein JSON-Objekt, das konfiguriert, wie Audio auf der WebSocket-Leitung serialisiert der WebSocket-Leitung serialisiert wird. Standardmäßig wird Audio als rohe binäre PCM 16-Bit-Frames gesendet. Setzen Sie dies, um JSON-verpacktes base64-Audio zu verwenden, was von einigen KI-Anbietern (z. B. OpenAI Realtime) verlangt wird. Das Objekt hat die folgenden Eigenschaften:

      • transport (erforderlich) - "binary" (rohe PCM16, die Voreinstellung) oder "json".
      • encoding (erforderlich, wenn der Transport "json") - "base64".
      • audio_field (optional) - Der JSON-Schlüssel für die ausgehenden Audiodaten. Der Standardwert ist "audio".
      • receive_audio_field (optional) - Der JSON-Schlüssel für eingehende Audiodaten (wenn bidirektional aktiviert ist). Standardmäßig derselbe Wert wie audio_field.
      • static_fields (optional) - Ein Objekt mit zusätzlichen Schlüssel-Wert-Paaren, die in jeder ausgehenden JSON-Audionachricht enthalten sind.

    • bidirectional (optional) — (Boolescher Wert) Gibt an, ob Audiodaten aus der WebSocket-Verbindung an einen in der Sitzung veröffentlichten Stream gesendet werden sollen. Der Standardwert ist false (Der WebSocket wird nicht zur Veröffentlichung eines Streams verwendet). Weitere Informationen finden Sie in der Audio Connector Entwicklerhandbuch.

Antwort

Ein erfolgreicher Aufruf führt zu einer HTTP-Antwort mit dem Statuscode 200, wobei die Details in den JSON-Antwortdaten enthalten sind:

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

Die JSON-Antwortdaten umfassen die folgenden Eigenschaften:

  • id - Eine eindeutige ID zur Identifizierung der Audio Connector WebSocket-Verbindung.

  • connectionId — Die OpenTok-Verbindungs-ID für die WebSocket-Verbindung des Audio Connectors innerhalb der OpenTok-Sitzung.

Im Fehlerfall enthält die HTTP-Antwort einen der folgenden Statuscodes:

  • 400 – Ungültige Anfrage. Diese Antwort kann darauf hinweisen, dass die Daten in Ihrer Anfrage ungültiges JSON sind oder dass eine der JSON-Eigenschaften ungültig ist.
  • 403 – Authentifizierungsfehler.
  • 409 – Nur weitergeleitete Sitzungen dürfen Audio-Connector-WebSocket-Verbindungen initiieren.
  • 500 – OpenTok-Serverfehler.

Beispiel

Einen Audio-Connector-WebSocket starten:

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

Einen neuen Projekt-API-Schlüssel erstellen

Verwenden Sie diese Methode, um einen OpenTok-API-Schlüssel und ein API-Geheimnis für ein Projekt zu erstellen.

Das ist wichtig: Nachdem Sie das Projekt erstellt haben, kann es bis zu 60 Sekunden dauern, bis es zur Nutzung bereitsteht.

Sie können auch ein neues Projekt auf Ihrem Vonage Video API-Konto Seite.

POST an Partner

Senden Sie eine HTTP-POST-Anfrage an die folgende URL:

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

Eigenschaften des POST-Headers

Wenn Sie Anforderungsdaten zum Festlegen eines Namens senden möchten (siehe den nächsten Abschnitt, „POST-Daten“), legen Sie die Content-Type Kopfzeile zu application/json. Andernfalls setzen Sie die Content-Type Kopfzeile.

Authentifizieren Sie diesen API-Aufruf mithilfe eines benutzerdefinierten HTTP-Headers — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Setzen Sie diesen Header auf ein JWT-Token (siehe Authentifizierung). Beachten Sie, dass Sie das auf Account-Ebene API-Schlüssel und auf Account-Ebene API Geheimcode beim Erstellen des Tokens. Der API-Schlüssel und der Geheimcode auf Account-Ebene stehen ausschließlich registrierten Administratoren Ihres OpenTok-Accounts zur Verfügung.

POST-Daten

Fügen Sie ein JSON-Objekt in der folgenden Form als Inhalt des Request-Bodys ein:

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

Wenn Sie dem Projekt keinen Namen geben möchten, lassen Sie den Hauptteil leer.

HTTP-Antwort

Die HTTP-Antwort enthält einen der folgenden Statuscodes:

  • 200 – Erfolg. Die Antwortdaten sind ein Projektdetails Objekt.

  • 400 – Ungültige Anfrage. Diese Antwort kann darauf hindeuten, dass die Daten in Ihrer Anfrage ungültiges JSON sind.

  • 403 – Authentifizierungsfehler.

  • 500 – OpenTok-Serverfehler.

Beispiel

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

Den Status eines Projekt-API-Schlüssels ändern

Account-Administratoren können diese Methode nutzen, um den Status eines Projekts zu ändern. Der Status kann entweder „aktiv“ oder „ausgesetzt“ sein. Wenn der Status eines Projekts auf „ausgesetzt“ gesetzt ist, können Sie den API-Schlüssel des Projekts (und alle damit erstellten OpenTok-Sitzungen) nicht mehr verwenden.

Sie können den Status eines Projekts von „aktiv“ auf „ausgesetzt“ und wieder zurück ändern.

PUT an Partner

Senden Sie eine HTTP PUT-Anfrage an die folgende URL:

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

Wo <api_key> ist der API-Schlüssel des Projekts.

PUT-Header-Eigenschaften

Setzen Sie die Content-Type Kopfzeile zu application/json.

Authentifizieren Sie diesen API-Aufruf mithilfe eines benutzerdefinierten HTTP-Headers — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Setzen Sie diesen Header auf ein JWT-Token (siehe Authentifizierung). Beachten Sie, dass Sie das auf Account-Ebene API-Schlüssel und auf Account-Ebene API Geheimcode beim Erstellen des Tokens. Der API-Schlüssel und der Geheimcode auf Account-Ebene stehen ausschließlich registrierten Administratoren Ihres OpenTok-Accounts zur Verfügung.

PUT-Daten

Fügen Sie ein JSON-Objekt in der folgenden Form als Inhalt des Request-Bodys ein:

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

HTTP-Antwort

Die HTTP-Antwort enthält einen der folgenden Statuscodes:

  • 200 – Erfolg. Die Antwortdaten lauten Projektdetails Objekt.

  • 400 – Ungültige Anfrage. Diese Antwort kann darauf hindeuten, dass die Daten in Ihrer Anfrage ungültiges JSON sind.

  • 403 – Authentifizierungsfehler.

  • 500 – OpenTok-Serverfehler.

Beispiel

Im folgenden Beispiel wird der Status des Projekts „Acme“ auf „ausgesetzt“ gesetzt:

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

Ein Projekt löschen

Verwenden Sie diese Methode, um ein Projekt zu löschen. Dadurch wird die Verwendung des Projekt-API-Schlüssels (sowie aller damit erstellten OpenTok-Sitzungen) verhindert.

Sie können auch vorübergehend Die API eines Projekts sperren Schlüssel.

Anmerkung: Sie können ein Projekt auch auf Ihrem Vonage Video API-Konto Seite.

DELETE an Partner

Senden Sie eine HTTP-DELETE-Anfrage an die folgende URL:

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

Wo <api_key> ist der API-Schlüssel des Projekts.

DELETE-Header-Eigenschaften

Authentifizieren Sie diesen API-Aufruf mithilfe eines benutzerdefinierten HTTP-Headers — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Setzen Sie diesen Header auf ein JWT-Token (siehe Authentifizierung). Beachten Sie, dass Sie das auf Account-Ebene API-Schlüssel und auf Account-Ebene API Geheimcode beim Erstellen des Tokens. Der API-Schlüssel und der Geheimcode auf Account-Ebene stehen ausschließlich registrierten Administratoren Ihres OpenTok-Accounts zur Verfügung.

HTTP-Antwort

Die HTTP-Antwort enthält einen der folgenden Statuscodes:

  • 204 – Erfolg (kein Inhalt).
  • 403 – Authentifizierungsfehler.
  • 404 – Nicht gefunden. Für den angegebenen API-Schlüssel gibt es kein Projekt.
  • 500 – OpenTok-Serverfehler.

Beispiel

Im folgenden Beispiel wird ein Projekt gelöscht:

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

Informationen zu Projekten einholen

Verwenden Sie diese Methode, um einen Datensatz mit Projektdetails abzurufen, der das Projekt beschreibt (oder um die Datensätze für alle Projekte abzurufen). Siehe Projektdetails Objekt.

GET als Partner

Um Informationen zu einem bestimmten Projekt abzurufen, senden Sie eine GET-Anfrage an die folgende URL:

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

Wo <api_key> ist der API-Schlüssel für das Projekt.

Um Informationen zu all Ihren Projekten abzurufen, senden Sie eine GET-Anfrage an die folgende URL:

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

GET-Header-Eigenschaften

Authentifizieren Sie diesen API-Aufruf mithilfe eines benutzerdefinierten HTTP-Headers — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Setzen Sie diesen Header auf ein JWT-Token (siehe Authentifizierung). Beachten Sie, dass Sie das auf Account-Ebene API-Schlüssel und auf Account-Ebene API Geheimcode beim Erstellen des Tokens. Der API-Schlüssel und der Geheimcode auf Account-Ebene stehen ausschließlich registrierten Administratoren Ihres OpenTok-Accounts zur Verfügung.

HTTP-Antwort

Die HTTP-Antwort enthält einen der folgenden Statuscodes:

  • 200 – Erfolg. Die Antwortdaten bestehen aus dem Objekt „project details“ oder einem Array von „project details“-Objekten. Siehe Projektdetails Objekt.

  • 403 – Authentifizierungsfehler.

  • 404 – Nicht gefunden. Für den angegebenen API-Schlüssel gibt es kein Projekt.

  • 500 – OpenTok-Serverfehler.

### Beispiel

Das folgende Beispiel ruft Details zu einem bestimmten Projekt ab:

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

Die Antwort ist ein JSON Projektdetails Objekt.

Das folgende Beispiel ruft Details zu all Ihren Projekten ab:

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

Die Antwort ist ein Array aus Projektdetails Objekte.

Ein neues API-Geheimnis für ein Projekt generieren

Aus Sicherheitsgründen empfiehlt es sich, einen neuen API-Schlüssel für ein Projekt zu generieren.

Anmerkung: Verwenden Sie den neuen API-Schlüssel für alle REST-API-Aufrufe sowie mit den serverseitigen OpenTok-SDKs. Wenn Sie einen neuen API-Schlüssel generieren, werden alle bestehenden Kundenmünzen werden ungültig (und können nicht mehr zur Verbindung mit OpenTok-Sitzungen verwendet werden); verwenden Sie den neuen API-Schlüssel mit dem OpenTok-Server-SDK, um Client-Token zu generieren.

POST an refreshSecret

Senden Sie eine HTTP-POST-Anfrage an die folgende URL:

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

Wo <api_key> ist der API-Schlüssel des Projekts.

Eigenschaften des POST-Headers

Authentifizieren Sie diesen API-Aufruf mithilfe eines benutzerdefinierten HTTP-Headers — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Setzen Sie diesen Header auf ein JWT-Token (siehe Authentifizierung). Beachten Sie, dass Sie das auf Account-Ebene API-Schlüssel und auf Account-Ebene API Geheimcode beim Erstellen des Tokens. Der API-Schlüssel und der Geheimcode auf Account-Ebene stehen ausschließlich registrierten Administratoren Ihres OpenTok-Accounts zur Verfügung.

HTTP-Antwort

Die HTTP-Antwort enthält einen der folgenden Statuscodes:

  • 200 – Erfolg. Die Antwortdaten lauten Projektdetails Objekt, mit dem neuen API-Schlüssel.

  • 403 – Authentifizierungsfehler.

  • 404 – Nicht gefunden. Für den angegebenen API-Schlüssel gibt es kein Projekt.

  • 500 – OpenTok-Serverfehler.

Beispiel

Das folgende Beispiel generiert einen neuen API-Schlüssel für das Projekt:

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