Referência da Video API REST da Vonage

Use a API REST do OpenTok para gerar sessões do OpenTok, trabalhar com arquivos e realizar transmissões ao vivo. A SDKs de servidor do OpenTok (para Java, .NET, Node.js, PHP, Python, e Ruby) implementam muitos dos métodos da API REST.

A API REST inclui métodos para o seguinte:

Criação de sessões, sinalização e moderação

Arquivamento

Interconexão SIP

Transmissões ao vivo

Legendas em tempo real

Experiência com o Composer

Conector de áudio

Gerenciamento de contas

O SDKs do OpenTok criar uma camada de abstração para a API REST do OpenTok, a fim de facilitar as chamadas à plataforma OpenTok.

Autenticação

As chamadas à API REST devem ser autenticadas por meio de um cabeçalho HTTP personalizado — X-OPENTOK-AUTH — além de um Token JSON da Web. Crie o token JWT com as seguintes reivindicações:

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

Conjunto iss à sua chave de API do OpenTok. Para a maioria das chamadas à API REST, use a chave de API do projeto específico do seu Account. Ela está disponível na página “Projeto” do seu Account Account da Video API. No entanto, os seguintes métodos REST estão restritos aos administradores registrados da conta do OpenTok. Para utilizar esses métodos, é necessário definir iss para o no nível da conta Chave de API, disponível apenas para administradores de conta. (consulte Gerenciamento de contas):

Para obter a chave e o segredo da API no nível da Account, faça login na sua Account da Video API, clique em Configurações da conta no menu à esquerda e, em seguida, em API REST do OpenTok, clique em Visualizar chaves da conta.

Para a maioria das chamadas à API REST, defina ist para "project". No entanto, para o seguinte Gerenciamento de contas Métodos REST, conjunto ist para "account":

Conjunto iat até o timestamp da época Unix atual (quando o token foi criado), em segundos.

Conjunto exp até o prazo de validade do token. Por motivos de segurança, recomendamos que você utilize um prazo de validade próximo à hora de criação do token (por exemplo, 3 minutos após a criação) e que crie um novo token para cada chamada à API REST. O intervalo máximo permitido para o prazo de validade é de 5 minutos.

Conjunto jti para um identificador exclusivo do JWT. Isso é opcional. Consulte o Especificação do JSON Web Token para mais detalhes.

Use seu segredo da API do OpenTok como chave secreta do JWT e assine-o com o algoritmo de criptografia HMAC-SHA256. Para a maioria das chamadas à API REST, use o segredo da API do projeto específico em seu Account. Ele está disponível na página “Projeto” do seu Account Account da Video API. No entanto, os seguintes métodos REST estão restritos aos administradores registrados da conta do OpenTok. Para utilizar esses métodos, é necessário usar o no nível da conta API chave e segredo (que só está disponível para administradores da conta) como a chave secreta do JWT (consulte Gerenciamento de contas):

Por exemplo, o código Python a seguir cria um token que pode ser usado em uma chamada à API REST do OpenTok:

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

Substitua o my-OpenTok-API-key e my-OpenTok-API-secret com a chave da API e o segredo da API do OpenTok.

Observação: Antes do uso dos JSON Web Tokens, as chamadas à API REST do OpenTok eram autenticadas por meio de um cabeçalho HTTP personalizado: X-TB-PARTNER-AUTH com o valor definido como sua chave e seu segredo da API do OpenTok concatenados por dois pontos:

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

No entanto, essa forma de autenticação (usando X-TB-PARTNER-AUTH) é obsoleto, e agora você deve usar tokens JSON Web para autenticação. (O uso dessa forma de autenticação, considerada obsoleta, será descontinuado em julho de 2017.)

Criação de uma sessão

Gerar uma nova sessão.

URL do recurso:

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

Verbo de recurso:

POST

Propriedades do cabeçalho POST

As chamadas à API devem ser autenticadas por meio de um cabeçalho HTTP personalizado — X-OPENTOK-AUTH — juntamente com um token JSON da Web (JWT). Consulte Autenticação.

Defina o Content-Type cabeçalho para application/x-www-form-urlencoded:

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

Defina o Accept cabeçalho para application/json:

Accept:application/json

Parâmetros POST

archiveName

O nome a ser usado para os arquivos em sessões arquivadas automaticamente. Ao definir essa opção, o archiveMode a opção deve ser definida como always ou ocorrerá um erro. O nome do arquivo compactado pode ter até 80 caracteres. Devido a limitações de codificação, os seguintes caracteres especiais são convertidos em dois pontos (:): ~, -, _. Se você não definir um nome e o archiveMode a opção está definida como always, o nome do arquivo ficará em branco.

archiveResolution

A resolução dos arquivos em uma sessão com arquivamento automático. Os valores válidos são “480x640”, “640x480” (padrão), “720x1280”, “1280x720”, “1080x1920” e “1920x1080”. Ao definir essa opção, o archiveMode a opção deve ser definida como always ou ocorrerá um erro.

location

O endereço IP que a Video API da Vonage utilizará para posicionar a sessão em sua rede global. Se nenhuma indicação de localização for fornecida (o que é recomendado), a sessão utilizará um servidor de mídia com base na localização do primeiro cliente que se conectar à sessão. Passe uma indicação de localização somente se você souber a região geográfica geral (e um endereço IP representativo) e acreditar que o primeiro cliente a se conectar possa não estar nessa região. Especifique um endereço IP que seja representativo da localização geográfica da sessão.

p2p.preference

Definir como enabled se você preferir que os clientes tentem enviar fluxos de áudio e vídeo diretamente para outros clientes; defina como disabled para sessões que utilizam o OpenTok Media Router. (Opcional; a configuração padrão é disabled -- a sessão utiliza o OpenTok Media Router.)

O Roteador de mídia OpenTok oferece os seguintes benefícios:

  • O OpenTok Media Router pode reduzir o uso de largura de banda em sessões com vários participantes. (Quando a propriedade p2p.preference está definida como enabled, cada cliente deve enviar um fluxo de áudio e vídeo separado para cada cliente que o assina.)
  • O OpenTok Media Router pode melhorar a qualidade da experiência do usuário por meio de solução alternativa para áudio e recuperação de vídeo. Com esses recursos, se a conectividade de um cliente se deteriorar a ponto de não suportar o vídeo de uma transmissão à qual ele está inscrito, o vídeo é interrompido nesse cliente (sem afetar os demais clientes), e o cliente passa a receber apenas o áudio. Se a conectividade do cliente melhorar, o vídeo é restabelecido.
  • O OpenTok Media Router é compatível com o recurso de arquivamento, que permite gravar, salvar e recuperar sessões do OpenTok.

Com o p2p.preference Se a propriedade estiver definida como “habilitada”, a sessão tentará transmitir fluxos diretamente entre os clientes. Caso os clientes não consigam se conectar devido a restrições de firewall, a sessão utiliza o servidor TURN da OpenTok para retransmitir os fluxos de áudio e vídeo.

Exemplos de solicitações

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

O exemplo de linha de comando a seguir cria uma sessão que utiliza o OpenTok Media Router e especifica uma sugestão de localização:

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

O exemplo de linha de comando a seguir cria uma sessão que tenta transmitir fluxos diretamente entre clientes (sem utilizar o OpenTok Media Router):

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

O exemplo de linha de comando a seguir cria uma sessão arquivada automaticamente:

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

Exemplo de resposta

A resposta consiste em dados JSON no seguinte formato:

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

Observe que, se você não incluir o cabeçalho “Accept:application/json”, o formato da resposta será XML. Essa versão em XML da chamada à API está obsoleta.

A resposta HTTP apresentará o código de status 403 caso você insira uma chave da API do OpenTok ou um token JWT inválido.

A resposta HTTP apresenta o código de status 500, indicando um erro no servidor OpenTok.

Envio de um sinal do servidor do seu aplicativo para os clientes conectados

Use a API REST do Signal para enviar sinais a todos os participantes de uma sessão ativa do OpenTok ou a um cliente específico conectado a essa sessão. Os sinais enviados pelo servidor têm um from parâmetro no sinal recebido manipuladores nos clientes conectados à sessão. Para um sinal enviado por um participante da sessão, o from A propriedade é definida com o ID da conexão do cliente que enviou o sinal, mas, neste caso, não há nenhuma conexão associada.

Nos dois exemplos de sinal abaixo, o corpo da solicitação será usado para encaminhar tanto o type e data campos. Estes correspondem aos parâmetros de tipo e de dados passados aos manipuladores de sinal do cliente.

type

String. O comprimento máximo é de 128 bytes, e ela deve conter apenas letras (A-Z e a-z), Numbers (0-9), '-', '_' e '~'.

data

String. O comprimento máximo é de 8 kb.

Notificar todos os clientes conectados à sessão

Envie uma solicitação HTTP POST para o signal recurso da sessão:

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

Observação: Anteriormente, essa URL REST utilizava /partner (que agora está obsoleto) em vez de /project.

Identificar um cliente específico conectado à sessão

Envie uma solicitação HTTP POST para o signal recurso de um ID de conexão específico, pertencente à sessão:

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

Respostas a erros de sinalização

Os erros devem ser retornados na resposta como códigos de status HTTP:

  • 400 — Uma das propriedades do sinal — data, type, sessionId ou connectionId — é inválido.
  • 403 — Você não está autorizado a enviar o sinal. Verifique suas credenciais de autenticação.
  • 404 — O cliente especificado pelo connectionId A propriedade não está vinculada à sessão.
  • 413 — A sequência de caracteres do tipo excede o comprimento máximo (128 bytes), ou a sequência de dados excede o tamanho máximo (8 kB).

Em caso de erro, o corpo da resposta terá a seguinte aparência:

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

Forçar um endpoint do cliente a se desconectar de uma sessão

Seu servidor de aplicativos pode desconectar um cliente de uma sessão do OpenTok enviando uma solicitação HTTP DELETE ao recurso correspondente à conexão desse cliente:

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

Observação: Anteriormente, essa URL REST utilizava /partner (que agora está obsoleto) em vez de /project.

Respostas de erro

Os erros devem ser retornados na resposta como códigos de status HTTP:

  • 400 — Um dos argumentos — sessionId ou connectionId — é inválido.
  • 403 — Você não está autorizado a executar o comando `forceDisconnect`; verifique suas credenciais de autenticação.
  • 404 — O cliente especificado pelo connectionId A propriedade não está vinculada à sessão.

Em caso de erro, o corpo da resposta terá a seguinte aparência:

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

Obtendo informações sobre a transmissão

Use este método para obter informações sobre um stream do OpenTok (ou todos os streams de uma sessão).

Por exemplo, você pode chamar esse método para obter informações sobre as classes de layout utilizadas por uma transmissão do OpenTok. As classes de layout definem como a transmissão é exibida no layout de uma transmissão ao vivo. Para obter mais informações, consulte Atribuição de classes de layout de transmissão ao vivo às transmissões do OpenTok streams.

HTTP GET para session/stream

Para obter informações sobre a classe de layout de um stream específico, envie uma solicitação HTTP GET para a seguinte URL:

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

  • Substituir <apiKey> com sua chave da API do OpenTok.

  • Substituir <sessionId> com o ID da sessão.

  • Substituir <streamId> com o ID da transmissão.

Para obter informações sobre as classes de layout de todos os fluxos em uma sessão, envie uma solicitação HTTP GET para a seguinte URL (omitindo o ID do fluxo no final):

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

Propriedades do cabeçalho GET

Autentique esta chamada de API usando um cabeçalho HTTP personalizado — X-OPENTOK-AUTH — definido como um token JSON da Web. Consulte Autenticação.

Resposta

Ao obter informações sobre a classe de layout de um único fluxo, os dados JSON da resposta incluem um layoutClassList matriz:

{
  "id": "8b732909-0a06-46a2-8ea8-074e64d43422",
  "videoType": "camera",
  "name": "",
  "layoutClassList": ["full"]
}
  • O layoutClassList A propriedade é uma matriz das classes de layout do fluxo.
  • O id A propriedade é o ID do fluxo.
  • O videoType A propriedade está definida como “camera”, “screen” ou “custom”. Um vídeo “screen” utiliza o compartilhamento de tela no editor como fonte de vídeo; um vídeo “custom” é publicado por um cliente web usando um elemento VideoTrack em HTML como fonte de vídeo.
  • O name A propriedade é o nome do stream (caso tenha sido definido quando o cliente publicou o stream).

Ao obter informações sobre a classe de layout para múltiplos fluxos, os dados JSON da resposta incluem um items propriedade, que é uma matriz contendo informações de layout para os fluxos na sessão:

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

A resposta HTTP terá um dos seguintes códigos de status:

  • 200 — Sucesso.
  • 400 — Solicitação inválida. Essa resposta pode indicar que os dados da sua solicitação estão em formato JSON inválido. Ou pode indicar que você não forneceu um ID de sessão ou que forneceu um ID de stream inválido.
  • 403 — Você inseriu uma chave da API do OpenTok ou um token JWT inválido.
  • 404 — A sessão existe, mas ainda não tem nenhum stream adicionado a ela.
  • 408 — Você inseriu um ID de stream inválido.
  • 500 — Erro no servidor OpenTok.

Exemplo

O exemplo de linha de comando a seguir recupera informações sobre a classe de layout de um fluxo específico:

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
  • Defina o valor para api_key à sua chave da API do OpenTok.
  • Defina o valor para json_web_token para um token JSON da Web (consulte Autenticação).
  • Defina o session_id valor para a sessão.
  • Defina o stream_id valor ao ID do fluxo.

O exemplo de linha de comando a seguir recupera informações sobre as classes de layout de todos os fluxos em uma sessão:

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/
  • Defina o valor para api_key à sua chave da API do OpenTok.
  • Defina o valor para json_web_token para um token JSON da Web (consulte Autenticação).
  • Defina o session_id valor para a sessão.

Forçar o silenciamento do áudio publicado em uma única transmissão

Você pode usar a API REST do OpenTok para forçar o emissor de uma transmissão específica a silenciar o áudio.

POST para session/stream/mute

Envie uma solicitação HTTP POST para a seguinte URL:

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

Substituir <api_key> com a chave da API do projeto OpenTok (consulte a página do projeto do seu Account da Video API). Substituir <session_id> com o ID da sessão que contém o stream. Substitua <stream_id> com o ID da transmissão.

Propriedades do cabeçalho POST

Autentique esta chamada de API usando um cabeçalho HTTP personalizado — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Defina este cabeçalho como um token JWT (consulte Autenticação).

Resposta HTTP

A resposta HTTP terá um dos seguintes códigos de status:

  • 200 — Sucesso. Os dados da resposta são um detalhes do projeto objeto.

  • 400 — Solicitação inválida.

  • 403 — Erro de autenticação.

  • 404 — Não encontrado. A sessão ou o fluxo não foi encontrado.

  • 500 — Erro no servidor OpenTok.

Exemplo

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

Forçar as transmissões em uma sessão a silenciar o áudio publicado

Você pode usar a API REST do OpenTok para forçar todos os streams (exceto uma lista opcional de streams) em uma sessão a silenciar o áudio publicado. Você também pode usar esse método para desativar o estado de silenciamento forçado de uma sessão (veja abaixo).

POST para session/mute

Envie uma solicitação HTTP POST para a seguinte URL:

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

Substituir <api_key> com a chave da API do projeto OpenTok (consulte a página do projeto do seu Account da Video API). Substituir <session_id> com o ID da sessão.

Propriedades do cabeçalho POST

Defina o Content-Type cabeçalho para application/json.

Autentique esta chamada de API usando um cabeçalho HTTP personalizado — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Defina este cabeçalho como um token JWT (consulte Autenticação).

Dados POST

Inclua um objeto JSON no formato a seguir como conteúdo do corpo da solicitação:

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

Os dados JSON incluem as seguintes propriedades:

  • active (Booleano, obrigatório) — Se os streams da sessão devem ser silenciados (true) e ativar o modo mudo da sessão, ou desativar o modo mudo da sessão (false). Com o modo mudo ativado (true), todos os fluxos atuais e futuros publicados na sessão (com exceção dos fluxos no excludedStreamIds (matriz) são silenciados. Ao chamar esse método com o active propriedade definida como false, as transmissões futuras publicadas na sessão não serão silenciadas (mas as transmissões já silenciadas permanecerão assim).

  • excludedStreamIds (Matriz de strings, opcional) — Os IDs das transmissões que não devem ser silenciadas. Esta é uma propriedade opcional. Se você omitir essa propriedade, todas as transmissões da sessão serão silenciadas. Essa propriedade só se aplica quando o active a propriedade está definida como true. Quando o active a propriedade está definida como false, ele é ignorado.

    Os elementos no excludedStreamIds A matriz contém os IDs dos streams (cadeias de caracteres) que você deseja excluir do silenciamento.

    Caso não deseje incluir uma lista de fluxos excluídos, não inclua nenhum conteúdo no corpo da mensagem.

Resposta HTTP

A resposta HTTP terá um dos seguintes códigos de status:

  • 200 — Sucesso. Os dados da resposta são um detalhes do projeto objeto.

  • 400 — Solicitação inválida. Essa resposta pode indicar que os dados em sua solicitação estão no formato JSON inválido.

  • 403 — Erro de autenticação.

  • 404 — Não encontrado. A sessão não foi encontrada.

  • 500 — Erro no servidor OpenTok.

Exemplo

O comando a seguir força todas as transmissões (exceto uma lista opcional de transmissões) em uma sessão a silenciar o áudio publicado:

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

Para desativar o estado de mudo da sessão (para impedir que transmissões futuras sejam silenciadas), chame o método novamente com o active propriedade definida como 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

Listando conexões em uma sessão

Use este método para listar as conexões de uma sessão do OpenTok associada a um projeto.

HTTP GET para sessão/conexão

Envie uma solicitação HTTP GET para a seguinte URL:

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

Substituir <api_key> com sua chave da API do OpenTok. Consulte a página do projeto em seu Account da Video API.

Substituir <sessionId> com o ID da sessão que contém as conexões.

Você pode adicionar parâmetros de consulta opcionais para filtrar os resultados:

  • offset (número inteiro, opcional): O índice, com base em zero, da primeira conexão a ser retornada. O valor padrão é 0 (a conexão mais antiga).
  • count (inteiro, opcional): O número máximo de conexões a serem retornadas. O valor padrão é 50; o máximo é 1.000.

Por exemplo, a chamada a seguir recupera 20 conexões a partir da posição 400:

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

Propriedades do cabeçalho GET

As chamadas à API devem ser autenticadas por meio de um cabeçalho HTTP personalizado — X-OPENTOK-AUTH — juntamente com um token JSON da Web (JWT). Consulte Autenticação.

Resposta

Os dados brutos da resposta HTTP, com código de status 200, são uma mensagem codificada em JSON com o seguinte formato:

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

O objeto JSON inclui as seguintes propriedades:

  • contagem — O número total de conexões na sessão.
  • projectId — Sua chave da API do OpenTok.
  • sessionId — O ID da sessão.
  • itens — Uma matriz de objetos que define cada conexão recuperada. As conexões são listadas da mais antiga para a mais recente no conjunto de resultados.

Cada objeto na matriz `items` representa uma conexão e possui as seguintes propriedades:

  • connectionId — O ID da conexão.
  • connectionState — O estado da conexão:
    • "Conectando" — A conexão ainda está em fase de criação e não está totalmente estabelecida.
    • "Conectado" — A conexão está totalmente estabelecida e conectada à sessão.
  • createdAt — O carimbo de data/hora correspondente ao momento em que a conexão foi criada, expresso em milissegundos desde a época Unix (1º de janeiro de 1970, 00:00:00 UTC).

A resposta HTTP terá um dos seguintes códigos de status:

  • 200 — Sucesso. Os dados da resposta contêm a lista de conexões de uma sessão do OpenTok.
  • 400 — Solicitação inválida. Essa resposta pode indicar que algum parâmetro da sua consulta está inválido.
  • 403 — Erro de autenticação.
  • 404 — A sessão não foi encontrada.
  • 500 — Erro no servidor OpenTok.

Exemplo

Nos exemplos a seguir:

  • Defina o valor de API_KEY como sua chave da API do OpenTok.
  • Defina o valor de JWT como um token JSON válido (consulte Autenticação).
  • Defina o valor de SESSION_ID como o seu ID de sessão do OpenTok.

O exemplo de linha de comando a seguir recupera as primeiras 50 conexões da sessão:

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

O exemplo de linha de comando a seguir recupera a primeira conexão criada na sessão:

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

O exemplo de linha de comando a seguir recupera duas conexões, começando pela quinta conexão criada na sessão:

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

O próximo exemplo não retorna nenhuma conexão, já que o deslocamento é maior do que o número de conexões na sessão:

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

Migração de uma sessão

Utilize este método para migrar uma sessão para um servidor diferente, quando necessário. A migração só é possível se não houver nenhuma migração em andamento para a sessão e se a sessão não tiver sido criada ou migrada recentemente. (Consulte o Rotação de servidores e migração de sessões guia do desenvolvedor.)

Observação: Quando a migração for acionada, todas as conexões que possuírem a capacidade “migrate” serão migradas para o novo servidor. Quaisquer conexões que não possuírem a capacidade “migrate” serão encerradas como parte do processo de migração. (Consulte Ativação da migração de sessão nos clientes.)

URL do recurso:

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

Substituir <api_key> com a chave da API do projeto OpenTok (consulte a página do projeto do seu Account da Video API). Substituir <session_id> com o ID da sessão a ser migrada para outro servidor.

Verbo de recurso:

POST

Propriedades do cabeçalho POST

Defina o Content-Type cabeçalho para application/json.

Autentique esta chamada de API usando um cabeçalho HTTP personalizado — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Defina este cabeçalho como um token JWT (consulte Autenticação).

Resposta HTTP

Para algumas respostas de erro, além do código de resposta HTTP, o corpo da resposta inclui um code campo para indicar o motivo específico do erro. A resposta HTTP terá um dos seguintes códigos de status:

  • 202 — Aceito. A solicitação é válida e a sessão será migrada.

  • 400 — Solicitação inválida. Essa resposta pode indicar que faltam algumas informações na solicitação.

  • 403 — Erro de autenticação. Devido a um token não autorizado ou inválido

  • 404 — Não encontrado. A sessão não foi encontrada.

  • 409 — Conflito. A sessão não pode ser migrada neste momento. Isso pode ser devido a um dos seguintes motivos:

    • código 15214: Já está em andamento uma migração para a sessão.
    • código 15215: A sessão foi criada ou migrada recentemente.

  • 500 — Erro interno do servidor OpenTok.

Solicitação de amostra

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
  • Defina o valor para API_KEY à sua chave da API do OpenTok.
  • Defina o valor para JWT para um token JSON da Web (consulte Autenticação).
  • Defina o SESSION_ID valor correspondente ao ID da sessão a ser migrada.

Exemplo de resposta

Resposta de erro de autenticação:

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

Iniciando uma gravação de arquivo

Para iniciar a gravação de um arquivo de uma sessão do OpenTok, envie uma solicitação HTTP POST.

Para iniciar com sucesso a gravação de um arquivo, é necessário que pelo menos um cliente esteja conectado à sessão.

É possível gravar apenas arquivos de sessões que utilizem o OpenTok Media Router (com o modo de mídia definido como “routed”); não é possível arquivar sessões cujo modo de mídia esteja definido como “relayed”. (Consulte O OpenTok Media Router e os modos de mídia.)

Para obter mais informações, consulte o Guia do desenvolvedor sobre arquivamento do OpenTok.

POST HTTP para o arquivo

Envie uma solicitação HTTP POST para a seguinte URL:

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

Substituir <api_key> com sua chave da API do OpenTok. Consulte a página do projeto do seu Account da Video API.

Observação: Anteriormente, essa URL REST utilizava /partner (que agora está obsoleto) em vez de /project.

Propriedades do cabeçalho POST

As chamadas à API devem ser autenticadas por meio de um cabeçalho HTTP personalizado — X-OPENTOK-AUTH — juntamente com um token JSON da Web (JWT). Consulte Autenticação.

Defina o cabeçalho Content-type como application/json:

Content-Type:application/json

Dados POST

Inclua um objeto JSON no formato a seguir como dados da solicitação POST:

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

O objeto JSON inclui as seguintes propriedades:

  • sessionId (String) — (Obrigatório) O ID da sessão do OpenTok que você deseja começar a arquivar
  • hasAudio (Booleano) — (Opcional) Indica se o arquivo irá gravar áudio (true, valor padrão) ou não (false). Se você definir ambos hasAudio e hasVideo Se o valor for “false”, a chamada a este método resultará em um erro.
  • hasVideo (Booleano) — (Opcional) Indica se o arquivo irá gravar vídeo (true, valor padrão) ou não (false). Se você definir ambos hasAudio e hasVideo Se o valor for “false”, a chamada a este método resultará em um erro.
  • layout (Objeto) — Opcional. Especifique isso para atribuir o tipo de layout inicial ao arquivo. Isso se aplica apenas a arquivos organizados. Esse objeto possui três propriedades: type, stylesheet, e screenshareType, sendo cada um deles uma sequência de caracteres. Os valores válidos para o layout as propriedades são "bestFit" (melhor ajuste), "custom" (personalizado), "horizontalPresentation" (apresentação horizontal), "pip" (imagem na imagem), e "verticalPresentation" (apresentação vertical)). Se você especificar um "custom" tipo de layout, defina o stylesheet propriedade do layout atribuir a folha de estilo. (Para outros tipos de layout, não defina um stylesheet propriedade.) Defina o screenshareType propriedade que define o tipo de layout a ser usado quando houver uma transmissão de compartilhamento de tela na sessão. (Essa propriedade é opcional.) Observe que, se você definir a screenshareType propriedade, é necessário definir o type atribuir a propriedade “bestFit” e deixar o stylesheet Propriedade não definida. Se você não especificar um tipo de layout inicial, o arquivo utilizará o tipo de layout mais adequado. Para obter mais informações, consulte Personalização do layout do vídeo para arquivos compostos.
  • maxBitrate (opcional) — A taxa de bits máxima do vídeo para o arquivo, em bits por segundo. O valor mínimo é 100.000 e o máximo é 6.000.000. Essa opção é válida apenas para arquivos compostos. Defina a taxa de bits máxima de vídeo para controlar o tamanho do arquivo composto. Essa taxa de bits máxima se aplica apenas à taxa de bits de vídeo. Se o arquivo de saída contiver áudio, esses bits serão excluídos do limite. Ao definir a maxBitrate propriedade, o arquivo utiliza uma taxa de bits constante. Não é possível definir tanto a maxBitrate propriedade e o quantizationParameter propriedades — isso gera um erro.
  • multiArchiveTag (String) — (Opcional) Defina este parâmetro para permitir a gravação simultânea de vários arquivos para a mesma sessão. Defina uma string exclusiva para cada arquivo simultâneo de uma sessão em andamento. Você também deve definir esta opção ao iniciar manualmente um arquivo em uma sessão que esteja arquivado automaticamente. Se você não especificar um multiArchiveTag, só é possível gravar um arquivo por vez em uma determinada sessão. Consulte Arquivos simultâneos.
  • name (String) — (Opcional) O nome do arquivo (para sua própria identificação). O comprimento máximo do nome do arquivo é de 255 caracteres.
  • outputMode (String) — (Opcional) Indica se todos os fluxos do arquivo serão gravados em um único arquivo ("composed", o padrão) ou a arquivos específicos ("individual"). Veja Arquivos individuais e arquivos compostos.
  • quantizationParameter (Número) — (Opcional) O parâmetro de quantização (QP) para um arquivo composto, que ajusta o equilíbrio entre a qualidade do vídeo e o tamanho do arquivo. Definir o parâmetro de quantização faz com que o arquivo utilize uma taxa de bits variável e uma quantização de compressão constante, resultando em um nível de qualidade consistente ao longo das mudanças de cena. Os valores válidos variam de 15 a 40, e valores entre 20 e 30 produzem resultados razoáveis sem uma grande diferença perceptível na qualidade. Valores mais baixos de QP produzem uma quantização de compressão de vídeo mais fina, resultando em maior qualidade de vídeo (retendo mais detalhes) e um tamanho de arquivo maior. Valores mais altos de QP produzem uma quantização de compressão de vídeo mais grosseira, diminuindo a qualidade do vídeo e resultando em um tamanho de arquivo menor. Só é possível definir um parâmetro de quantização para um arquivo composto — a configuração quantizationParameter A tentativa de acessar o arquivo de um stream específico resulta em um erro. Não é possível definir tanto o quantizationParameter propriedade e o maxBitrate propriedade — isso gera um erro.
  • resolution (String) — (Opcional) A resolução do arquivo, que pode ser "640x480" (paisagem SD, a configuração padrão), "1280x720" (HD paisagem), "1920x1080" (FHD na orientação paisagem), "480x640" (retrato em SD), "720x1280" (retrato em HD), ou "1080x1920" (FHD retrato). Pode ser interessante usar uma proporção de tela retrato para arquivos que incluam transmissões de vídeo de dispositivos móveis (que geralmente utilizam a proporção de tela retrato). Essa propriedade se aplica apenas a arquivos compostos. Se você definir essa propriedade e definir a outputMode propriedade para "individual", a chamada ao método REST resulta em um erro.
  • streamMode (String) — (Opcional) Se os fluxos incluídos no arquivo são selecionados automaticamente ("auto", o padrão) ou manualmente ("manual"). Quando os fluxos são selecionados automaticamente ("auto"), todas as transmissões da sessão podem ser incluídas no arquivo. Quando as transmissões são selecionadas manualmente ("manual"), você especifica os fluxos a serem incluídos com base nas chamadas para esse método REST. É possível especificar se o áudio, o vídeo ou ambos de um fluxo serão incluídos no arquivo. Em arquivos compostos, tanto no modo automático quanto no manual, o criador de arquivos inclui os fluxos com base em regras de priorização de fluxos.

Os dados brutos da resposta HTTP, com código de status 200, são uma mensagem codificada em JSON com o seguinte formato:

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

O objeto JSON inclui as seguintes propriedades:

  • createdAt — O carimbo de data e hora do momento em que o arquivo começou a gravar, expresso em milissegundos desde a época Unix (1º de janeiro de 1970, 00:00:00 UTC).
  • hasAudio — Se o arquivo gravará áudio (verdadeiro) ou não (falso).
  • hasVideo — Se o arquivo gravará vídeo (verdadeiro) ou não (falso).
  • id — O ID exclusivo do arquivo. Salve esse valor para uso posterior (por exemplo, para parar a gravação).
  • multiArchiveTag — A tag exclusiva para arquivos simultâneos (caso tenha sido definida).
  • name — O nome do arquivo que você forneceu (isso é opcional).
  • outputMode — Ou "composed" ou "individual". Veja Arquivos individuais e arquivos compostos.
  • projectId — Sua chave da API do OpenTok.
  • resolution — A resolução do arquivo (seja “640x480”, “1280x720”, “1920x1080”, “480x640”, “720x1280” ou “1080x1920”). Essa propriedade é definida apenas para arquivos compostos.
  • sessionId — O ID da sessão do OpenTok que está sendo arquivada.
  • status — Isso está definido para "started".
  • streamMode — Se os streams incluídos no arquivo são selecionados automaticamente ("auto", o padrão) ou manualmente ("manual").
  • streams — Uma matriz de objetos correspondentes aos fluxos que estão sendo arquivados no momento. Esse valor só é definido para um arquivo com o status definir como "started" e o streamMode definir como "manual". Cada objeto da matriz possui as seguintes propriedades:
    • streamId — O ID do stream incluído no arquivo.
    • hasAudio — Se o áudio da transmissão está incluído no arquivo.
    • hasVideo — Se o vídeo da transmissão está incluído no arquivo.

A resposta HTTP apresenta um código de status 400 nos seguintes casos:

  • Você não forneceu um ID de sessão ou forneceu um ID de sessão inválido.
  • Não há clientes conectados ativamente à sessão do OpenTok.
  • Você especificou um valor inválido resolution valor.
  • O outputMode a propriedade está definida como "individual" e você define o resolution propriedade e (o que não é compatível com arquivos de stream individuais).
  • Você especificou um valor inválido maxBitrate valor ou você especificar um maxBitrate valor para um arquivo de stream específico. (maxBitrate (é compatível apenas com arquivos compostos.)
  • Você especificou um valor inválido quantizationParameter valor ou você especificar um quantizationParameter valor para um arquivo de stream específico. (quantizationParameter (é compatível apenas com arquivos compostos.)
  • Você especifica tanto um maxBitrate e um quantizationParameter propriedade.

A resposta HTTP apresentará o código de status 403 caso você insira uma chave da API do OpenTok ou um token JWT inválido.

A resposta HTTP apresenta o código de status 404 se a sessão não existir ou se a sessão existir, mas não houver clientes conectados a ela.

A resposta HTTP apresentará o código de status 409 caso você tente iniciar um arquivamento para uma sessão que não utilize o OpenTok Media Router. Ou caso você tente iniciar um arquivamento para uma sessão que já esteja sendo gravada sem definir o multiArchiveTag opção. Ou, se você tentar iniciar um arquivamento simultâneo para uma sessão sem definir um multiArchiveTag valor.

A resposta HTTP apresenta o código de status 500, indicando um erro no servidor OpenTok.

Exemplo

O exemplo de linha de comando a seguir inicia a gravação de um arquivo de uma sessão do OpenTok:

api_key=12345
json_web_token="jwt_string" # replace with a JSON web token (see "Authentication")
session_id=2_MX40NzIwMzJ-flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN-MC45NDQ2MzE2NH4
name="Foo"
data='{"sessionId" : "'$session_id'", "name" : "'$name'"}'
curl \
     -i \
     -H "Content-Type: application/json" \
     -X POST \
     -d $data \
     -H "X-OPENTOK-AUTH:$json_web_token" \
     https://api.opentok.com/v2/project/$api_key/archive
  • Defina o valor para api_key à sua chave da API do OpenTok.
  • Defina o valor para json_web_token para um token JSON da Web (consulte Autenticação).
  • Defina o session_id valor para o ID da sessão do OpenTok que você deseja arquivar.
  • Defina o name adicionar um valor ao nome do arquivo (isso é opcional).

Interromper uma gravação em arquivo

Para interromper a gravação de um arquivo, envie uma solicitação HTTP POST.

Os arquivos param de gravar após 4 horas (14.400 segundos), ou 60 segundos após o último cliente se desconectar da sessão, ou 60 minutos após o último cliente parar de publicar. No entanto, arquivos automáticos continue gravando em vários arquivos consecutivos com até 4 horas de duração cada. Para obter mais informações, consulte Período de arquivamento

Ao chamar esse método para arquivos automáticos não tem efeito. Os arquivos automáticos continuam gravando em vários arquivos consecutivos com duração de até 4 horas (14.400 segundos) cada, até 60 segundos após o último cliente se desconectar da sessão ou 60 minutos após o último cliente interromper a publicação de um stream na sessão.

POST HTTP para o arquivo

Envie uma solicitação HTTP POST para a seguinte URL:

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

Substituir <api_key> com sua chave da API do OpenTok. Consulte a página do seu projeto em seu Account da Video API.

Substituir <archive_id> com o ID do arquivo. Você pode obter o ID do arquivo na resposta à chamada da API para começar a gravar o arquivo.

Observação: Anteriormente, essa URL REST utilizava /partner (que agora está obsoleto) em vez de /project.

Propriedades do cabeçalho POST

As chamadas à API devem ser autenticadas por meio de um cabeçalho HTTP personalizado — X-OPENTOK-AUTH — juntamente com um token JSON da Web (JWT). Consulte Autenticação.

Resposta

Os dados brutos da resposta HTTP, com código de status 200, são uma mensagem codificada em JSON com o seguinte formato:

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

O objeto JSON inclui as seguintes propriedades:

  • createdAt — O carimbo de data e hora do momento em que o arquivo começou a gravar, expresso em milissegundos desde a época Unix (1º de janeiro de 1970, 00:00:00 UTC).
  • hasAudio — Se o arquivo gravará áudio (verdadeiro) ou não (falso).
  • hasVideo — Se o arquivo gravará vídeo (verdadeiro) ou não (falso).
  • id — O ID exclusivo do arquivo.
  • multiArchiveTag — A tag exclusiva para arquivos simultâneos (caso tenha sido definida).
  • outputMode — Ou "composed" ou "individual". Veja Arquivos individuais e arquivos compostos.
  • projectId — Sua chave da API do OpenTok.
  • resolution — A resolução do arquivo (seja “640x480”, “1280x720”, “1920x1080”, “480x640”, “720x1280” ou “1080x1920”). Essa propriedade é definida apenas para arquivos compostos.
  • sessionId — O ID da sessão do OpenTok que foi arquivada.
  • name — O nome do arquivo que você forneceu (isso é opcional)
  • size — Quando o arquivo é interrompido (e ainda não foi gerado), o tamanho é definido como 0.
  • status — Isso está definido para "stopped".
  • streamMode — Se os streams incluídos no arquivo são selecionados automaticamente ("auto", o padrão) ou manualmente ("manual").
  • streams — Uma matriz de objetos correspondentes aos fluxos que estão sendo arquivados no momento. Esse valor só é definido para um arquivo com o status definir como "started" e o streamMode definir como "manual". Cada objeto da matriz possui as seguintes propriedades:
    • streamId — O ID do stream incluído no arquivo.
    • hasAudio — Se o áudio da transmissão está incluído no arquivo.
    • hasVideo — Se o vídeo da transmissão está incluído no arquivo.

A resposta HTTP apresentará o código de status 400 caso você não forneça um ID de sessão ou forneça um ID de sessão inválido.

A resposta HTTP apresentará o código de status 403 caso você insira uma chave da API do OpenTok ou um token JWT inválido.

A resposta HTTP apresentará o código de status 404 caso você insira um ID de arquivo inválido.

A resposta HTTP apresentará o código de status 409 caso você tente interromper um arquivo que não esteja sendo gravado.

A resposta HTTP apresenta o código de status 500, indicando um erro no servidor OpenTok.

Exemplo

O exemplo de linha de comando a seguir interrompe a gravação de um arquivo de uma sessão do OpenTok:

api_key=123456
json_web_token="jwt_string" # replace with a JSON web token (see "Authentication")
id=b40ef09b-3811-4726-b508-e41a0f96c68f
curl \
     -i \
     -X POST \
     -H "X-OPENTOK-AUTH:$json_web_token" \
     https://api.opentok.com/v2/project/$api_key/archive/$id/stop
  • Defina o valor para api_key à sua chave da API do OpenTok.
  • Defina o valor para json_web_token para um token JSON da Web (consulte Autenticação).
  • Defina o id valor para o ID do arquivo. Você pode obter o ID do arquivo na resposta à chamada da API para começar a gravar o arquivo.

Arquivos de listagens

Para listar os arquivos associados à sua chave de API, tanto os concluídos quanto os em andamento, envie uma solicitação HTTP GET.

Observação: Os registros do arquivo ficam disponíveis por até 12 meses.

HTTP GET para o arquivo

Envie uma solicitação HTTP GET para a seguinte URL:

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

Substituir <api_key> com sua chave da API do OpenTok. Consulte a página do projeto em seu Account da Video API.

Observação: Anteriormente, essa URL REST utilizava /partner (que agora está obsoleto) em vez de /project.

Você pode adicionar parâmetros de consulta para filtrar os resultados (eles são opcionais):

  • Defina um offset parâmetros de consulta para especificar o deslocamento no índice do primeiro arquivo. 0 é o deslocamento do arquivo iniciado mais recentemente (excluindo arquivos excluídos). 1 é o deslocamento do arquivo iniciado antes do arquivo mais recente. O valor padrão é 0.

  • Defina um count parâmetro de consulta para limitar o número de arquivos a serem retornados. O número padrão de arquivos retornados é 50 (ou menos, se houver menos de 50 arquivos). O número máximo de arquivos que a chamada retornará é 1.000.

  • Defina um sessionId parâmetro de consulta para listar arquivos de uma ID de sessão específica. (Isso é útil ao listar vários arquivos para uma arquivada automaticamente sessão.)

Por exemplo, a chamada a seguir especifica um count e offset valores:

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

A chamada a seguir especifica um (falso) sessionId valor:

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

Os arquivos excluídos não são incluídos nos resultados desta chamada de API.

Substituir <api_key> com sua chave da API do OpenTok. Consulte a página do projeto em seu Account da Video API.

Propriedades do cabeçalho GET

As chamadas à API devem ser autenticadas por meio de um cabeçalho HTTP personalizado — X-OPENTOK-AUTH — juntamente com um token JSON da Web (JWT). Consulte Autenticação.

Resposta

Os dados brutos da resposta HTTP, com código de status 200, são uma mensagem codificada em JSON com o seguinte formato:

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

O objeto JSON inclui as seguintes propriedades:

  • count — O número total de arquivos associados à chave da API.
  • items — Uma matriz de objetos que define cada arquivo recuperado. Os arquivos são listados do mais recente ao mais antigo no conjunto de resultados.

Cada objeto de arquivo (item) possui as seguintes propriedades:

  • createdAt — O carimbo de data e hora do momento em que o arquivo começou a gravar, expresso em milissegundos desde a época Unix (1º de janeiro de 1970, 00:00:00 UTC).
  • duration — A duração do arquivo em segundos. Para arquivos que estão sendo gravados (com a propriedade “status” definida como “iniciado”), esse valor é definido como 0.
  • hasAudio — Se o arquivo gravará áudio (verdadeiro) ou não (falso).
  • hasVideo — Se o arquivo gravará vídeo (verdadeiro) ou não (falso).
  • id — O ID exclusivo do arquivo.
  • multiArchiveTag — A tag exclusiva para arquivos simultâneos (caso tenha sido definida).
  • name — O nome do arquivo que você forneceu (isso é opcional)
  • outputMode — Ou "composed" ou "individual". Veja Arquivos individuais e arquivos compostos.
  • projectId — Sua chave da API do OpenTok.
  • reason — Para arquivos com o status "stopped", isso pode ser definido como "maximum duration exceeded", "maximum idle time exceeded", "session ended", "user initiated". Para arquivos com o status "failed", isso pode ser definido como "failure".
  • sessionId — O ID da sessão do OpenTok que foi arquivada.
  • status — O status do arquivo:

    • "available" — O arquivo está disponível para download na nuvem da OpenTok.

    • "expired" — O arquivo não está mais disponível para download na nuvem da OpenTok.

    • "failed" — O arquivamento da gravação falhou.

    • "paused" — Quando um arquivamento é pausado, nada é gravado. O arquivamento é pausado se ocorrer qualquer uma das seguintes condições:

      • Nenhum cliente está publicando fluxos na sessão. Nesse caso, há um tempo limite de 60 minutos; após esse período, o arquivamento é interrompido e o status do arquivamento passa a ser "stopped".
      • Todos os clientes encerram a sessão. Após 60 segundos, o arquivamento é interrompido e o status do arquivamento passa a ser "stopped".

      Se um cliente retomar a publicação enquanto o arquivo estiver no estado “pausado”, a gravação do arquivo será retomada e o status voltará a ser "started".

    • "started" — O arquivo foi iniciado e está em processo de gravação.

    • "stopped" — O arquivo parou de gravar.

    • "uploaded" — O arquivo está disponível para download no bucket do S3 que você especificou em seu Account da Video API.

  • streamMode — Se os streams incluídos no arquivo são selecionados automaticamente ("auto", o padrão) ou manualmente ("manual").
  • resolution — A resolução do arquivo (seja “640x480”, “1280x720”, “1920x1080”, “480x640”, “720x1280” ou “1080x1920”). Essa propriedade é definida apenas para arquivos compostos.
  • size — O tamanho do arquivo compactado. Para arquivos compactados que ainda não foram gerados, esse valor é definido como 0.
  • streamMode — Se todas as transmissões estão incluídas no arquivo ("auto") ou você seleciona os fluxos a serem incluídos no arquivo ("manual"). Veja Seleção dos fluxos a serem incluídos em um arquivo.
  • streams — Uma matriz de objetos correspondentes aos fluxos que estão sendo arquivados no momento. Esse valor só é definido para um arquivo com o status definir como "started" e o streamMode definir como "manual". Cada objeto da matriz possui as seguintes propriedades:
    • streamId — O ID do stream incluído no arquivo.
    • hasAudio — Se o áudio da transmissão está incluído no arquivo.
    • hasVideo — Se o vídeo da transmissão está incluído no arquivo.
  • url — A URL de download do arquivo compactado disponível. Esse campo só é preenchido para um arquivo compactado cujo status esteja definido como "available"; para outros arquivos (incluindo aqueles com o status "uploaded") essa propriedade está definida como nula. A URL de download está ofuscada, e o arquivo fica disponível nessa URL apenas por 10 minutos. Para gerar uma nova URL, use a API REST para recuperação de informações do arquivo ou arquivos de listagens.

A resposta HTTP apresentará o código de status 403 caso você insira uma chave da API do OpenTok ou um token JWT inválido.

A resposta HTTP apresenta o código de status 500, indicando um erro no servidor OpenTok.

Exemplo

O exemplo de linha de comando a seguir recupera informações sobre todos os arquivos:

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
  • Defina o valor para api_key à sua chave da API do OpenTok.
  • Defina o valor para json_web_token para um token JSON da Web (consulte Autenticação).

Recuperação de informações do arquivo

Para obter informações sobre um arquivo específico, envie uma solicitação HTTP GET.

Observação: Os registros do arquivo ficam disponíveis por até 12 meses.

Você também pode obter informações sobre vários arquivos. Consulte Arquivos de listagens.

HTTP GET para o arquivo

Envie uma solicitação HTTP GET para a seguinte URL:

https://api.opentok.com/v2/project/<api_key>/archive/<archive_id>
  • Substituir <api_key> com sua chave da API do OpenTok. Consulte a página do projeto do seu Account da Video API.
  • Substituir <archive_id com o ID do arquivo.

Observação: Anteriormente, essa URL REST utilizava /partner (que agora está obsoleto) em vez de /project.

Propriedades do cabeçalho GET

As chamadas à API devem ser autenticadas por meio de um cabeçalho HTTP personalizado — X-OPENTOK-AUTH — juntamente com um token JSON da Web (JWT). Consulte Autenticação.

Resposta

Os dados brutos da resposta HTTP, com código de status 200, são uma mensagem codificada em JSON com o seguinte formato:

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

O objeto JSON inclui as seguintes propriedades:

  • createdAt — O carimbo de data e hora do momento em que o arquivo começou a gravar, expresso em milissegundos desde a época Unix (1º de janeiro de 1970, 00:00:00 UTC).
  • duration — A duração do arquivo em segundos. Para arquivos que estão sendo gravados (com a propriedade “status” definida como “iniciado”), esse valor é definido como 0.
  • hasAudio — Se o arquivo gravará áudio (verdadeiro) ou não (falso).
  • hasVideo — Se o arquivo gravará vídeo (verdadeiro) ou não (falso).
  • id — O ID exclusivo do arquivo.
  • multiArchiveTag — A tag exclusiva para arquivos simultâneos (caso tenha sido definida).
  • name — O nome do arquivo que você forneceu (isso é opcional)
  • outputMode — Ou "composed" ou "individual". Veja Arquivos individuais e arquivos compostos.
  • projectId — Sua chave da API do OpenTok.
  • reason — Para arquivos com o status "stopped", isso pode ser definido como "maximum duration exceeded", "maximum idle time exceeded", "session ended", "user initiated". Para arquivos com o status "failed", isso pode ser definido como "failure".
  • resolution — A resolução do arquivo (seja “640x480”, “1280x720”, “1920x1080”, “480x640”, “720x1280” ou “1080x1920”). Essa propriedade é definida apenas para arquivos compostos.
  • sessionId — O ID da sessão do OpenTok que foi arquivada.
  • status — O status do arquivo:

    • "available" — O arquivo está disponível para download na nuvem da OpenTok.

    • "deleted" — O arquivo foi excluído.

    • "expired" — O arquivo não está mais disponível para download na nuvem da OpenTok.

    • "failed" — O arquivamento da gravação falhou.

    • "paused" — Quando um arquivamento é pausado, nada é gravado. O arquivamento é pausado se ocorrer qualquer uma das seguintes condições:

      • Nenhum cliente está publicando fluxos na sessão. Nesse caso, há um tempo limite de 60 minutos; após esse período, o arquivamento é interrompido e o status do arquivamento passa a ser "stopped".
      • Todos os clientes encerram a sessão. Após 60 segundos, o arquivamento é interrompido e o status do arquivamento passa a ser "stopped".

      Se um cliente retomar a publicação enquanto o arquivo estiver no "paused" nesse estado, a gravação do arquivo é retomada e o status volta a ser "started".

    • "started" — O arquivo foi iniciado e está em processo de gravação.

    • "stopped" — O arquivo parou de gravar.

    • "uploaded" — O arquivo está disponível para download no bucket do S3 que você especificou em seu Account da Video API.

  • size — O tamanho do arquivo compactado. Para arquivos compactados que ainda não foram gerados, esse valor é definido como 0.
  • streamMode — Se todas as transmissões estão incluídas no arquivo ("auto") ou você seleciona os fluxos a serem incluídos no arquivo ("manual"). Veja Seleção dos fluxos a serem incluídos em um arquivo.
  • streams — Uma matriz de objetos correspondentes aos fluxos que estão sendo arquivados no momento. Esse valor só é definido para um arquivo cujo status esteja definido como "started" e o streamMode definir como "manual". Cada objeto da matriz possui as seguintes propriedades:
    • streamId — O ID do stream incluído no arquivo.
    • hasAudio — Se o áudio da transmissão está incluído no arquivo.
    • hasVideo — Se o vídeo da transmissão está incluído no arquivo.
  • url — A URL de download do arquivo compactado disponível. Esse campo só é preenchido para um arquivo compactado cujo status esteja definido como "available"; para outros arquivos (incluindo aqueles com o status "uploaded") essa propriedade está definida como nula. A URL de download está ofuscada, e o arquivo fica disponível nessa URL apenas por 10 minutos. Para gerar uma nova URL, use a API REST para recuperação de informações do arquivo ou arquivos de listagens.

A resposta HTTP apresentará o código de status 400 caso você não forneça um ID de sessão ou forneça um ID de arquivo inválido.

A resposta HTTP apresentará o código de status 403 caso você insira uma chave da API do OpenTok ou um token JWT inválido.

A resposta HTTP apresenta o código de status 500, indicando um erro no servidor OpenTok.

Exemplo

O exemplo de linha de comando a seguir recupera informações sobre um arquivo:

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
  • Defina o valor para api_key à sua chave da API do OpenTok.
  • Defina o valor para json_web_token para um token JSON da Web (consulte Autenticação).
  • Defina o id valor para o ID do arquivo.

Excluindo um arquivo

Para excluir um arquivo, envie uma solicitação HTTP DELETE.

Só é possível excluir um arquivo cujo status seja "available" ou "uploaded". Ao excluir um arquivo, seu registro é removido da lista de arquivos (consulte Arquivos de listagens). Para um "available" arquivo, além de excluir o arquivo em si, tornando-o indisponível para download.

HTTP DELETE para arquivar

Envie uma solicitação HTTP DELETE para a seguinte URL:

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

Substituir <api_key> com sua chave da API do OpenTok. Consulte a página do projeto do seu Account da Video API.

Substituir <archive_id> com o ID do arquivo.

Observação: Anteriormente, essa URL REST utilizava /partner (que agora está obsoleto) em vez de /project.

Excluir propriedades do cabeçalho

As chamadas à API devem ser autenticadas por meio de um cabeçalho HTTP personalizado — X-OPENTOK-AUTH — juntamente com um token JSON da Web (JWT). Consulte Autenticação.

Resposta

Uma resposta HTTP com o código de status 204 indica que o arquivo foi excluído.

A resposta HTTP apresentará o código de status 403 caso você insira uma chave da API do OpenTok inválida, um token JWT inválido ou um ID de arquivo inválido.

A resposta HTTP apresenta o código de status 409 se o status do arquivo não for "uploaded", "available", ou "deleted".

A resposta HTTP apresenta o código de status 500, indicando um erro no servidor OpenTok.

Exemplo

O exemplo de linha de comando a seguir exclui um arquivo:

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
  • Defina o valor para api_key à sua chave da API do OpenTok.
  • Defina o valor para json_web_token para um token JSON da Web (consulte Autenticação).
  • Defina o id valor correspondente ao ID do arquivo a ser excluído.

Como definir um destino de upload para arquivamento no S3 ou no Azure

Em um projeto do OpenTok, é possível fazer com que o OpenTok envie arquivos compactados concluídos para um bucket do Amazon S3 (ou um provedor de armazenamento compatível com o S3) ou para um contêiner do Windows Azure.

Observação: Você também pode definir um destino para o envio de arquivos no seu Account da Video API da Vonage página.

Para o Amazon S3, você precisará conceder à Vonage permissão apenas para upload no bucket do Amazon S3. Se desejar utilizar um usuário IAM do S3, atribua a ele a seguinte política de usuário:

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

Para definir um destino de envio de arquivos, envie uma solicitação HTTP PUT.

Se você definir um destino para o upload, cada arquivo compactado concluído será enviado como um arquivo chamado archive.mp4 no caminho /projectKey/archiveId/ do bucket de destino, onde projectKey é a chave da API do projeto, e archiveId é o ID do arquivo.

Se você já definiu um destino de envio de arquivos para os arquivos de um projeto, pode enviar outra solicitação PUT para registrar um novo destino de envio.

Para obter mais informações sobre arquivamento, consulte o programação de arquivamento guia.

HTTP PUT para arquivar

Envie uma solicitação HTTP PUT para a seguinte URL:

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

Substituir <api_key> com a chave de API do projeto OpenTok.

Propriedades do cabeçalho PUT

Autentique esta chamada de API usando um cabeçalho HTTP personalizado — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Defina este cabeçalho como um token JWT (consulte Autenticação).

Defina o Content-type cabeçalho para application/json:

Content-Type:application/json

Dados de PUT

Para um bucket do Amazon S3, inclua um objeto JSON no formato a seguir como dados da solicitação PUT:

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

O objeto JSON inclui as seguintes propriedades:

  • type — "s3" (para o Amazon S3)

  • config — Configurações do Account da Amazon Web Services:

  • accessKey — A chave de acesso do Amazon Web Services

  • secretKey — A chave secreta do Amazon Web Services

  • bucket — O nome do bucket do S3.

  • endpoint (opcional) — Um endpoint do S3. Isso é opcional. O endpoint padrão é http://s3.amazonaws.com (o endpoint do Amazon S3). Especifique isso se desejar utilizar uma solução de armazenamento compatível com o S3 (que não seja o Amazon S3). Defina aqui a URL base do endpoint, incluindo o protocolo (http ou https), como, por exemplo, "https://s3.cloudianhyperstore.com" ou "https://storage.googleapis.com". Oferecemos suporte ao Cloudian e ao Google Cloud Storage (acessado por meio da API do AWS S3) como soluções de armazenamento compatíveis com o S3. Outros serviços compatíveis com o S3 podem apresentar limitações de recursos.

  • fallback — Defina isso como "opentok" para que o arquivo fique disponível no painel do OpenTok caso o upload falhe. Defina isso como "none" (ou omitir a propriedade) para impedir que os arquivos de arquivo sejam armazenados na nuvem da OpenTok caso o upload falhe.

Para um contêiner do Windows Azure, inclua um objeto JSON no formato a seguir como os dados da solicitação PUT:

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

O objeto JSON inclui as seguintes propriedades:

  • type — "azure" (para o Microsoft Azure)

  • config — Configurações do Account do Windows Azure:

  • accountName — O nome da conta do Windows Azure

  • accountKey — A chave do Account do Windows Azure

  • container — O nome do contêiner do Windows Azure.

  • domain (opcional) — O domínio do Windows Azure no qual o contêiner está localizado.

  • fallback — Defina isso como "opentok" para que o arquivo fique disponível no painel do OpenTok caso o upload falhe. Defina isso como "none" (ou omita a propriedade) para impedir que os arquivos de arquivo sejam armazenados na nuvem da OpenTok caso o envio falhe.

Resposta HTTP

A resposta HTTP terá um dos seguintes códigos de status:

  • 200 — Sucesso. O corpo da resposta corresponde aos dados que você enviou.

  • 400 — Solicitação inválida. Essa resposta pode indicar o seguinte:

  • O tipo não está definido.

  • Esse tipo não é compatível (não é "s3" ou "azure").

  • A configuração não está definida.

  • O valor da configuração excede o limite de tamanho. Nós criptografamos a configuração ao armazená-la, e o tamanho da criptografia não pode ultrapassar 2.048 caracteres.

  • Os dados da sua solicitação contêm JSON inválido.

    • 403 — Erro de autenticação. Você inseriu um token inválido no X-OPENTOK-AUTH cabeçalho.

Exemplo

O exemplo de linha de comando a seguir define um bucket do S3 para um projeto:

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

  • Defina o valor para token para um token JWT válido do OpenTok.

  • Defina o valor para projectKey à chave de API do projeto.

  • Defina o storage_type valor para "s3".

  • Defina o access_key valor para a chave de acesso do seu Account da Amazon Web Services .

  • Defina o secret_key valor da chave secreta do seu Account da Amazon Web Services .

  • Defina o bucket valor ao nome do bucket.

Exclusão de um destino de upload para arquivamento

Se você tiver definido um destino de envio de arquivos compactados para os arquivos compactados de um projeto, é possível excluí-lo.

Observação: Você também pode excluir um destino de envio de arquivos no seu Account da Video API da Vonage página.

HTTP DELETE para arquivar

Envie uma solicitação HTTP DELETE para a seguinte URL:

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

Substituir <project_key> com a chave de API do projeto.

Excluir propriedades do cabeçalho

Autentique esta chamada de API usando um cabeçalho HTTP personalizado — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Defina este cabeçalho como um token JWT (consulte Autenticação).

Resposta

A resposta HTTP terá um dos seguintes códigos de status:

  • 204 — Sucesso (sem conteúdo).

  • 403 — Erro de autenticação. Você inseriu um token inválido no cabeçalho X-OPENTOK-AUTH.

  • 404 — Não existe nenhum destino para o upload.

### Exemplo

O exemplo de linha de comando a seguir exclui um destino de upload de um projeto:

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

  • Defina o valor para token para um token JWT válido do OpenTok.

  • Defina o valor para projectKey à chave de API do projeto.

Alteração dinâmica do tipo de layout de um arquivo composto

É possível alterar dinamicamente o tipo de layout de um arquivo composto enquanto ele está sendo gravado.

Para obter mais informações sobre o arquivamento composto, consulte o Guia do desenvolvedor sobre arquivamento do OpenTok e Personalização do layout do vídeo para arquivos compostos.

HTTP PUT para arquivar

Envie uma solicitação HTTP PUT para a seguinte URL:

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

Substituir <apiKey> com sua chave da API do OpenTok.

Substituir <archiveId> com o ID do arquivo.

Propriedades do cabeçalho PUT

Defina o Content-Type cabeçalho para application/json.

Autentique esta chamada de API usando um cabeçalho HTTP personalizado — X-OPENTOK-AUTH — definido como um token JSON da Web. Consulte Autenticação.

Dados de PUT

Inclua um objeto JSON no formato a seguir como conteúdo do corpo da solicitação:

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

O objeto JSON inclui as seguintes propriedades:

  • tipo (String) — O tipo de layout do arquivo. Os valores válidos são "bestFit" (melhor ajuste), "custom" (personalizado), "horizontalPresentation" (apresentação horizontal), "pip" (imagem na imagem) e "verticalPresentation" (apresentação vertical). Se você especificar um "custom" tipo de layout, defina o stylesheet propriedade à folha de estilo. (Para outros tipos de layout, não defina a stylesheet propriedade.) Para obter mais informações, consulte Personalização do layout do vídeo para arquivos compostos.

    Ao especificar um tipo de layout diferente do tipo “Best Fit”, certifique-se de aplicar as classes de layout adequadas para os fluxos na sessão do OpenTok (consulte Atribuição de classes de layout de transmissão ao vivo às transmissões do OpenTok streams).

  • folha de estilo (String) — Opcional. Especifique isso somente se você definir o type propriedade para "custom". Defina o stylesheet propriedade à folha de estilo. (Para outros tipos de layout, não defina a stylesheet propriedade.) Para obter mais informações, consulte Definindo layouts personalizados.

  • tipo de compartilhamento de tela (String) — Opcional. O tipo de layout a ser usado quando houver uma transmissão de compartilhamento de tela na sessão. Observe que, para usar essa propriedade, é necessário definir o type atribuir a propriedade “bestFit” e deixar o stylesheet propriedade não definida. Para obter mais informações, consulte Tipos de layout para compartilhamento de tela.

Resposta

A resposta HTTP terá um dos seguintes códigos de status:

  • 200 — Sucesso.
  • 400 — Solicitação inválida. Essa resposta pode indicar que os dados da sua solicitação estão em formato JSON inválido. Também pode indicar que você passou opções de layout inválidas.
  • 403 — Erro de autenticação.
  • 500 — Erro no servidor OpenTok.

Exemplo

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

Alteração das classes de layout do arquivo composto para um stream do OpenTok

Use este método para alterar as classes de layout de uma transmissão do OpenTok. As classes de layout definem como a transmissão é exibida no layout de um arquivo composto do OpenTok. Para obter mais informações, consulte Atribuição de classes de layout de transmissão ao vivo às transmissões do OpenTok streams.

HTTP PUT para transmissão

Envie uma solicitação HTTP PUT para a seguinte URL:

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

Substituir <apiKey> com sua chave da API do OpenTok. Substitua <sessionId> com o ID da sessão.

Propriedades do cabeçalho PUT

Defina o Content-Type cabeçalho para application/json.

Autentique esta chamada de API usando um cabeçalho HTTP personalizado — X-OPENTOK-AUTH — definido como um token JSON da Web. Consulte Autenticação.

Dados de PUT

Inclua um objeto JSON no formato a seguir como conteúdo do corpo da solicitação:

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

O objeto JSON inclui um items matriz de objetos. Cada objeto define as classes de layout a serem atribuídas a um fluxo e contém as seguintes propriedades:

  • id (String) — O ID do fluxo.
  • layoutClassList (Matriz) — Uma matriz de classes de layout (cada uma representada por uma string) para o fluxo.

É possível atualizar a lista de classes de layout para vários fluxos passando vários objetos JSON no items matriz.

Resposta

A resposta HTTP terá um dos seguintes códigos de status:

  • 200 — Sucesso.
  • 400 — Solicitação inválida. Essa resposta pode indicar que os dados da sua solicitação estão em formato JSON inválido. Também pode indicar que você passou opções de layout inválidas.
  • 403 — Erro de autenticação.
  • 500 — Erro no servidor OpenTok.

Exemplo

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

Seleção dos fluxos a serem incluídos em um arquivo

Use este método para alterar os fluxos incluídos em um arquivo composto que foi iniciado com o comando streamMode definir como "manual" (ver Iniciando uma gravação de arquivo).

O compositor de arquivos inclui fluxos adicionados com base em regras de priorização de fluxos.

HTTP PATCH para archive/streams

Envie uma solicitação HTTP PATCH para a seguinte URL:

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

Substituir <apiKey> com sua chave da API do OpenTok. Substitua <archiveId> com o ID do arquivo.

Propriedades do cabeçalho PATCH

Defina o Content-Type cabeçalho para application/json.

Autentique esta chamada de API usando um cabeçalho HTTP personalizado — X-OPENTOK-AUTH — definido como um token JSON da Web. Consulte Autenticação.

Dados do PATCH

Para adicionar um stream ao arquivo, inclua um objeto JSON no formato a seguir como conteúdo do corpo da solicitação:

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

O objeto JSON contém as seguintes propriedades:

  • addStream (String) — O ID do fluxo.
  • hasAudio (Booleano, opcional) — Se o arquivo resultante deve incluir o áudio do stream (true, o padrão) ou não (false).
  • hasVideo (Booleano, opcional) — Se o arquivo resultante deve incluir o vídeo do stream (true, o padrão) ou não (false).

Você pode chamar o método repetidamente com addStream definido com o mesmo ID da transmissão, para ativar ou desativar o áudio ou o vídeo da transmissão no arquivo.

Se você definir ambos hasAudio e hasVideo para false, você receberá uma resposta de erro.

Para impedir que um stream seja incluído no arquivo, inclua um objeto JSON no formato a seguir como conteúdo do corpo da solicitação:

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

Defina o removeStream propriedade associada ao ID do fluxo.

Resposta

A resposta HTTP terá um dos seguintes códigos de status:

  • 204 — Sucesso (sem conteúdo).
  • 400 — Solicitação inválida. Essa resposta pode indicar que os dados fornecidos em sua solicitação estão em formato JSON inválido ou que a solicitação não pôde ser atendida porque o arquivo foi iniciado com streamMode definir como "auto", que não oferece suporte à manipulação de fluxos.
  • 403 — Erro de autenticação.
  • 404 — Arquivo ou transmissão não encontrado(a).
  • 500 — Erro no servidor OpenTok.

Exemplos

Adicionando um stream a um arquivo:

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

Remover o vídeo de uma transmissão em um arquivo (mas mantendo o áudio):

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

Removendo um stream de um arquivo:

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

Iniciando uma chamada SIP

Para conectar sua plataforma SIP a uma sessão do OpenTok, envie uma solicitação HTTP POST para o dial método. O áudio proveniente do seu lado da chamada SIP é adicionado à sessão do OpenTok como um fluxo exclusivamente de áudio. O OpenTok Media Router mixa o áudio de outros fluxos da sessão e envia o áudio mixado para o seu terminal SIP.

A chamada é encerrada quando o seu servidor SIP envia um BYE mensagem (para encerrar a chamada). Você também pode encerrar uma chamada usando o método da API REST do OpenTok para desconectar um cliente de uma sessão. O gateway SIP da OpenTok encerra automaticamente uma chamada após 5 minutos de inatividade (5 minutos sem recepção de mídia). Além disso, como medida de segurança, o gateway SIP da OpenTok encerra qualquer chamada SIP que dure mais de 6 horas.

O recurso de interconexão SIP exige que você utilize uma sessão do OpenTok que utilize o Roteador de mídia OpenTok (uma sessão com o modo de mídia configurado como “roteado”).

Para obter mais informações, incluindo detalhes técnicos e considerações de segurança, consulte o Interconexão SIP da OpenTok guia do desenvolvedor.

POST HTTP para discar

Envie uma solicitação HTTP POST para a seguinte URL:

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

Substituir <api_key> com sua chave da API do OpenTok. Consulte a página do projeto do seu Account da Video API.

Observação: Anteriormente, essa URL REST utilizava /partner (que agora está obsoleto) em vez de /project.

Propriedades do cabeçalho POST

As chamadas à API devem ser autenticadas por meio de um cabeçalho HTTP personalizado — X-OPENTOK-AUTH — juntamente com um token JSON da Web (JWT). Consulte Autenticação.

Defina o cabeçalho Content-type como application/json:

Content-Type:application/json

Dados POST

Inclua um objeto JSON no formato a seguir como dados da solicitação POST:

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

O objeto JSON inclui as seguintes propriedades:

  • sessionId​ (obrigatório) — O ID da sessão do OpenTok para a chamada SIP à qual se deseja ingressar.
  • token​ (obrigatório) — O token do OpenTok a ser usado para o participante que está sendo chamado. Você pode adicionar um token data para identificar se o participante está em um terminal SIP ou para obter outros dados de identificação, como números de telefone. (As bibliotecas de clientes do OpenTok incluem propriedades para analisar os dados de conexão de um cliente conectado a uma sessão.) Consulte o Criação de tokens guia do desenvolvedor.

  • SIP uri​ ​(obrigatório) — O URI SIP a ser usado como destino da chamada SIP iniciada pelo OpenTok para sua plataforma SIP.

    Se o SIP ​uri​ contém um ​transport=tls​ cabeçalho, a negociação entre a Vonage e o terminal SIP será realizada de forma segura. Observe que isso se aplica apenas à negociação em si, e não à transmissão de áudio. Se você também quiser que a transmissão de áudio seja criptografada, defina o ​secure​ propriedade para ​true​.

    Este é um exemplo de negociação de chamada segura:

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

    Este é um exemplo de negociação de chamada não segura:

    "sip:user@sip.partner.com"

  • from ​(opcional): O número ou sequência de caracteres que será enviada ao número SIP final como identificador do chamador. Deve ser uma sequência de caracteres no formato from@example.com, onde from pode ser uma sequência composta por caracteres alfabéticos (a-z, A-Z, 0-9) ou pelos caracteres _, +, !, %, `, ', ~, ou -.

    Se from é definido como um número (por exemplo, "<14155550101@example.com>"), ele aparecerá como o número de origem nos telefones da rede PSTN. Se from não está definido ou está definido como uma string (por exemplo, "<joe@example.com>"), +00000000 aparecerá como o número de origem nos telefones da rede PSTN.

    Se from não está definido ou está definido como uma string (por exemplo, "<joe@example.com>"), ou seja, um número não reconhecido ou não autorizado, na maioria dos casos ele será convertido para "Unknown" antes que a solicitação seja encaminhada a uma operadora para terminação na PSTN por provedores SIP. Dependendo do provedor, "Unknown" aparecerá como o número de origem nos telefones PSTN. Em alguns casos, as operadoras podem rejeitar essas chamadas por motivos de segurança, para evitar problemas como a falsificação de números. Caso a chamada não seja rejeitada pelas operadoras, +00000000 aparecerá como o número de origem nos telefones PSTN.

    Um número é considerado não reconhecido quando não está em conformidade com a norma E.164 ou não é um Número virtual da Vonage se estiver conectando ao Voice API da Vonage, por exemplo.

  • SIP headers​​ (opcional) — Este objeto define cabeçalhos personalizados a serem adicionados ao SIP ​INVITE​ solicitação iniciada pelo OpenTok para sua plataforma SIP.

  • SIP auth​ (opcional) — Este objeto contém o nome de usuário e a senha a serem utilizados no SIP INVITE​ solicitação de autenticação HTTP Digest, caso seja exigida pela sua plataforma SIP.

  • secure​ (opcional) — Um sinalizador booleano que indica se a mídia deve ser transmitida criptografada (​true​) ou não (​false​, o padrão).

  • video (opcional) — Um indicador booleano que indica se a chamada SIP incluirá vídeo (​true​) ou não (​false​, o padrão). Quando o vídeo está incluído, o vídeo do cliente SIP é incorporado ao fluxo do OpenTok enviado para a sessão do OpenTok. O vídeo SIP está limitado a 480p a 800 kbps. O cliente SIP receberá um único vídeo composto a partir dos fluxos publicados na sessão do OpenTok.

  • observeForceMute (opcional) Um indicador booleano que indica se o ponto final SIP observa moderação com silenciamento forçado (true) ou não (false, o padrão). Além disso, com observeForceMute definir como true, o chamador pode pressionar “*6” para ativar ou desativar o som do áudio transmitido. Para que a função de ativação/desativação de som com “*6” funcione, o chamador SIP deve negociar DTMFs conforme a RFC 2833 (dígitos RFC 2833/RFC 4733). A função de ativação/desativação do mudo não é compatível com SIP INFO ou DTMFs em banda. Uma mensagem (em inglês) é reproduzida para o chamador quando ele ativa ou desativa o mudo, ou quando o cliente SIP é silenciado por meio de uma ação de silenciamento forçado.

  • streams (opcional) — Uma matriz de IDs de fluxos a serem incluídos na chamada SIP. Se você não definir essa propriedade, todos os fluxos da sessão serão incluídos na chamada.

Resposta

Os dados brutos da resposta HTTP, com código de status 200, são uma mensagem codificada em JSON com o seguinte formato:

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

O objeto JSON inclui as seguintes propriedades:

  • id — Um identificador único para a chamada SIP.
  • connectionId — O ID de conexão do OpenTok para a conexão da chamada SIP na sessão do OpenTok. Você pode usar esse ID de conexão para encerrar a chamada SIP, por meio da API REST do OpenTok.
  • streamId — O ID de transmissão do OpenTok correspondente à transmissão da chamada SIP na sessão do OpenTok.

A resposta HTTP apresenta um código de status 400 nos seguintes casos:

  • Você não forneceu um ID de sessão ou forneceu um ID de sessão inválido.

A resposta HTTP apresentará o código de status 403 caso você insira uma chave da API do OpenTok inválida ou um token JSON inválido.

A resposta HTTP apresenta o código de status 404 caso a sessão não exista.

A resposta HTTP apresentará o código de status 409 caso você tente iniciar uma chamada SIP para uma sessão que não utilize o OpenTok Media Router.

A resposta HTTP apresenta o código de status 500, indicando um erro no servidor OpenTok.

Exemplo

O exemplo de linha de comando a seguir conecta seu terminal SIP a uma sessão do OpenTok:

api_key=12345
json_web_token="jwt_string" # replace with a JSON web token (see "Authentication")
session_id=2_MX40NzIwMzJ-flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN-MC45NDQ2MzE2NH4
sip_uri='sip:user@sip.partner.comwhen;transport=tls'
data='{\
  "sessionId" : "'$session_id'", \
  "token": "A valid OpenTok token", \
  "sip": { \
    "uri": "'$sip_uri'", \
    "auth": {
      "username": "username",
      "password": "password"
    }
  }
}'
curl \
  -i \
  -H "Content-Type: application/json" \
  -H "X-OPENTOK-AUTH:$json_web_token" \
	-d "$data" \
  https://api.opentok.com/v2/project/$api_key/dial
  • Defina o valor para api_key à sua chave da API do OpenTok.
  • Defina o valor para json_web_token para um token JSON da Web (consulte Autenticação).
  • Defina o session_id valor para o ID da sessão do OpenTok à qual você deseja se conectar à sua plataforma SIP.
  • Defina o sip_uri valor para o URI SIP do seu terminal SIP.
  • Defina o token propriedade do data JSON para um token de conexão válido do OpenTok para o participante que está sendo chamado (consulte o Criação de tokens (guia do desenvolvedor).
  • Defina o username e password propriedades do data JSON com o nome de usuário e a senha do seu terminal SIP. (Isso é opcional.)

Envio de dígitos DTMF para clientes SIP

Use a API REST play-dtmf para enviar dígitos DTMF a todos os participantes de uma sessão ativa do OpenTok ou a um cliente específico conectado a essa sessão.

Os eventos de telefonia são negociados por meio do SDP e transmitidos como dígitos RFC4733/RFC2833 para o terminal remoto.

Enviar dígitos DTMF para todos os clientes conectados à sessão

Envie uma solicitação HTTP POST para a seguinte URL:

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

Substituir <api_key> com sua chave da API do OpenTok. Consulte a página do projeto do seu Account da Video API. Substituir <session_id> com o ID da sessão para a qual você está enviando o sinal DTMF.

A mensagem DTMF é ignorada pelos clientes que não oferecem suporte a DTMF (como os clientes que não são SIP).

Propriedades do cabeçalho POST

As chamadas à API devem ser autenticadas por meio de um cabeçalho HTTP personalizado — X-OPENTOK-AUTH — juntamente com um token JSON da Web (JWT). Consulte Autenticação.

Defina o Content-type cabeçalho para application/json:

Content-Type:application/json

Dados POST

Inclua um objeto JSON no formato a seguir como dados da solicitação POST:

{ "digits": "1713" }

O objeto JSON inclui um digits propriedade. Esta é a sequência de dígitos DTMF a ser enviada. Isso pode incluir 0-9, '*', '#' e 'p'. A p indica uma pausa de 500 ms (caso seja necessário adicionar um atraso no envio dos dígitos).

Resposta

Em uma chamada bem-sucedida, a resposta inclui um código de status HTTP 200.

Em caso de erros, a resposta inclui um dos seguintes códigos de status HTTP:

  • 400 — Uma das propriedades — digits ou sessionId — é inválido.

  • 403 — Erro de autenticação. Isso pode ocorrer se você usar uma chave de API do OpenTok inválida ou um token JSON da Web inválido

  • 404 — A sessão especificada não existe.

Em caso de erro, o corpo da resposta será em JSON com um code e message propriedade:

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

Exemplo

O código a seguir envia uma solicitação HTTP POST para o play-dtmf recurso da sessão:

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

Enviar tons DTMF para um cliente específico conectado à sessão

Envie uma solicitação HTTP POST para a seguinte URL:

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

Substituir <api_key> com sua chave da API do OpenTok. Consulte a página do projeto do seu Account da Video API. Substituir <session_id> com o ID da sessão para a qual você está enviando o sinal DTMF. Substitua <connection_id> com o ID de conexão do cliente para o qual você está enviando o sinal DTMF.

É possível obter o ID de conexão de um cliente SIP a partir da resposta da chamada à API REST para iniciar a chamada SIP.

Se você enviar dígitos DTMF para um cliente que não seja compatível com DTMF (como um cliente que não seja SIP), o cliente ignorará a solicitação.

Propriedades do cabeçalho POST

As chamadas à API devem ser autenticadas por meio de um cabeçalho HTTP personalizado — X-OPENTOK-AUTH — juntamente com um token JSON da Web (JWT). Consulte Autenticação.

Defina o Content-type cabeçalho para application/json:

Content-Type:application/json

Dados POST

Inclua um objeto JSON no formato a seguir como dados da solicitação POST:

{ "digits": "1713" }

O objeto JSON inclui um digits propriedade. Esta é a sequência de dígitos DTMF a ser enviada. Isso pode incluir 0-9, '*', '#' e 'p'. A p indica uma pausa de 500 ms (caso seja necessário adicionar um atraso no envio dos dígitos).

Resposta

Em uma chamada bem-sucedida, a resposta inclui um código de status HTTP 200.

Em caso de erros, a resposta inclui um dos seguintes códigos de status HTTP:

  • 400 — Uma das propriedades — digits ou sessionId — é inválido.

  • 403 — Erro de autenticação. Isso pode ocorrer se você usar uma chave de API do OpenTok inválida ou um token JSON da Web inválido

  • 404 — A sessão especificada não existe ou o cliente especificado pelo connectionId A propriedade não está vinculada à sessão.

Em caso de erro, o corpo da resposta será em JSON com um code e message propriedade:

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

Exemplo

Envie uma solicitação HTTP POST para o play-dtmf recurso de um ID de conexão específico pertencente à sessão:

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

Iniciando uma transmissão ao vivo

Use este método para iniciar uma transmissão ao vivo de uma sessão do OpenTok. Isso transmite a sessão para um fluxo HLS (HTTP Live Streaming) ou RTMP.

Para iniciar com sucesso a transmissão de uma sessão, é necessário que pelo menos um cliente esteja conectado à sessão.

A transmissão ao vivo pode ser direcionada a um ponto de extremidade HLS e a até cinco servidores RTMP simultaneamente por sessão. Só é possível iniciar a transmissão ao vivo para sessões que utilizem o OpenTok Media Router (com o modo de mídia definido como “routed”); não é possível usar a transmissão ao vivo com sessões que tenham o modo de mídia definido como “relayed”. (Consulte O OpenTok Media Router e os modos de mídia.)

Para obter mais informações sobre a transmissão ao vivo do OpenTok, consulte o Guia do desenvolvedor de transmissões.

POST HTTP para transmissão

Envie uma solicitação HTTP POST para a seguinte URL:

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

Substituir <apiKey> com sua chave da API do OpenTok.

Observação: Anteriormente, essa URL REST utilizava /partner (que agora está obsoleto) em vez de /project.

Propriedades do cabeçalho POST

Defina o Content-Type cabeçalho para application/json.

Autentique esta chamada de API usando um cabeçalho HTTP personalizado — X-OPENTOK-AUTH — definido como um token JSON da Web. Consulte Autenticação.

Dados POST

Inclua um objeto JSON no formato a seguir como conteúdo do corpo da solicitação:

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

O objeto JSON inclui as seguintes propriedades:

  • sessionId (String) — Defina aqui o ID da sessão do OpenTok que você deseja transmitir.

  • hasAudio (Booleano) — (Opcional) Indica se a transmissão incluirá áudio (true, valor padrão) ou não (false). Se você definir ambos hasAudio e hasVideo Se o valor for “false”, a chamada a este método resultará em um erro.

  • hasVideo (Booleano) — (Opcional) Indica se a transmissão incluirá vídeo (true, valor padrão) ou não (false). Se você definir ambos hasAudio e hasVideo Se o valor for “false”, a chamada a este método resultará em um erro.

    Observação: ao definir hasVideo Se o valor for “false”, a transmissão incluirá vídeos com quadros pretos de 160x120 nos fluxos RTMP. Alguns destinos, como o YouTube e o Facebook, rejeitam fluxos RTMP apenas de áudio.

  • layout (Objeto) — Opcional. Especifique-o para atribuir o tipo de layout inicial à transmissão. Esse objeto possui três propriedades: type, stylesheet, e screenshareType, sendo cada um deles uma sequência de caracteres. Os valores válidos para o layout as propriedades são "bestFit" (melhor ajuste), "custom" (personalizado), "horizontalPresentation" (apresentação horizontal), "pip" (imagem na imagem), e "verticalPresentation" (apresentação vertical)). Se você especificar um "custom" tipo de layout, defina o stylesheet propriedade do layout atribuir a folha de estilo. (Para outros tipos de layout, não defina um stylesheet propriedade.) Defina o screenshareType propriedade que define o tipo de layout a ser usado quando houver uma transmissão de compartilhamento de tela na sessão. (Essa propriedade é opcional.) Observe que, se você definir a screenshareType propriedade, é necessário definir o type atribuir a propriedade “bestFit” e deixar o stylesheet Propriedade não definida. Se você não especificar um tipo de layout inicial, o fluxo de transmissão utilizará o tipo de layout “Best Fit”. Para obter mais informações, consulte Configurando o layout de vídeo para o recurso de transmissão ao vivo do OpenTok.

  • multiBroadcastTag (String) — (Opcional) Defina este parâmetro para permitir a transmissão simultânea de várias transmissões para a mesma sessão. Defina-o como uma string exclusiva para cada transmissão simultânea de uma sessão em andamento. Consulte Transmissões simultâneas.

  • maxBitrate (opcional) — A taxa de bits máxima para o(s) fluxo(s) de transmissão, em bits por segundo. O valor mínimo é 100.000 e o máximo é 6.000.000.

  • maxDuration (Número inteiro) — Opcional. A duração máxima da transmissão, em segundos. A transmissão será interrompida automaticamente quando a duração máxima for atingida. Você pode definir a duração máxima com um valor entre 60 (60 segundos) e 36.000 (10 horas). A duração máxima padrão é de 4 horas (14.400 segundos).

  • outputs (Objeto) — Obrigatório. Este objeto define os tipos de fluxos de transmissão que você deseja iniciar (tanto HLS quanto RTMP). Você pode incluir HLS, RTMP ou ambos como fluxos de transmissão. Se incluir a transmissão por RTMP, é possível especificar até cinco fluxos RTMP de destino (ou apenas um).

    Para cada transmissão RTMP, especifique serverUrl (a URL do servidor RTMP), streamName (o nome da transmissão, como o nome da transmissão ao vivo do YouTube ou a chave de transmissão do Facebook) e (opcionalmente) id (um ID exclusivo para o stream). Certifique-se de incluir a porta para o serverUrl, como em "rtmps://myfooserver:443/myfooapp" (em vez de "rtmps://myfooserver/myfooapp"). Se você especificar um ID, ele será incluído na resposta da chamada REST e o Método REST para obter informações sobre uma transmissão ao vivo. A Vonage transmite a sessão para cada URL RTMP que você especificar. Observe que a transmissão ao vivo do OpenTok é compatível com RTMP e RTMPS.

    Para HLS, inclua um único hls propriedade na outputs objeto. Esse objeto inclui as seguintes propriedades opcionais:

    • dvr (Booleano) — Se deve ser ativado Funcionalidade de DVR — retroceder, pausar e retomar — em reprodutores que ofereçam esses recursos (true), ou não (false, (padrão). Com o DVR ativado, a URL HLS incluirá um ?DVR sequência de consulta anexada ao final.
    • lowLatency (Booleano) — Se deve ser ativado modo de baixa latência para o HLSstream. Alguns reprodutores HLS não oferecem suporte ao modo de baixa latência. Esse recurso é incompatível com transmissões HLS no modo DVR.

    A URL do HLS é retornada na resposta e no método REST para obter informações sobre uma transmissão ao vivo.

  • resolution (String) — A resolução da transmissão: pode ser "640x480" (paisagem SD, a configuração padrão), "1280x720" (HD paisagem), "1920x1080" (FHD na orientação paisagem), "480x640" (retrato em SD), "720x1280" (retrato em HD), ou "1080x1920" (FHD retrato). Pode ser interessante usar uma proporção de tela retrato para transmissões que incluam fluxos de vídeo de dispositivos móveis (que geralmente utilizam a proporção de tela retrato). Essa propriedade é opcional.

  • streamMode (String) — (Opcional) Se os streams incluídos na transmissão são selecionados automaticamente ("auto", o padrão) ou manualmente ("manual"). Quando os fluxos são selecionados automaticamente ("auto"), todas as transmissões da sessão podem ser incluídas na transmissão. Quando as transmissões são selecionadas manualmente ("manual"), você especifica quais fluxos incluir com base nas chamadas para esse método REST. É possível especificar se o áudio, o vídeo ou ambos de um stream serão incluídos na transmissão. Tanto no modo automático quanto no manual, o editor de transmissões inclui os streams com base em regras de priorização de fluxos.

Se você precisar oferecer suporte a apenas uma URL RTMP, pode passar um objeto (em vez de uma matriz de objetos) para o rtmp valor da propriedade nos dados POST que você fornece ao chamar o método REST. Por exemplo, os dados POST a seguir especificam uma URL de saída RTMP (e não incluem saída HLS):

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

Resposta

Os dados brutos da resposta HTTP, com código de status 200, são uma mensagem codificada em JSON com o seguinte formato:

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

O objeto JSON inclui as seguintes propriedades:

  • id — O ID exclusivo da transmissão
  • sessionId — O ID da sessão do OpenTok
  • projectId — Sua chave da API do OpenTok
  • createdAt — O momento em que a transmissão começou, expresso em milissegundos desde a época Unix (1º de janeiro de 1970, 00:00:00 UTC)
  • updatedAt — Para esse método de inicialização, esse carimbo de data e hora corresponde ao carimbo de data e hora “createdAt”.
  • resolution — A resolução da transmissão (seja “640x480”, “1280x720”, “1920x1080”, “480x640”, “720x1280” ou “1920x1080”).
  • status — Isso está definido para "started".
  • streamMode — Se todas as transmissões estão incluídas na transmissão ("auto") ou você seleciona os streams a serem incluídos na transmissão ("manual").
  • streams — Uma matriz de objetos correspondentes às transmissões que estão no ar no momento. Esse valor só é definido para uma transmissão com o status definir como "started" e o streamMode definir como "manual". Cada objeto da matriz possui as seguintes propriedades:
    • streamId — O ID da transmissão incluída na transmissão ao vivo.
    • hasAudio — Se o áudio da transmissão está incluído na transmissão.
    • hasVideo — Se o vídeo da transmissão está incluído na transmissão.
  • maxDuration — A duração máxima da transmissão (caso tenha sido definida), em segundos.
  • multiBroadcastTag — A tag exclusiva para transmissões simultâneas (caso tenha sido definida).
  • broadcastUrls — Um objeto que contém detalhes sobre as transmissões HLS e RTMP.

Se você tiver especificado um endpoint HLS, o objeto inclui um hls propriedade e um hlsStatus propriedade. A hls A propriedade é definida como a URL da transmissão HLS. Observe que essa URL de transmissão HLS aponta para um arquivo de índice, uma lista de reprodução no formato .M3U8 que contém uma lista de URLs para arquivos de segmentos de mídia .ts (arquivos de fluxo de transporte MPEG-2). Embora as URLs tanto do arquivo de índice da lista de reprodução quanto dos arquivos de segmentos de mídia sejam fornecidas assim que a resposta HTTP é retornada, essas URLs não devem ser acessadas até 15 a 20 segundos depois, após o início da transmissão HLS, devido ao atraso entre a transmissão HLS e as transmissões ao vivo na sessão do OpenTok. Consulte https://developer.apple.com/library/ios/technotes/tn2288/_index.html para obter mais informações sobre o arquivo de índice da lista de reprodução e os arquivos de segmentos de mídia para HLS. O hlsStatus a propriedade está definida como um dos seguintes valores:

  • "connecting" — O servidor OpenTok está iniciando os transcodificadores. Este é o estado inicial.
  • "ready" — O servidor OpenTok foi inicializado com sucesso, mas a CDN não está recebendo a mídia.
  • "live" — O servidor OpenTok foi inicializado com sucesso e a CDN está recebendo os arquivos de mídia.
  • "ended" — A transmissão da fonte foi encerrada. Se o DVR estiver ativado e for solicitada uma gravação prévia, o status mudará para "live".
  • "error" — Ocorreu um erro na plataforma OpenTok.

Se você tiver especificado pontos finais de transmissão RTMP, o objeto inclui um rtmp propriedade. Trata-se de uma matriz de objetos que contém informações sobre cada um dos fluxos RTMP. Cada um desses objetos possui as seguintes propriedades: id (o ID que você atribuiu ao stream RTMP), serverUrl (a URL do servidor), streamName (o nome do stream), e status propriedade (que está definida como "connecting"). Você pode chamar o Método REST do OpenTok para verificar atualizações de status da transmissão.

A resposta HTTP terá um dos seguintes códigos de status:

  • 200 — Sucesso.
  • 400 — Solicitação inválida. Essa resposta pode indicar que os dados da sua solicitação estão no formato JSON inválido. Também pode indicar que você passou opções de layout inválidas. Ou que você excedeu o limite de cinco transmissões RTMP simultâneas para uma sessão do OpenTok. Ou que você especificou uma resolução inválida.
  • 403 — Erro de autenticação.
  • 409 — A transmissão da sessão já começou. Ou se você tentar iniciar uma transmissão simultânea de uma sessão sem definir um multiBroadcastTag valor.
  • 500 — Erro no servidor OpenTok.

Exemplo

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

Interromper uma transmissão ao vivo

Use este método para interromper uma transmissão ao vivo de uma sessão do OpenTok.

Observe que uma transmissão é interrompida automaticamente 60 segundos após o último cliente se desconectar da sessão. Além disso, há uma duração máxima padrão de 4 horas (14.400 segundos) para cada transmissão HLS e RTMP (a transmissão ao vivo é interrompida automaticamente quando essa duração é atingida). Você pode alterar a duração máxima da transmissão definindo o maxDuration propriedade quando você iniciar a transmissão Método REST.

HTTP POST para broadcast//stop

Envie uma solicitação HTTP POST para a seguinte URL:

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

Substituir <apiKey> com sua chave da API do OpenTok. Substitua <broadcastId> com o ID da transmissão que você deseja interromper. Você obtém o ID da transmissão ao iniciá-la.

Propriedades do cabeçalho POST

Autentique esta chamada de API usando um cabeçalho HTTP personalizado — X-OPENTOK-AUTH — definido como um token JSON da Web. Consulte Autenticação.

Observação: Anteriormente, essa URL REST utilizava /partner (que agora está obsoleto) em vez de /project.

Resposta

Os dados brutos da resposta HTTP, com código de status 200, são uma mensagem codificada em JSON com o seguinte formato:

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

O objeto JSON inclui as seguintes propriedades:

  • id — O ID exclusivo da transmissão
  • sessionId — O ID da sessão do OpenTok que está sendo transmitida
  • projectId — Sua chave da API do OpenTok
  • createdAt — A hora em que a transmissão começou, expressa em segundos desde a época Unix (1º de janeiro de 1970, 00:00:00 UTC)
  • updatedAt — O tempo em que a transmissão foi interrompida, expresso em segundos desde a época Unix (1º de janeiro de 1970, 00:00:00 UTC)
  • resolution — A resolução da transmissão (seja “640x480”, “1280x720”, “1920x1080”, “480x640”, “720x1280” ou “1080x1920”).
  • status — Isso está definido para "stopped".
  • streamMode — Se todas as transmissões estão incluídas na transmissão ("auto") ou você seleciona os streams a serem incluídos na transmissão ("manual").
  • streams — Uma matriz de objetos correspondentes às transmissões que estão no ar no momento. No método `stop`, essa matriz está vazia.
  • maxDuration — A duração máxima da transmissão (caso tenha sido definida), em segundos.
  • multiBroadcastTag — A tag exclusiva para transmissões simultâneas (caso tenha sido definida).
  • broadcastUrls — Esse valor é definido como nulo para o método `stop`.

A resposta HTTP terá um dos seguintes códigos de status:

  • 200 — Sucesso.
  • 400 — Solicitação inválida. Essa resposta pode indicar que os dados da sua solicitação estão no formato JSON inválido.
  • 403 — Erro de autenticação.
  • 404 — A transmissão (com o ID especificado) não foi encontrada ou já foi encerrada.
  • 500 — Erro no servidor OpenTok.

Exemplo

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

Lista de transmissões ao vivo

Use este método para obter detalhes sobre transmissões em andamento e já iniciadas. As transmissões concluídas não estão incluídas na lista.

HTTP GET para transmissão

Envie uma solicitação HTTP GET para a seguinte URL:

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

Substituir <apiKey> com sua chave da API do OpenTok.

São aceitos os seguintes parâmetros de consulta:

  • offset (opcional) — O deslocamento inicial na lista de transmissões existentes
  • count (opcional, padrão: 50, máximo: 1000) — O número de transmissões a serem recuperadas a partir do deslocamento
  • sessionId (opcional): Recuperar apenas as transmissões correspondentes a um determinado ID de sessão

Propriedades do cabeçalho GET

Autentique esta chamada de API usando um cabeçalho HTTP personalizado — X-OPENTOK-AUTH — definido como um token JSON da Web. Consulte Autenticação.

Resposta

Os dados brutos da resposta HTTP, com código de status 200, consistem em uma mensagem codificada em JSON com o seguinte formato:

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

O objeto JSON inclui as seguintes propriedades:

  • count — O número total de transmissões nos resultados.
  • items — Uma matriz de objetos que define cada transmissão recuperada. As transmissões são listadas do mais recente ao mais antigo no conjunto de resultados.

Cada objeto de transmissão (item) possui as seguintes propriedades:

  • id — O ID exclusivo da transmissão

  • sessionId — O ID da sessão do OpenTok

  • projectId — Sua chave da API do OpenTok

  • createdAt — O momento em que a transmissão começou, expresso em milissegundos desde a época Unix (1º de janeiro de 1970, 00:00:00 UTC)

  • updatedAt — Para esse método GET, esse carimbo de data e hora corresponde ao carimbo de data e hora `createdAt`.

  • resolution — A resolução da transmissão (seja “640x480”, “1280x720”, “1920x1080”, “480x640”, “720x1280” ou “1080x1920”).

  • status — O status da transmissão. Este método retorna apenas transmissões cujo status esteja definido como "started".

  • maxDuration — A duração máxima da transmissão (caso tenha sido definida), em segundos.

  • multiBroadcastTag — A tag exclusiva para transmissões simultâneas (caso tenha sido definida).

  • broadcastUrls — Detalhes sobre os fluxos de transmissão HLS e RTMP.

    Para uma transmissão HLS, a URL é fornecida como o hls propriedade. Consulte o Guia do desenvolvedor para transmissão ao vivo do OpenTok Para obter mais informações sobre como usar este URL. O hlsStatus a propriedade está definida como um dos seguintes valores:

    • "connecting" — O servidor OpenTok está iniciando os transcodificadores. Este é o estado inicial.
    • "ready" — O servidor OpenTok foi inicializado com sucesso, mas a CDN não está recebendo a mídia.
    • "live" — O servidor OpenTok foi inicializado com sucesso e a CDN está recebendo a mídia.
    • "ended" — A transmissão da fonte foi encerrada. Se o DVR estiver ativado e for solicitado um conteúdo pré-gravado, o status mudará para live".
    • "error" — Ocorreu um erro na plataforma OpenTok.

    Para cada transmissão RTMP, são fornecidos a URL do servidor RTMP e o nome da transmissão, juntamente com o status da transmissão RTMP. O status a propriedade está definida como um dos seguintes valores:

    • connecting — A plataforma OpenTok está se conectando ao servidor RTMP remoto. Esse é o estado inicial e é o status exibido quando você inicia a sessão e não há transmissões publicadas nela. Ele muda para “ao vivo” quando há transmissões (ou muda para um dos outros estados).
    • live — A plataforma OpenTok se conectou com sucesso ao servidor RTMP remoto, e a transmissão de mídia está em andamento.
    • offline — A plataforma OpenTok não conseguiu se conectar ao servidor RTMP remoto. Isso se deve a um servidor inacessível ou a um erro no handshake RTMP. As causas incluem conexões RTMP rejeitadas, Applications RTMP inexistentes, nomes de stream rejeitados, erros de autenticação etc. Verifique se o servidor está online e se você forneceu a URL correta do servidor e o nome correto do stream.
    • error — Ocorreu um erro na plataforma OpenTok.

  • settings — Mais detalhes sobre a transmissão em HLS. Isso settings objeto inclui um hls propriedade com as seguintes características:

  • streamMode — Se todas as transmissões estão incluídas na transmissão ("auto") ou você seleciona os streams a serem incluídos na transmissão ("manual"). Veja Seleção dos streams a serem incluídos em uma transmissão ao vivo.

  • streams — Para uma transmissão com "manual" streamMode e um status definir como "started", esta é uma matriz de objetos correspondentes às transmissões que estão no ar no momento. Cada objeto da matriz inclui as seguintes propriedades:

    • streamId — O ID da transmissão incluída na transmissão ao vivo.
    • hasAudio — Se o áudio da transmissão está incluído na transmissão.
    • hasVideo — Se o vídeo da transmissão está incluído na transmissão.

A resposta HTTP terá um dos seguintes códigos de status:

  • 200 — Sucesso
  • 403 — Erro de autenticação
  • 500 — Erro no servidor OpenTok

Exemplos

Listando todas as transmissões (até 50):

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

Listando uma série de transmissões:

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

Listar transmissões para um ID de sessão específico:

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

Como obter informações sobre uma transmissão ao vivo

Use este método para obter detalhes sobre uma transmissão que está em andamento.

HTTP GET para transmissão

Envie uma solicitação HTTP GET para a seguinte URL:

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

Substituir <apiKey> com sua chave da API do OpenTok. Substitua <broadcastId> com o ID da transmissão. Você obtém o ID da transmissão ao iniciá-la.

Observação: Anteriormente, essa URL REST utilizava /partner (que agora está obsoleto) em vez de /project.

Propriedades do cabeçalho GET

Autentique esta chamada de API usando um cabeçalho HTTP personalizado — X-OPENTOK-AUTH — definido como um token JSON da Web. Consulte Autenticação.

Resposta

Os dados brutos da resposta HTTP, com código de status 200, são uma mensagem codificada em JSON com o seguinte formato:

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

O objeto JSON inclui as seguintes propriedades:

  • id — O ID exclusivo da transmissão

  • sessionId — O ID da sessão do OpenTok

  • projectId — Sua chave da API do OpenTok

  • createdAt — O momento em que a transmissão começou, expresso em milissegundos desde a época Unix (1º de janeiro de 1970, 00:00:00 UTC)

  • updatedAt — Para esse método GET, esse carimbo de data e hora corresponde ao carimbo de data e hora “createdAt”.

  • resolution — A resolução da transmissão (seja “640x480”, “1280x720”, “1920x1080”, “480x640”, “720x1280” ou “1080x1920”).

  • status — O status da transmissão: ou "started" ou "stopped".

  • broadcastUrls — Detalhes sobre os fluxos de transmissão HLS e RTMP.

    Para uma transmissão HLS, a URL é fornecida como o hls propriedade. Consulte o Guia do desenvolvedor para transmissão ao vivo do OpenTok para obter mais informações sobre como usar essa URL. O hlsStatus a propriedade está definida como um dos seguintes valores:

  • "connecting" — O servidor OpenTok está iniciando os transcodificadores. Este é o estado inicial.
  • "ready" — O servidor OpenTok foi inicializado com sucesso, mas a CDN não está recebendo a mídia.
  • "live" — O servidor OpenTok foi inicializado com sucesso e a CDN está recebendo os arquivos de mídia.
  • "ended" — A transmissão da fonte foi encerrada. Se o DVR estiver ativado e for solicitada uma gravação prévia, o status mudará para "live".
  • "error" — Ocorreu um erro na plataforma OpenTok.

Para cada transmissão RTMP, são fornecidos a URL do servidor RTMP e o nome da transmissão, juntamente com o status da transmissão RTMP.

  • status — O status do fluxo RTMP. Verifique com frequência para acompanhar as atualizações de status. Essa propriedade pode assumir um dos seguintes valores:

    • connecting — A plataforma OpenTok está se conectando ao servidor RTMP remoto. Esse é o estado inicial e é o status exibido quando você inicia a sessão sem que haja transmissões publicadas. Ele muda para “ao vivo” quando há transmissões (ou muda para um dos outros estados).
    • live — A plataforma OpenTok se conectou com sucesso ao servidor RTMP remoto, e a transmissão de mídia está em andamento.
    • offline — A plataforma OpenTok não conseguiu se conectar ao servidor RTMP remoto. Isso ocorre devido a um servidor inacessível ou a um erro no handshake RTMP. As causas incluem conexões RTMP rejeitadas, Applications RTMP inexistentes, nomes de stream rejeitados, erros de autenticação etc. Verifique se o servidor está online e se você forneceu a URL correta do servidor e o nome do stream.
    • error — Ocorreu um erro na plataforma OpenTok.

  • settings — Mais detalhes sobre a transmissão em HLS. Isso properties O objeto inclui um hls propriedade com as seguintes características:

  • multiBroadcastTag — A tag exclusiva para transmissões simultâneas (caso tenha sido definida).

  • streamMode — Se todas as transmissões estão incluídas na transmissão ("auto") ou você seleciona os streams a serem incluídos na transmissão ("manual"). Veja Seleção dos streams a serem incluídos em uma transmissão ao vivo.

  • streams — Uma matriz de objetos correspondentes às transmissões que estão no ar no momento. Esse valor só é definido para uma transmissão com o status definir como "started" e o streamMode definir como "manual". Cada objeto da matriz possui as seguintes propriedades:

    • streamId — O ID da transmissão incluída na transmissão ao vivo.
    • hasAudio — Se o áudio da transmissão está incluído na transmissão.
    • hasVideo — Se o vídeo da transmissão está incluído na transmissão.

A resposta HTTP terá um dos seguintes códigos de status:

  • 200 — Sucesso
  • 400 — Solicitação inválida
  • 403 — Erro de autenticação
  • 404 — Não foi encontrada nenhuma transmissão correspondente (com o ID especificado)
  • 500 — Erro no servidor OpenTok

Exemplo

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

Alteração dinâmica do tipo de layout durante uma transmissão ao vivo

É possível alterar dinamicamente o tipo de layout de uma transmissão ao vivo.

Para obter mais informações sobre as transmissões ao vivo do OpenTok, consulte o Guia do desenvolvedor de transmissões.

HTTP PUT para transmissão

Envie uma solicitação HTTP PUT para a seguinte URL:

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

Substituir <apiKey> com sua chave da API do OpenTok.

Substituir <broadcastId> com o ID da transmissão.

Propriedades do cabeçalho PUT

Defina o Content-Type cabeçalho para application/json.

Autentique esta chamada de API usando um cabeçalho HTTP personalizado — X-OPENTOK-AUTH — definido como um token JSON da Web. Consulte Autenticação.

Dados de PUT

Inclua um objeto JSON no formato a seguir como conteúdo do corpo da solicitação:

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

O objeto JSON inclui as seguintes propriedades:

  • tipo (String) — O tipo de layout da transmissão. Os valores válidos são "bestFit" (melhor ajuste), "custom" (personalizado), "horizontalPresentation" (apresentação horizontal), "pip" (imagem na imagem), e "verticalPresentation" (apresentação vertical)). Se você especificar um "custom" tipo de layout, defina o stylesheet propriedade à folha de estilo. (Para outros tipos de layout, não defina a stylesheet propriedade.) Para obter mais informações, consulte Configurando o layout de vídeo para o recurso de transmissão ao vivo do OpenTok.
  • folha de estilo (String) — Opcional. Especifique isso somente se você definir o type propriedade para "custom". Defina o stylesheet propriedade à folha de estilo. (Para outros tipos de layout, não defina a stylesheet propriedade.) Para obter mais informações, consulte Definindo layouts personalizados.
  • tipo de compartilhamento de tela (String) — Opcional. O tipo de layout a ser usado quando houver uma transmissão de compartilhamento de tela na sessão. Observe que, para usar essa propriedade, é necessário definir o type atribuir a propriedade “bestFit” e deixar o stylesheet propriedade não definida. Para obter mais informações, consulte Tipos de layout para compartilhamento de tela.

Ao especificar um tipo de layout diferente do tipo “Best Fit”, certifique-se de aplicar as classes de layout adequadas aos fluxos na sessão do OpenTok (consulte Atribuição de classes de layout de transmissão ao vivo às transmissões do OpenTok.

Resposta

A resposta HTTP terá um dos seguintes códigos de status:

  • 200 — Sucesso.
  • 400 — Solicitação inválida. Essa resposta pode indicar que os dados da sua solicitação estão no formato JSON inválido. Também pode indicar que você passou opções de layout inválidas.
  • 403 — Erro de autenticação.
  • 500 — Erro no servidor OpenTok.

Exemplo

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

Alterando as classes de layout da transmissão ao vivo para uma transmissão do OpenTok

Use este método para alterar as classes de layout de uma transmissão do OpenTok. As classes de layout definem como a transmissão é exibida no layout da transmissão ao vivo. Para obter mais informações, consulte Atribuição de classes de layout de transmissão ao vivo às transmissões do OpenTok.

HTTP PUT para transmissão

Envie uma solicitação HTTP PUT para a seguinte URL:

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

Substituir <apiKey> com sua chave da API do OpenTok.

Substituir <sessionId> com o ID da sessão.

Propriedades do cabeçalho PUT

Defina o Content-Type cabeçalho para application/json.

Autentique esta chamada de API usando um cabeçalho HTTP personalizado — X-OPENTOK-AUTH — definido como um token JSON da Web. Consulte Autenticação.

Dados de PUT

Inclua um objeto JSON no formato a seguir como conteúdo do corpo da solicitação:

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

O objeto JSON inclui um items matriz de objetos. Cada objeto define as classes de layout a serem atribuídas a um fluxo e contém as seguintes propriedades:

  • id (String) — O ID do fluxo.
  • layoutClassList (Matriz) — Uma matriz de classes de layout (cada uma representada por uma string) para o fluxo.

É possível atualizar a lista de classes de layout para vários fluxos passando vários objetos JSON no items matriz.

Resposta

A resposta HTTP terá um dos seguintes códigos de status:

  • 200 — Sucesso.
  • 400 — Solicitação inválida. Essa resposta pode indicar que os dados da sua solicitação estão no formato JSON inválido. Também pode indicar que você passou opções de layout inválidas.
  • 403 — Erro de autenticação.
  • 500 — Erro no servidor OpenTok.

Exemplo

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

Seleção dos streams a serem incluídos em uma transmissão ao vivo

Use este método para alterar os fluxos incluídos em uma transmissão ao vivo que foi iniciada com o streamMode definir como "manual" (ver Iniciando uma transmissão ao vivo).

O compositor de transmissão inclui fluxos adicionados com base em regras de priorização de fluxos.

HTTP PATCH para broadcast/streams

Envie uma solicitação HTTP PATCH para a seguinte URL:

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

Substituir <apiKey> com sua chave da API do OpenTok. Substitua <broadcastId> com o ID da transmissão.

Propriedades do cabeçalho PATCH

Defina o Content-Type cabeçalho para application/json.

Autentique esta chamada de API usando um cabeçalho HTTP personalizado — X-OPENTOK-AUTH — definido como um token JSON da Web. Consulte Autenticação.

Dados do PATCH

Para adicionar uma transmissão à transmissão ao vivo, inclua um objeto JSON no formato a seguir como conteúdo do corpo da solicitação:

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

O objeto JSON contém as seguintes propriedades:

  • addStream (String) — O ID do fluxo.
  • hasAudio (Booleano, opcional) — Se a transmissão deve incluir o áudio do stream (true, o padrão) ou não (false).
  • hasVideo (Booleano, opcional) — Se a transmissão deve incluir o vídeo do stream (true, o padrão) ou não (false).

Você pode chamar o método repetidamente com addStream definido com o mesmo ID de stream, para ativar ou desativar o áudio ou o vídeo do stream na transmissão.

Se você definir ambos hasAudio e hasVideo para false, você receberá uma resposta de erro.

Para impedir que um stream seja incluído na transmissão, inclua um objeto JSON no formato a seguir como conteúdo do corpo da solicitação:

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

Defina o removeStream propriedade associada ao ID do fluxo.

Resposta

A resposta HTTP terá um dos seguintes códigos de status:

  • 204 — Sucesso (sem conteúdo).
  • 400 — Solicitação inválida. Essa resposta pode indicar que os dados fornecidos em sua solicitação estão em formato JSON inválido ou que a solicitação não pôde ser atendida porque a transmissão foi iniciada com streamMode definir como "auto", que não oferece suporte à manipulação de fluxos.
  • 403 — Erro de autenticação.
  • 404 — Transmissão ou stream não encontrado.
  • 500 — Erro no servidor OpenTok.

Exemplos

Adicionar uma transmissão a uma transmissão ao vivo:

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

Remover o vídeo de uma transmissão (mas mantendo o áudio):

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

Como remover uma transmissão de uma transmissão ao vivo:

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

Iniciando as legendas em tempo real

Use este método para ativar as legendas em tempo real (Live Captions) em uma sessão do OpenTok.

A duração máxima permitida é de 4 horas; após esse período, a legenda de áudio será interrompida sem afetar a sessão do OpenTok em andamento. As sessões de legenda também serão encerradas 60 segundos após a desconexão do último cliente. Um evento será enviado para sua URL de retorno de chamada, caso tenha sido fornecida ao iniciar as legendas.

Cada sessão do OpenTok suporta apenas uma sessão de legenda de áudio.

Para obter mais informações sobre o recurso “Legendas em tempo real”, consulte o Guia do desenvolvedor do Live Captions.

POST HTTP para ativar as legendas em tempo real

Envie uma solicitação HTTP POST para a seguinte URL:

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

Substituir <apiKey> com sua chave da API do OpenTok.

Defina o Content-Type cabeçalho para application/json.

Autentique esta chamada de API usando um cabeçalho HTTP personalizado — X-OPENTOK-AUTH — definido como um token JSON da Web. Consulte Autenticação.

Dados POST

Inclua um objeto JSON no formato a seguir como conteúdo do corpo da solicitação:

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

O objeto JSON inclui as seguintes propriedades:

  • sessionId (String) — O ID da sessão do OpenTok. O áudio dos emissores que estão transmitindo para essa sessão será usado para gerar as legendas.
  • token(String) — Um token válido do OpenTok com a função definida como “Moderador”.
  • languageCode (String) — (Opcional) O código BCP-47 do idioma utilizado pelo Live Captions (consulte esta lista de idiomas suportados). O valor padrão é “en-US”.
  • maxDuration (Número inteiro) — (Opcional) A duração máxima da legenda de áudio, em segundos. O valor padrão é 14.400 segundos (4 horas), que é a duração máxima permitida. O valor mínimo para maxDuration é 300 (300 segundos, ou 5 minutos).
  • partialCaptions (Booleano) — (Opcional) Indica se essa opção deve ser ativada para agilizar a geração de legendas, em troca de um certo grau de imprecisão. O valor padrão é true.

Resposta

Se a operação for bem-sucedida, os dados brutos da resposta HTTP, com código de status 200, consistem em uma mensagem codificada em JSON com o seguinte formato:

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

O objeto JSON inclui a seguinte propriedade:

  • captionsId — O ID exclusivo da sessão de legenda de áudio.

A resposta HTTP terá um dos seguintes códigos de status:

  • 202 — Aceito.
  • 400 — Solicitação inválida; a resposta pode indicar um erro relacionado aos dados da solicitação que não são aceitáveis.
  • 403 — Erro de autenticação. O X-OPENTOK-AUTH pode estar inválido.
  • 409 — As legendas em tempo real já começaram nesta sessão do OpenTok.
  • 500 — Erro na plataforma da Video API da Vonage.

Exemplo


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

Desativar as legendas em tempo real

Use este método para interromper as legendas em tempo real de uma sessão.

POST HTTP para interromper as legendas em tempo real

Envie uma solicitação HTTP POST para a seguinte URL:

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

Substituir <apiKey> com sua chave da API do OpenTok. Substitua <captionsId> com o ID retornado na resposta da API de legendas iniciais.

Autentique esta chamada de API usando um cabeçalho HTTP personalizado — X-OPENTOK-AUTH — definido como um token JSON da Web. Consulte Autenticação.

A resposta HTTP terá um dos seguintes códigos de status:

  • 202 — Aceito
  • 403 — Erro de autenticação
  • 404 — Não foi encontrado nenhum captionsId correspondente
  • 500 — Erro na plataforma da Video API da Vonage

Exemplo

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;

Iniciando o Experience Composer

Use este método para criar um Experience Composer para uma sessão do OpenTok. Para obter mais informações, consulte o Guia do desenvolvedor do Experience Composer.

HTTP POST para renderizar

Envie uma solicitação HTTP POST para a seguinte URL:

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

Substituir <apiKey> com sua chave da API do OpenTok.

Propriedades do cabeçalho POST

Defina o Content-Type cabeçalho para application/json.

Autentique esta chamada de API usando um cabeçalho HTTP personalizado — X-OPENTOK-AUTH — definido como um token JSON da Web. Consulte Autenticação.

Dados POST

Inclua um objeto JSON no formato a seguir como conteúdo do corpo da solicitação:

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

O objeto JSON inclui as seguintes propriedades:

  • sessionId (String) — O ID da sessão do OpenTok que irá incluir a transmissão do Experience Composer.
  • token (String) — Um token válido do OpenTok com a função de Publisher e (opcionalmente) dados de conexão a serem associados ao fluxo de saída.
  • url (String) — Uma URL acessível ao público, controlada pelo cliente e capaz de gerar o conteúdo a ser exibido sem intervenção do usuário. O comprimento mínimo da URL é de 15 caracteres e o máximo é de 2.048 caracteres.
  • maxDuration (Inteiro) — (Opcional) O tempo máximo permitido para o Experience Composer, em segundos. Após esse tempo, ele é interrompido automaticamente, caso ainda esteja em execução. O valor máximo é 36000 (10 horas), o valor mínimo é 60 (1 minuto) e o valor padrão é 7200 (2 horas). Quando o Experience Composer é encerrado, seu stream é retirado do ar e um evento é enviado para a URL de retorno de chamada, caso esteja configurada no Portal da Conta.
  • resolução (String) — (Opcional) A resolução do Experience Composer, que pode ser "640x480" (SD paisagem), "480x640" (SD retrato), “1280x720” (HD paisagem), “720x1280” (HD retrato), “1920x1080” (FHD paisagem) ou “1080x1920” (FHD retrato). Por padrão, essa resolução é “1280x720” (HD paisagem, a configuração padrão).
  • propriedades (Object) — (Opcional) A configuração inicial das propriedades do Publisher para o fluxo de saída composto. O objeto de propriedades contém o nome da chave (String), que serve como nome do fluxo de saída composto publicado na sessão. O nome deve ter comprimento mínimo de 1 e máximo de 200.

Resposta

Os dados brutos da resposta HTTP, com código de status 200, são uma mensagem codificada em JSON com o seguinte formato:

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

O objeto JSON inclui as seguintes propriedades:

  • id — O ID exclusivo do Experience Composer.
  • sessionId — O ID da sessão do OpenTok.
  • projectId — Sua chave da API do OpenTok.
  • createdAt — A hora em que o Experience Composer foi iniciado, expressa em milissegundos desde a época Unix (1º de janeiro de 1970, 00:00:00 UTC).
  • updatedAt — Este é o timestamp do UNIX correspondente à última atualização do status do Experience Composer. Para este método de inicialização, esse timestamp coincide com o timestamp createdAt.
  • callbackUrl — A URL de retorno de chamada para eventos do Experience Composer (caso tenha sido definida). Consulte Configurando callbacks.
  • nome — O nome do Experience Composer (caso tenha sido especificado).
  • url — Uma URL acessível ao público, controlada pelo cliente e capaz de gerar o conteúdo a ser exibido sem a intervenção do usuário.
  • resolução — A resolução do Experience Composer (seja “640x480”, “480x640”, “1280x720”, “720x1280”, “1920x1080” ou “1080x1920”).
  • status — Para este método de inicialização, ele está definido como “inicializando”.
  • streamId — O ID do stream composto que está sendo publicado.

A resposta HTTP terá um dos seguintes códigos de status:

  • 202 — Sucesso.

  • 400 — Solicitação inválida. Essa resposta pode indicar que os dados da sua solicitação estão em formato JSON inválido. Ela pode incluir um código de erro; alguns deles estão listados abaixo:

    • 50001 — Estrutura inválida da URL do aplicativo.
    • 50002 — Não foi possível acessar a URL do aplicativo.
    • 50005 — O valor fornecido para maxDuration é inválido.
    • 50006 — Resolução inválida fornecida.
    • 50007 — Nome de fluxo inválido fornecido.
    • 50008 — sessionId inválido fornecido.

  • 403 — Erro de autenticação. Pode incluir um código de erro; alguns deles estão listados a seguir:

    • 10001 - Formato ou assinatura inválida do token.
    • 10002 - Token não autorizado.
    • 10003 - Formato inválido de autenticação do parceiro.
    • 10004 - Autenticação não autorizada de parceiro.
    • 10007 - O token não corresponde ao ID da sessão.
    • 10012 - Token expirado.

  • 429 — Número excessivo de solicitações. Você excedeu o limite de uso do Experienced Composer. A resposta incluirá um código de erro definido como 50004.

  • 500 — Erro na plataforma da Video API da Vonage.

Exemplo

  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

Como obter informações sobre um Experience Composer

Use este método para obter detalhes sobre um Experience Composer.

HTTP GET para renderizar

Envie uma solicitação HTTP GET para a seguinte URL:

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

Substituir <apiKey> com sua chave da API do OpenTok. Substitua <experienceComposerId> com o ID do Experience Composer. Você obtém o ID do Experience Composer ao iniciar um Experience Composer.

Propriedades do cabeçalho GET

Autentique esta chamada de API usando um cabeçalho HTTP personalizado — X-OPENTOK-AUTH — definido como um token JSON da Web. Consulte Autenticação.

Resposta

Os dados brutos da resposta HTTP, com código de status 200, são uma mensagem codificada em JSON com o seguinte formato:

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

O objeto JSON inclui as seguintes propriedades:

  • id — O ID exclusivo do Experience Composer.
  • sessionId — O ID da sessão do OpenTok.
  • projectId — Sua chave da API do OpenTok.
  • createdAt — A hora em que o Experience Composer foi iniciado, expressa em milissegundos desde a época Unix (1º de janeiro de 1970, 00:00:00 UTC).
  • updatedAt — Para este método GET, este carimbo de data e hora corresponde ao carimbo de data e hora de createdAt.
  • callbackUrl — O callback para eventos do URL Experience Composer (caso tenha sido definido). Consulte Configurando callbacks.
  • nome — O nome do Experience Composer (caso tenha sido especificado).
  • url — Uma URL acessível ao público, controlada pelo cliente e capaz de gerar o conteúdo a ser exibido sem a intervenção do usuário.
  • resolução — A resolução do Experience Composer (seja “640x480”, “1280x720”, “480x640” ou “720x1280”).
  • status — O status do Experience Composer. Verifique com frequência para acompanhar as atualizações de status. Essa propriedade pode assumir um dos seguintes valores:
    • "inicializando" — A plataforma da Video API da Vonage está se conectando ao aplicativo remoto no URL fornecido. Este é o estado inicial.
    • "iniciada" — A plataforma da Video API da Vonage se conectou com sucesso ao servidor de aplicativos remoto e está publicando a visualização da web em um fluxo do OpenTok.
    • "parou" — O Experience Composer foi encerrado.
    • "falha" — Ocorreu um erro e o Experience Composer não pôde prosseguir. Isso pode ocorrer na inicialização se o servidor OpenTok não conseguir se conectar ao servidor de aplicativos remoto ou republicar o stream. Também pode ocorrer a qualquer momento durante o processo devido a um erro na plataforma da Video API da Vonage.
  • motivo — O campo “motivo” só fica disponível quando o status é “interrompido” ou “falha”. Se o status for “interrompido”, o campo “motivo” conterá “Duração máxima excedida” ou “Interrupção solicitada”. Se o status for “falha”, o motivo conterá uma mensagem de erro mais específica.
  • streamId — O ID do stream composto que está sendo publicado. O streamId não está disponível quando o status é “starting” e pode não estar disponível quando o status é “failed”.

A resposta HTTP terá um dos seguintes códigos de status:

  • 200 — Sucesso
  • 400 — Solicitação inválida
  • 403 — Erro de autenticação
  • 404 — Não foi encontrado nenhum compositor com o ID especificado.
  • 500 — Erro na plataforma da Video API da Vonage.

Exemplo

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;

Como obter uma lista de compositores experientes

Use este método para obter uma lista dos Compositores de Experiência associados a um projeto.

HTTP GET para renderizar

Envie uma solicitação HTTP GET para a seguinte URL:

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

Substituir <apiKey> com sua chave da API do OpenTok. Os seguintes parâmetros de consulta opcionais podem ser adicionados:

  • offset — O deslocamento inicial da lista de Compositores de Experiências. O valor padrão é 0.
  • count — O número de Experience Composers a serem recuperados a partir do deslocamento. O valor padrão é 50 e o máximo é 1.000.

Propriedades do cabeçalho GET

Autentique esta chamada de API usando um cabeçalho HTTP personalizado — X-OPENTOK-AUTH — definido como um token JSON da Web. Consulte Autenticação.

Resposta

Os dados brutos da resposta HTTP, com código de status 200, são uma mensagem codificada em JSON com o seguinte formato:

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

O objeto JSON inclui as seguintes propriedades:

  • contagem — O número total de Compositores de Experiência.
  • itens — A matriz que contém os Experience Composers recuperados. Cada item do Experience Composer inclui as seguintes propriedades:
    • id — O ID exclusivo do Experience Composer.
    • sessionId — O ID da sessão do OpenTok.
    • projectId — Sua chave da API do OpenTok.
    • createdAt — A hora em que o Experience Composer foi iniciado, expressa em milissegundos desde a época Unix (1º de janeiro de 1970, 00:00:00 UTC).
    • updatedAt — Para este método GET, este carimbo de data e hora corresponde ao carimbo de data e hora de createdAt.
    • callbackUrl — A URL de retorno de chamada para eventos do Experience Composer (caso tenha sido definida). Consulte Configurando callbacks.
    • nome — O nome do Experience Composer (caso tenha sido especificado).
    • url — Uma URL acessível ao público, controlada pelo cliente e capaz de gerar o conteúdo a ser exibido sem a intervenção do usuário.
    • resolução — A resolução do Experience Composer (seja “640x480”, “1280x720”, “480x640” ou “720x1280”).
    • status — O status do Experience Composer. Verifique com frequência para acompanhar as atualizações de status. Essa propriedade pode assumir um dos seguintes valores:
      • "inicializando" — A plataforma da Video API da Vonage está se conectando ao aplicativo remoto no URL fornecido. Este é o estado inicial.
      • "iniciada" — A plataforma da Video API da Vonage se conectou com sucesso ao servidor de aplicativos remoto e está publicando a visualização da web em um fluxo do OpenTok.
      • "parou" — O Experience Composer foi encerrado.
      • "falha" — Ocorreu um erro e o Experience Composer não pôde prosseguir. Isso pode ocorrer na inicialização se o servidor OpenTok não conseguir se conectar ao servidor de aplicativos remoto ou republicar o stream. Também pode ocorrer a qualquer momento durante o processo devido a um erro na plataforma da Video API da Vonage.
    • motivo — O campo “motivo” só fica disponível quando o status é “interrompido” ou “falha”. Se o status for “interrompido”, o campo “motivo” conterá “Duração máxima excedida” ou “Interrupção solicitada”. Se o status for “falha”, o motivo conterá uma mensagem de erro mais específica.
    • streamId — O ID do stream composto que está sendo publicado. O streamId não está disponível quando o status é “starting” e pode não estar disponível quando o status é “failed”.

A resposta HTTP terá um dos seguintes códigos de status:

  • 200 — Sucesso
  • 403 — Erro de autenticação
  • 500 — Erro na plataforma da Video API da Vonage.

Exemplo

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

Interrompendo um Experience Composer

Use este método para encerrar um Experience Composer de uma sessão do OpenTok. Observe que, por padrão, os Experience Composers são encerrados automaticamente 2 horas após seu início. Você também pode definir um valor diferente para `maxDuration` ao criar o Experience Composer. Quando o Experience Composer é encerrado, um evento é enviado para a URL de retorno de chamada, caso você tenha configurei um para o projeto.

HTTP DELETE para renderizar

Envie uma solicitação HTTP DELETE para a seguinte URL:

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

Substituir <apiKey> com sua chave da API do OpenTok. Substitua <experienceComposerId> com o ID do Experience Composer que você deseja interromper. Você obtém o ID do Experience Composer a partir da resposta recebida ao iniciar um Experience Composer.

Excluir propriedades do cabeçalho

Autentique esta chamada de API usando um cabeçalho HTTP personalizado — X-OPENTOK-AUTH — definido como um token JSON da Web. Consulte Autenticação.

Resposta

A resposta HTTP terá um dos seguintes códigos de status:

  • 204 — Sem conteúdo.
  • 400 — Solicitação inválida.
  • 403 — Erro de autenticação.
  • 404 — O Experience Composer (com o ID especificado) não foi encontrado ou já foi encerrado.
  • 500 — Erro na plataforma da Video API da Vonage.

Exemplo

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

Iniciando uma conexão WebSocket do Audio Connector

Use este método para enviar áudio de uma sessão da Video API da Vonage para um WebSocket.

Para obter mais informações, incluindo detalhes sobre os dados do WebSocket, consulte o Guia do desenvolvedor do Audio Connector.

HTTP POST para se conectar

Envie uma solicitação HTTP POST para a seguinte URL:

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

Substituir <apiKey> com sua chave da API do OpenTok.

Propriedades do cabeçalho POST

Defina o Content-Type cabeçalho para application/json.

Autentique esta chamada de API usando um cabeçalho HTTP personalizado — X-OPENTOK-AUTH — definido como um token JSON da Web. Consulte Autenticação.

Dados POST

Inclua um objeto JSON no formato a seguir como conteúdo do corpo da solicitação:

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

O objeto JSON inclui as seguintes propriedades:

  • sessionId​ (obrigatório) — O ID da sessão do OpenTok que inclui os fluxos do OpenTok que você deseja incluir no fluxo do WebSocket. O recurso Audio Connector é compatível apenas com sessões roteadas (sessões que utilizam o Roteador de mídia OpenTok).

  • token​ (obrigatório) — O token do OpenTok a ser usado para a conexão do Audio Connector com a sessão do OpenTok. Você pode adicionar um token data para identificar se a conexão é o ponto de extremidade do Audio Connector ou para obter outros dados de identificação. (As bibliotecas de cliente do OpenTok incluem propriedades para analisar os dados de conexão de um cliente conectado a uma sessão.) Se você for usar o Audio Connector para publicar áudio na sessão, defina a função do token como publisher ou moderator. Veja o Criação de tokens guia do desenvolvedor.

  • websocket ​(obrigatório): Detalhes incluídos para o WebSocket:

    • uri ​(obrigatório): Um URI de WebSocket acessível ao público a ser usado como destino do fluxo de áudio (como “wss://example.com/ws-endpoint”).

    • streams (opcional) — Uma matriz de IDs de transmissões do OpenTok que você deseja incluir no áudio do WebSocket. Se você omitir essa propriedade, todas as transmissões da sessão serão incluídas.

    • headers​ (opcional) — Um objeto contendo pares chave-valor de cabeçalhos a serem enviados ao seu servidor WebSocket a cada mensagem, com comprimento máximo de 512 bytes.

    • audioRate (opcional) — Um número que representa a taxa de amostragem de áudio em Hz. Os valores aceitos são 8.000, 16.000 (padrão) e 24.000.

    • audioTransport (opcional) — Um objeto JSON que configura como o áudio é serializado na conexão WebSocket. Por padrão, o áudio é enviado como quadros binários PCM de 16 bits sem processamento. Defina essa opção para usar áudio base64 encapsulado em JSON, o que é exigido por alguns fornecedores de IA (por exemplo, o OpenAI Realtime). O objeto possui as seguintes propriedades:

      • transport (obrigatório) — "binary" (PCM16 bruto, a configuração padrão) ou "json".
      • encoding (obrigatório quando o transporte for "json") — "base64".
      • audio_field (opcional) — A chave JSON para os dados de áudio de saída. O valor padrão é "audio".
      • receive_audio_field (opcional) — A chave JSON para dados de áudio de entrada (quando a opção bidirecional estiver ativada). O valor padrão é o mesmo que audio_field.
      • static_fields (opcional) — Um objeto com pares adicionais de chave-valor incluído em todas as mensagens de áudio JSON enviadas.

    • bidirectional (opcional) — (booleano) Indica se os dados de áudio da conexão WebSocket devem ser enviados para um stream publicado na sessão. O valor padrão é false (o WebSocket não é usado para publicar um fluxo). Veja mais detalhes no Guia do desenvolvedor do Audio Connector.

Resposta

Uma chamada bem-sucedida resulta em uma resposta HTTP com o código de status 200, com detalhes incluídos nos dados da resposta JSON:

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

Os dados da resposta JSON incluem as seguintes propriedades:

  • id — Um ID exclusivo que identifica a conexão WebSocket do Audio Connector.

  • connectionId — O ID de conexão do OpenTok para a conexão WebSocket do Audio Connector na sessão do OpenTok.

Em caso de erro, a resposta HTTP apresentará um dos seguintes códigos de status:

  • 400 — Solicitação inválida. Essa resposta pode indicar que os dados da sua solicitação estão em formato JSON inválido ou que uma das propriedades JSON está inválida.
  • 403 — Erro de autenticação.
  • 409 — Somente sessões encaminhadas têm permissão para iniciar conexões WebSocket do Audio Connector.
  • 500 — Erro no servidor OpenTok.

Exemplo

Iniciando um WebSocket do Audio Connector:

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

Criação de uma nova chave de API do projeto

Use este método para criar uma chave e um segredo da API do OpenTok para um projeto.

Importante: Depois de criar o projeto, pode levar até 60 segundos para que ele fique disponível para uso.

Você também pode criar um novo projeto no seu Account da Video API da Vonage página.

POST para parceiro

Envie uma solicitação HTTP POST para a seguinte URL:

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

Propriedades do cabeçalho POST

Se você for enviar dados de solicitação para definir um nome (consulte a próxima seção, “Dados POST”), defina o Content-Type cabeçalho para application/json. Caso contrário, não defina o Content-Type cabeçalho.

Autentique esta chamada de API usando um cabeçalho HTTP personalizado — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Defina este cabeçalho como um token JWT (consulte Autenticação). Observe que é necessário usar o no nível da conta Chave da API e no nível da conta API segredo ao criar o token. A chave e o segredo da API no nível da conta estão disponíveis apenas para administradores registrados da sua conta OpenTok.

Dados POST

Inclua um objeto JSON no formato a seguir como conteúdo do corpo da solicitação:

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

Se você não quiser definir um nome para o projeto, não inclua nenhum conteúdo no corpo do texto.

Resposta HTTP

A resposta HTTP terá um dos seguintes códigos de status:

  • 200 — Sucesso. Os dados da resposta são um detalhes do projeto objeto.

  • 400 — Solicitação inválida. Essa resposta pode indicar que os dados em sua solicitação estão no formato JSON inválido.

  • 403 — Erro de autenticação.

  • 500 — Erro no servidor OpenTok.

Exemplo

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

Alteração do status de uma chave de API de projeto

Os administradores de conta podem usar esse método para alterar o status de um projeto. O status pode ser “ativo” ou “suspenso”. Se o status de um projeto estiver “suspenso”, você não poderá usar a chave de API do projeto (nem quaisquer sessões do OpenTok criadas com ela).

É possível alterar o status de um projeto de “ativo” para “suspenso” e vice-versa.

PUT para parceiro

Envie uma solicitação HTTP PUT para a seguinte URL:

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

Onde <api_key> é a chave da API do projeto.

Propriedades do cabeçalho PUT

Defina o Content-Type cabeçalho para application/json.

Autentique esta chamada de API usando um cabeçalho HTTP personalizado — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Defina este cabeçalho como um token JWT (consulte Autenticação). Observe que é necessário usar o no nível da conta Chave da API e no nível da conta API segredo ao criar o token. A chave e o segredo da API no nível da conta estão disponíveis apenas para administradores registrados da sua conta OpenTok.

Dados de PUT

Inclua um objeto JSON no formato a seguir como conteúdo do corpo da solicitação:

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

Resposta HTTP

A resposta HTTP terá um dos seguintes códigos de status:

  • 200 — Sucesso. Os dados da resposta são os detalhes do projeto objeto.

  • 400 — Solicitação inválida. Essa resposta pode indicar que os dados em sua solicitação estão no formato JSON inválido.

  • 403 — Erro de autenticação.

  • 500 — Erro no servidor OpenTok.

Exemplo

O exemplo a seguir define o status do projeto “Acme” como suspenso:

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

Excluindo um projeto

Use este método para excluir um projeto. Isso impede o uso da chave da API do projeto (e de quaisquer sessões do OpenTok criadas com ela).

Você também pode, temporariamente, suspender a chave de API de um projeto.

Observação: Você também pode excluir um projeto na sua Account da Video API da Vonage página.

EXCLUIR do parceiro

Envie uma solicitação HTTP DELETE para a seguinte URL:

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

Onde <api_key> é a chave da API do projeto.

Excluir propriedades do cabeçalho

Autentique esta chamada de API usando um cabeçalho HTTP personalizado — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Defina este cabeçalho como um token JWT (consulte Autenticação). Observe que é necessário usar o no nível da conta Chave da API e no nível da conta API segredo ao criar o token. A chave e o segredo da API no nível da conta estão disponíveis apenas para administradores registrados da sua conta OpenTok.

Resposta HTTP

A resposta HTTP terá um dos seguintes códigos de status:

  • 204 — Sucesso (sem conteúdo).
  • 403 — Erro de autenticação.
  • 404 — Não encontrado. Não há nenhum projeto associado à chave de API fornecida.
  • 500 — Erro no servidor OpenTok.

Exemplo

O exemplo a seguir exclui um projeto:

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

Obter informações sobre projetos

Use este método para obter um registro de detalhes do projeto que descreva o projeto (ou para obter os registros de todos os projetos). Consulte detalhes do projeto objeto.

Torne-se um parceiro da GET

Para obter informações sobre um projeto específico, envie uma solicitação GET para a seguinte URL:

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

Onde <api_key> é a chave da API do projeto.

Para obter informações sobre todos os seus projetos, envie uma solicitação GET para a seguinte URL:

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

Propriedades do cabeçalho GET

Autentique esta chamada de API usando um cabeçalho HTTP personalizado — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Defina este cabeçalho como um token JWT (consulte Autenticação). Observe que é necessário usar o no nível da conta Chave da API e no nível da conta API segredo ao criar o token. A chave e o segredo da API no nível da conta estão disponíveis apenas para administradores registrados da sua conta OpenTok.

Resposta HTTP

A resposta HTTP terá um dos seguintes códigos de status:

  • 200 — Sucesso. Os dados da resposta são o objeto de detalhes do projeto ou uma matriz de objetos de detalhes do projeto. Consulte detalhes do projeto objeto.

  • 403 — Erro de autenticação.

  • 404 — Não encontrado. Não há nenhum projeto associado à chave de API fornecida.

  • 500 — Erro no servidor OpenTok.

### Exemplo

O exemplo a seguir obtém detalhes sobre um projeto específico:

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

A resposta é um JSON detalhes do projeto objeto.

O exemplo a seguir obtém detalhes de todos os seus projetos:

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

A resposta é uma matriz de detalhes do projeto objetos.

Gerando um novo segredo de API do projeto

Por motivos de segurança, talvez seja recomendável gerar um novo segredo de API para um projeto.

Observação: Utilize o novo segredo da API em todas as chamadas à API REST e com os SDKs do lado do servidor da OpenTok. Ao gerar um novo segredo da API, todos os existentes tokens de cliente perderão a validade (e não poderão ser usados para se conectar a sessões do OpenTok); use o novo segredo da API com o Client SDK do servidor do OpenTok para gerar tokens de cliente.

POST para atualizar o segredo

Envie uma solicitação HTTP POST para a seguinte URL:

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

Onde <api_key> é a chave da API do projeto.

Propriedades do cabeçalho POST

Autentique esta chamada de API usando um cabeçalho HTTP personalizado — X-OPENTOK-AUTH:

X-OPENTOK-AUTH:<token>

Defina este cabeçalho como um token JWT (consulte Autenticação). Observe que é necessário usar o no nível da conta Chave da API e no nível da conta API segredo ao criar o token. A chave e o segredo da API no nível da conta estão disponíveis apenas para administradores registrados da sua conta OpenTok.

Resposta HTTP

A resposta HTTP terá um dos seguintes códigos de status:

  • 200 — Sucesso. Os dados da resposta são os detalhes do projeto objeto, com o novo segredo da API.

  • 403 — Erro de autenticação.

  • 404 — Não encontrado. Não há nenhum projeto associado à chave de API fornecida.

  • 500 — Erro no servidor OpenTok.

Exemplo

O exemplo a seguir gera um novo segredo de API do projeto:

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