Skip to main content

Referência da API HappyOyster-Adventure-Enter Travel

O cliente usa o ticket para criar uma Travel real e obter a configuração de entrada RTC e a versão da capacidade do Adventure. maxExperienceTimeSec tem efeito apenas no modelo Adventure.

Escopo

O cliente usa o ticket para criar uma Travel real e obter a configuração de entrada RTC. maxExperienceTimeSec tem efeito apenas no modelo Adventure. Antes de chamar, confirme o seguinte:
  • Autenticação: A API Key primária não é obrigatória; o ticket completa a validação de entrada na sala. Para saber como obtê-lo, veja Obter credenciais de autenticação.
  • Pré-requisitos: O ticket é obtido em Obter Credencial da Travel, não está expirado nem foi usado, e o status do seu Mundo é ready.
  • Chamador: Chamado pelo seu cliente.

Solicitação HTTP

  • Singapore
  • China (Pequim)
  • EUA (Virgínia)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/travels/enter-travelSubstitua {WorkspaceId} pelo seu ID do Workspace real.

Parâmetros da solicitação

  • Entrar na travel (cliente)
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/travels/enter-travel' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "ticket": "{ticket}",
    "maxExperienceTimeSec": 90
}'
Content-Typestring(Obrigatório)Tipo de conteúdo da solicitação. Este parâmetro deve ser definido como application/json.
Authorization string (Obrigatório)Autenticação por Chave de API. A Chave de API primária não é obrigatória; tanto a chave primária quanto uma temporária podem chamá-lo.
  • API Key Primária: começa com sk-, ex. sk-xxx.
  • Chave de API Temporária: começa com st-, por exemplo, st-xxx.
Corpo da solicitação
ticket string (Obrigatório)Uma credencial de uso único, não expirada e não utilizada, obtida em Obter Credencial da Travel. Reutilizar o mesmo ticket retorna 401011.
maxExperienceTimeSec integer (Opcional)Duração máxima da experiência, em segundos, deve ser um inteiro JSON. O padrão é 60. Valores permitidos:
  • 60
  • 90
  • 120
Strings e outros valores numéricos não são aceitos (por exemplo, "60" não é válido); um nível inválido retorna 400000. O servidor encerra automaticamente a Travel assim que essa duração é atingida.

Parâmetros de resposta

  • Entrada bem-sucedida
{
    "code": 0,
    "message": null,
    "data": {
        "encryptedTravelId": "trvl_a1b2****",
        "encryptedWorldId": "enc_a1b2****",
        "mode": 1,
        "creationModel": "simple",
        "playUrl": null,
        "firstFrame": "https://cdn.happyoyster.com/frames/world_xyz789.jpg",
        "rtcConfig": {
            "channelId": "stream_abc123",
            "appId": "18bca2e3218c46aebf8ff3a32fb12311",
            "token": "007eJxTYOh...",
            "userId": "user_1"
        },
        "version": "wanderV2",
        "aspectRatio": null,
        "noStreamAutoEndTimeoutSec": 30,
        "maxExperienceTimeSec": 90
    }
}
code integerCódigo de retorno. 0 indica sucesso; diferente de zero é um código de erro.
message stringMensagem de erro. null em caso de sucesso.
data objectDados da resposta. null em caso de falha.

Propriedades

encryptedTravelId stringO ID criptografado da Travel recém-criada. Usado para consultas subsequentes de Status da Travel, encerramento e artefatos.encryptedWorldId stringO ID criptografado do Mundo ao qual esta Travel corresponde.mode integerSempre 1 para Adventure.creationModel stringSempre simple para Adventure.playUrl nullAinda não disponível; fixado em null.firstFrame stringURL do primeiro quadro do Mundo.rtcConfig objectConfiguração de entrada RTC; null quando não há canal de streaming disponível, caso em que o cliente não pode iniciar a reprodução com base nela.
  • channelId: ID do canal RTC
  • appId: ID do aplicativo RTC atribuído pela plataforma
  • token: Token de entrada RTC
  • userId: ID de usuário de entrada RTC, fixado em user_1
version stringA versão de entrada na sala do Adventure, fixa em wanderV2. Os dados de controle devem ser enviados via SDK sendCommand de acordo com esta versão.aspectRatio nullFixo em null para Adventure; a proporção do player não é lida deste campo e segue a proporção da imagem do primeiro quadro.noStreamAutoEndTimeoutSec integerTempo limite de término automático sem fluxo em segundos, padrão de 30; a resposta real prevalece. Se rtcStatus não entrar no estado de streaming dentro deste tempo após entrar na sala, chame Encerrar Travel com failCode=TRAVEL_NO_STREAM_AUTO_END.maxExperienceTimeSec integerA duração da experiência efetivamente adotada pelo servidor; só pode ser 60 / 90 / 120. O servidor encerra automaticamente a Travel assim que essa duração é atingida.

Estados pré-requisitos e notas de chamada

  • O Mundo correspondente ao ticket deve estar ready, e o ticket não deve estar expirado nem usado.
  • Uma chamada bem-sucedida cria a Travel; reutilizar o mesmo ticket retorna 401011.
  • version deve ser tratado como wanderV2; não envie dados de controle usando o protocolo de interação de outro modelo.
  • O servidor encerra a experiência assim que maxExperienceTimeSec é atingido; o cliente deve lidar com o estado terminal que chega posteriormente.
  • Os controles de direção, ponto de vista e ação do Adventure não são Open APIs HTTP do lado do servidor; o cliente deve usar o sendCommand do SDK da plataforma correspondente, que o SDK envia pelo DataChannel RTC.
  • rtcConfig=null significa que não há atualmente nenhum canal de streaming disponível, e o cliente não pode iniciar a reprodução com base nele.

Códigos de erro

Se a chamada do modelo falhar e retornar um erro, consulte Códigos de Erro do HappyOyster para resolvê-lo.

Próximos passos

Após entrar na sala com sucesso:
  • Consultar Status da Travel: consulte a cada 2–5 segundos para ler o pool de ações disponíveis.
  • Depois que a Travel se torna running, o cliente envia controles de direção, ponto de vista e ação via SDK sendCommand.
  • Encerrar Travel: encerre a sessão e processe os artefatos.