Skip to main content

Referencia de la API HappyOyster-Adventure-Enter Travel

El cliente utiliza el ticket para crear un Travel real y obtener la configuración de unión RTC y la versión de capacidad de Adventure. maxExperienceTimeSec solo tiene efecto en el modelo Adventure.

Ámbito

El cliente utiliza el ticket para crear un Travel real y obtener la configuración de unión RTC. maxExperienceTimeSec solo tiene efecto en el modelo Adventure. Antes de realizar la llamada, confirme lo siguiente:
  • Autenticación: La API Key principal no es obligatoria; el ticket completa la validación de entrada a la sala. Para saber cómo obtenerla, consulte Obtener credenciales de autenticación.
  • Requisitos previos: El ticket se obtiene de Obtener credencial de viaje, no ha caducado y no se ha utilizado, y el estado de su mundo es ready.
  • Solicitante: Invocado por su cliente.

Solicitud HTTP

  • Singapore
  • China (Beijing)
  • EE. UU. (Virginia)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-adventure/openapi/v1/travels/enter-travelReemplace {WorkspaceId} con su ID de espacio de trabajo real.

Parámetros de solicitud

  • Entrar al viaje (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(Requerido)Tipo de contenido de la solicitud. Este parámetro debe establecerse en application/json.
Authorization string (Requerido)Autenticación mediante clave de API. No se requiere la clave de API principal; pueden invocarla tanto la clave principal como una temporal.
  • Clave de API principal: comienza con sk-, por ejemplo, sk-xxx.
  • Clave de API temporal: comienza con st-, por ejemplo, st-xxx.
Cuerpo de la solicitud
ticket string (Obligatorio)Una credencial de un solo uso, no caducada y no utilizada, obtenida de Obtener credencial de viaje. Reutilizar el mismo ticket devuelve 401011.
maxExperienceTimeSec integer (Opcional)Duración máxima de la experiencia, en segundos, debe ser un entero JSON. El valor predeterminado es 60. Valores permitidos:
  • 60
  • 90
  • 120
No se aceptan cadenas ni otros valores numéricos (por ejemplo, "60" no es válido); un nivel no válido devuelve 400000. El servidor finaliza automáticamente el Travel una vez que se alcanza esta duración.

Parámetros de respuesta

  • Entrada exitosa
{
    "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 éxito; un valor distinto de cero es un código de error.
message stringMensaje de error. null en caso de éxito.
data objectDatos de respuesta. null en caso de fallo.

Propiedades

encryptedTravelId stringEl ID de Travel cifrado recién creado. Se utiliza para consultas posteriores de Consultar estado del Travel, finalización y artefactos.encryptedWorldId stringEl ID de mundo cifrado al que corresponde este viaje.mode integerSiempre 1 para Adventure.creationModel stringSiempre simple para Adventure.playUrl nullAún no disponible; fijado en null.firstFrame stringURL del primer fotograma del mundo.rtcConfig objectConfiguración de unión RTC; null cuando no hay ningún canal de transmisión disponible, en cuyo caso el cliente no puede iniciar la reproducción basándose en ella.
  • channelId: ID de canal RTC
  • appId: ID de aplicación RTC asignado por la plataforma
  • token: token de unión RTC
  • userId: ID de usuario de unión RTC, fijado en user_1
version stringLa versión de entrada a la sala de Adventure, fija en wanderV2. Los datos de control deben enviarse a través del SDK sendCommand de acuerdo con esta versión.aspectRatio nullFijo en null para Adventure; la relación de aspecto del reproductor no se lee de este campo y sigue la relación de la imagen del primer fotograma.noStreamAutoEndTimeoutSec integerTiempo de espera de finalización automática sin flujo en segundos, por defecto 30; prevalece la respuesta real. Si rtcStatus no entra en el estado de transmisión dentro de este tiempo después de entrar en la sala, llame a Finalizar viaje con failCode=TRAVEL_NO_STREAM_AUTO_END.maxExperienceTimeSec integerLa duración de la experiencia adoptada realmente por el servidor; solo puede ser 60 / 90 / 120. El servidor finaliza automáticamente el Travel una vez que se alcanza esta duración.

Estados previos y notas de llamada

  • El mundo correspondiente al ticket debe estar ready, y el ticket no debe haber caducado ni haber sido utilizado.
  • Una llamada exitosa crea el viaje; reutilizar el mismo ticket devuelve 401011.
  • version debe manejarse como wanderV2; no envíe datos de control utilizando el protocolo de interacción de otro modelo.
  • El servidor finaliza la experiencia una vez que se alcanza maxExperienceTimeSec; el cliente debe gestionar el estado terminal que llega posteriormente.
  • Los controles de dirección, punto de vista y acción de Adventure no son Open APIs HTTP del lado del servidor; el cliente debe utilizar el sendCommand del SDK de la plataforma correspondiente, que el SDK envía a través del DataChannel RTC.
  • rtcConfig=null significa que actualmente no hay ningún canal de transmisión disponible, y el cliente no puede iniciar la reproducción basándose en él.

Códigos de error

Si la llamada al modelo falla y devuelve un error, consulte Códigos de error de HappyOyster para resolverlo.

Siguientes pasos

Después de entrar en la sala correctamente:
  • Consultar estado del Travel: sondee cada 2–5 segundos para leer el grupo de acciones disponibles.
  • Después de que el Travel se convierta en running, el cliente envía controles de dirección, punto de vista y acción a través del SDK sendCommand.
  • Finalizar Travel: finalice la sesión y gestione los artefactos.