Skip to main content

HappyOyster-Acting-Get Travel Credential API リファレンス

サードパーティサーバーはプライマリ API キーを使用して短命かつ単発の ticket と交換し、それを安全にクライアントへ配信します。このエンドポイントは World の所有権、ステータス、およびクォータのみを検証し、Travel は作成しません。

スコープ

サードパーティサーバーはプライマリ API キーを使用して短命かつ単発の ticket と交換し、それを安全にクライアントへ配信します。呼び出す前に、以下を確認してください：
  • 認証：プライマリ API Key のみがサポートされています。一時的な API Key は使用できません（エラーコード 403003）。
  • 前提条件：World は現在のプライマリアカウントおよび Acting モデルに属している必要があり、そのステータスは ready である必要があります。World ビルドステータスのクエリ で確認してください。
  • 呼び出し元：サーバー から呼び出します。結果として得られる ticket は、すぐに入室しようとしているクライアントにのみ配信する必要があります。

HTTP リクエスト

  • Singapore
  • 米国（バージニア）
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/worlds/get-travel-credential{WorkspaceId} を実際の ワークスペースID に置き換えます。

リクエストパラメーター

  • Travel 資格情報の取得
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v2/apps/happyoyster-1.0-acting/openapi/v1/worlds/get-travel-credential' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "encryptedWorldId": "{encryptedWorldId}"
}'
Content-Typestring（必須）リクエストのコンテンツタイプ。このパラメータは application/json に設定する必要があります。
Authorization string （必須）API Key 認証。プライマリ API Key のみがサポートされており、sk- で始まります（例：sk-xxx）。通常、環境変数 $DASHSCOPE_API_KEY として設定されます。一時的な API Key（st- で始まる）を使用すると 403003 が返されます。
リクエストボディ
encryptedWorldId string （必須）現在のプライマリアカウント配下で、ステータスが ready の Acting World ID です。World の作成 によって返されます。

レスポンスパラメーター

  • 交換成功
{
    "code": 0,
    "message": null,
    "data": {
        "ticket": "tk_a1b2****",
        "expiresIn": 1800,
        "encryptedWorldId": "enc_a1b2****"
    }
}
code integerリターンコード。0 は成功を意味し、ゼロ以外の値はエラーコードです。
message stringエラーメッセージ。成功時は null です。
data objectレスポンスデータ。失敗時は null です。

プロパティ

ticket stringtk_ プレフィックスが付いた1回限りの Travel クレデンシャルです。有効期間は 1800 秒間（30 分間）で、正常に使用できるのは1回のみです。expiresIn integer有効期間（秒）、1800（30 分）に固定されています。encryptedWorldId string資格情報に対応する暗号化 World ID です。

前提条件となるステータスと呼び出しに関する注意事項

  • World は現在のプライマリアカウントおよび Acting モデルに属している必要があり、そのステータスは ready である必要があります。
  • ticketの有効期間は1800秒であり、正常に使用できるのは1回のみです。有効期限切れまたは使用後は、新しいものを取得してください。
  • ticket は、すぐに入室しようとしているクライアントにのみ配信する必要があり、長期アクセス資格情報として永続化すべきではありません。
  • このエンドポイントの呼び出しでは Travel は作成されません。Travel は 入室 が成功した際に作成されます。
  • Acting 機能ゲートは主に作成時および入室時に有効になります。資格情報の交換時も World の対応するクォータが検証され、クォータが有効化されていない場合は 403007 が返されます。

エラーコード

モデルの呼び出しに失敗してエラーが返された場合は、HappyOyster エラーコードを参照して解決してください。

次のステップ

ticket を取得した後：
  • Travel への入室：クライアントは ticket を使用して Travel を作成し、RTC 設定を取得します。