次の方法で共有

JavaScript 用 Azure Remote Rendering クライアント ライブラリ - バージョン 1.0.0-beta.1

  • [アーティクル]

Azure Remote Rendering (ARR) は、高品質でインタラクティブな 3D コンテンツをクラウドでレンダリングし、HoloLens 2 などのデバイスにリアルタイムでストリーム配信できるようにするサービスです。

この SDK には、資産をランタイムで想定される形式に変換する機能と、リモート レンダリング セッションの有効期間を管理する機能が用意されています。

注: セッションが実行されると、クライアント アプリケーションは"ランタイム SDK" のいずれかを使用してセッションに接続します。 これらの SDK は、3D レンダリングを実行する対話型アプリケーションのニーズを最もよくサポートするように設計されています。 これらは (.net または (C++) で使用できます。

製品ドキュメント

作業の開始

現在サポートされている環境

前提条件

このパッケージを使用するには、Azure サブスクリプションと Azure Remote Rendering アカウントが必要です。

@azure/mixed-reality-remote-rendering パッケージのインストール

を使用して JavaScript 用テンプレート クライアント ライブラリを npmインストールします。

npm install @azure/mixed-reality-remote-rendering

ブラウザーのサポート

JavaScript バンドル

ブラウザーでこのクライアント ライブラリを使用するには、まず bundler を使用する必要があります。 これを行う方法の詳細については、 バンドルに関するドキュメントを参照してください。

CORS

このライブラリを使用して、ブラウザーから Azure Remote Rendering サービスに直接呼び出すことはできません。 ガイダンスについては、 こちらのドキュメント を参照してください。

クライアントを認証する

リモート レンダリング クライアントを構築するには、認証されたアカウントとリモート レンダリング エンドポイントが必要です。 eastus リージョンで作成されたアカウントの場合、アカウント ドメインの形式は "eastus.mixedreality.azure.com" になります。 認証にはいくつかの異なる形式があります。

  • アカウント キー認証
    • アカウント キーを使用すると、Azure Remote Renderingの使用をすばやく開始できます。 ただし、アプリケーションを運用環境にデプロイする前に、Azure AD 認証を使用するようにアプリを更新することをお勧めします。
  • Azure Active Directory (AD) トークン認証
    • エンタープライズ アプリケーションをビルドしていて、会社の ID システムとして Azure AD を使用している場合は、アプリ内でユーザーベースの Azure AD 認証を使用できます。 その後、既存の Azure AD セキュリティ グループを使用して、Azure Remote Rendering アカウントへのアクセス権を付与します。 組織内のユーザーに直接アクセス権を付与することもできます。
    • それ以外の場合は、アプリをサポートしている Web サービスから Azure AD トークンを取得することをお勧めします。 Azure Spatial Anchors にアクセスするための資格情報をクライアント アプリケーションに埋め込むことを回避できるため、運用アプリケーションではこの方法をお勧めします。

詳細な手順と情報については、 こちらを 参照してください。

次のすべての例では、クライアントは を remoteRenderingEndpoint使用して構築されます。 使用可能なエンドポイントはリージョンに対応しており、エンドポイントの選択によって、サービスがその作業を実行するリージョンが決まります。 たとえば https://remoterendering.eastus2.mixedreality.azure.com です。

注: 資産を変換する場合は、資産を含むストレージに近いリージョンを選択することをお勧めします。

注: レンダリングの場合は、サービスを使用するデバイスに最も近いリージョンを選択することを強くお勧めします。 サーバーとの通信にかかった時間は、エクスペリエンスの品質に影響します。

アカウント キー認証を使用した認証

AccountKeyCredential認証にアカウント識別子とアカウント キーを使用するには、 オブジェクトを使用します。

const credential = new AzureKeyCredential(accountKey);

const client = new RemoteRenderingClient(serviceEndpoint, accountId, accountDomain, credential);

AAD クライアント シークレットを使用した認証

オブジェクトを ClientSecretCredential 使用して、クライアント シークレット認証を実行します。

let credential = new ClientSecretCredential(tenantId, clientId, clientSecret, {
  authorityHost: "https://login.microsoftonline.com/" + tenantId
});

const client = new RemoteRenderingClient(serviceEndpoint, accountId, accountDomain, credential);

デバイス コード認証を使用したユーザーの認証

オブジェクトを DeviceCodeCredential 使用して、デバイス コード認証を実行します。

let deviceCodeCallback = (deviceCodeInfo: DeviceCodeInfo) => {
  console.debug(deviceCodeInfo.message);
  console.log(deviceCodeInfo.message);
};

let credential = new DeviceCodeCredential(tenantId, clientId, deviceCodeCallback, {
  authorityHost: "https://login.microsoftonline.com/" + tenantId
});

const client = new RemoteRenderingClient(serviceEndpoint, accountId, accountDomain, credential);

デバイス コード認証フローの使用の詳細については、 こちらを 参照してください。

DefaultAzureCredential を使用した対話型認証

を使用して、既定の DefaultAzureCredential 対話型認証フローを使用します includeInteractiveCredentials: true 。

let credential = new DefaultAzureCredential();

return new RemoteRenderingClient(serviceEndpoint, accountId, accountDomain, credential, {
  authenticationEndpointUrl: "https://sts.mixedreality.azure.com"
});

静的アクセス トークンを使用した認証

Mixed Realityアクセス トークンは、Mixed Reality STS サービスから以前に取得した としてAccessToken渡し、Mixed Reality クライアント ライブラリで使用できます。

// GetMixedRealityAccessTokenFromWebService is a hypothetical method that retrieves
// a Mixed Reality access token from a web service. The web service would use the
// MixedRealityStsClient and credentials to obtain an access token to be returned
// to the client.
const accessToken = GetMixedRealityAccessTokenFromWebService();

RemoteRenderingClient client = new RemoteRenderingClient(remoteRenderingEndpoint, accountId, accessToken);

主要な概念

RemoteRenderingClient

RemoteRenderingClientは、RemoteRenderingService にアクセスするために使用されるクライアント ライブラリです。 アセットの変換とレンダリング セッションを作成および管理する方法を提供します。

例

単純な資産を変換する

RemoteRenderingClient は、「 クライアントの認証 」セクションの説明に従って構築されていることを前提としています。 次のスニペットでは、指定された URI の BLOB コンテナーのルートにある "box.fbx" が変換されるように要求する方法について説明します。

const inputSettings: AssetConversionInputSettings = {
  storageContainerUrl,
  relativeInputAssetPath: "box.fbx"
};
const outputSettings: AssetConversionOutputSettings = {
  storageContainerUrl
};
const conversionSettings: AssetConversionSettings = { inputSettings, outputSettings };

// A randomly generated UUID is a good choice for a conversionId.
const conversionId = uuid();

const conversionPoller: AssetConversionPollerLike = await client.beginConversion(
  conversionId,
  conversionSettings
);

出力ファイルは、入力アセットの横に配置されます。

より複雑な資産を変換する

資産は他のファイルを参照でき、BLOB コンテナーにはさまざまな資産に属するファイルを含めることができます。 この例では、プレフィックスを使用して BLOB を整理する方法と、その組織を考慮して資産を変換する方法を示します。 の inputStorageUrl BLOB コンテナーには、"Bicycle/bicycle.gltf"、"Bicycle/bicycle.bin"、"Bicycle/saddleTexture.jpg" などの多くのファイルが含まれているとします。 (したがって、プレフィックス "Bicycle" はフォルダーのように動作します)。glTF を変換して、プレフィックスを共有する他のファイルにアクセスできるようにし、変換サービスが他のファイルにアクセスする必要はありません。 整理を維持するために、出力ファイルを別のストレージ コンテナーに書き込み、共通のプレフィックス "ConvertedBicycle" を指定することもできます。 コードは次のとおりです。

  const inputSettings: AssetConversionInputSettings = {
    storageContainerUrl: inputStorageUrl,
    blobPrefix: "Bicycle"
    relativeInputAssetPath: "bicycle.gltf"
  };
  const outputSettings: AssetConversionOutputSettings = {
    storageContainerUrl: outputStorageUrl,
    blobPrefix: "ConvertedBicycle"
  };
  const conversionSettings: AssetConversionSettings = { inputSettings, outputSettings };

  const conversionId = uuid();

  const conversionPoller: AssetConversionPollerLike = await client.beginConversion(
    conversionId,
    conversionSettings
  );

注: 入力オプションにプレフィックスが指定されている場合、入力ファイル パラメーターはそのプレフィックスに対する相対パスであると見なされます。 出力オプションの出力ファイル パラメーターにも同じことが当てはまります。

資産の変換が完了したときに出力を取得する

資産の変換には、数秒から数時間かかる場合があります。 このコードでは、beginConversion によって返された conversionPoller を使用して、変換が完了または失敗するまで定期的にポーリングします。 既定のポーリング期間は 10 秒です。

const conversion = await conversionPoller.pollUntilDone();

console.log("== Check results ==");

if (conversion.status === "Succeeded") {
  console.log("Conversion succeeded: Output written to " + conversion.output?.outputAssetUrl);
} else if (conversion.status === "Failed") {
  console.log("Conversion failed: " + conversion.error.code + " " + conversion.error.message);
}

AssetConversionPollerLike の状態は、conversionPoller.toString() を呼び出すことによってシリアル化できることに注意してください。 その値を後で beginConversion に値として resumeFrom 渡して、前の値が中断された場所から引き継ぐ新しいポーリングャーを構築できます。

const serializedPollerString = conversionPoller.toString();
// ...
const resumedPoller = client.beginConversion({ resumeFrom: serializedPollerString });

リスト変換

変換に関する情報は、 メソッドを getConversions 使用して取得できます。 このメソッドは、まだ開始していない変換、実行中の変換、完了した変換を返す場合があります。 この例では、最後の日に開始された成功した変換の出力 URI を一覧表示します。

for await (const conversion of client.listConversions()) {
  if (conversion.status === "Succeeded") {
    console.log(
      `Conversion ${conversion.conversionId} succeeded: Output written to ${conversion.output?.outputAssetUrl}`
    );
  } else if (conversion.status === "Failed") {
    console.log(
      `Conversion ${conversion.conversionId} failed: ${conversion.error.code} ${conversion.error.message}`
    );
  }
}

セッションを作成する

RemoteRenderingClient は、「 クライアントの認証 」セクションの説明に従って構築されていることを前提としています。 次のスニペットでは、新しいレンダリング セッションの開始を要求する方法について説明します。

const sessionSettings: RenderingSessionSettings = {
  maxLeaseTimeInMinutes: 4,
  size: "Standard"
};

// A randomly generated UUID is a good choice for a conversionId.
const sessionId = uuid();

const sessionPoller: RenderingSessionPollerLike = await client.beginSession(
  sessionId,
  sessionSettings
);

RenderingSessionPollerLike の状態は、toString() を呼び出すことによってシリアル化できることに注意してください。 その値を後で beginSession に値として resumeFrom 渡して、前の値が中断された場所から引き継ぐ新しいポーリングャーを構築できます。

const serializedPollerString = sessionPoller.toString();
// ...
const resumedPoller = client.beginSession({ resumeFrom: serializedPollerString });

セッションのリース時間を延長する

セッションが最大リース時間に近づいているが、それを維持したい場合は、最大リース時間を長くするために呼び出しを行う必要があります。 この例では、現在のプロパティに対してクエリを実行し、間もなく期限が切れる場合にリースを拡張する方法を示します。

注: ランタイム SDK にもこの機能が用意されており、多くの一般的なシナリオでは、それらを使用してセッション リースを拡張します。

/// When the lease is within 2 minutes of expiring, extend it by 15 minutes.
let currentSession = await client.getSession(sessionId);
if (currentSession.status == "Ready") {
  if (
    currentSession.maxLeaseTimeInMinutes -
      (Date.now() - currentSession.properties.createdOn.valueOf()) / 60000 <
    2
  ) {
    let newLeaseTime = currentSession.maxLeaseTimeInMinutes + 15;

    await client.updateSession(sessionId, { maxLeaseTimeInMinutes: newLeaseTime });
  }
}

セッションを一覧表示する

メソッドを使用して、セッションに関する情報を getSessions 取得できます。 このメソッドは、まだ開始していないセッションと準備ができているセッションを返す場合があります。

for await (const session of client.listSessions()) {
  console.log(`Session ${session.sessionId} is ${session.status}`);
}

セッションを停止する

次のコードは、指定された ID を持つ実行中のセッションを停止します。

client.endSession(sessionId);

トラブルシューティング

ログの記録

ログの記録を有効にすると、エラーに関する有用な情報を明らかにするのに役立つ場合があります。 HTTP 要求と応答のログを表示するには、環境変数 AZURE_LOG_LEVEL を info に設定します。 または、@azure/logger で setLogLevel を呼び出して、実行時にログ記録を有効にすることもできます。

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Azure Remote Renderingのトラブルシューティング

Azure Remote Renderingに関する一般的なトラブルシューティングのアドバイスについては、「docs.microsoft.com でのリモート レンダリングのトラブルシューティング」ページを参照してください。

要求を行うことができない場合、クライアント メソッドは例外をスローします。 ただし、変換とセッションの両方の場合、要求は成功しますが、要求された操作は成功しない可能性があります。 この場合、例外はスローされませんが、返されたオブジェクトを調べて何が起こったかを理解できます。

変換中の資産が無効な場合、変換操作は、失敗状態の AssetConversion オブジェクトを返し、詳細を含む RemoteRenderingServiceError を実行します。 変換サービスがファイルを処理できるようになると <、assetName.result.json> ファイルが出力コンテナーに書き込まれます。 入力資産が無効な場合、そのファイルには問題の詳細な説明が含まれます。

同様に、セッションが要求されると、セッションがエラー状態になることがあります。 startSessionOperation メソッドは RenderingSession オブジェクトを返しますが、そのオブジェクトの状態は Error になり、詳細を含む RemoteRenderingServiceError が実行されます。

次の手順

共同作成

このライブラリに投稿する場合、コードをビルドしてテストする方法の詳細については、投稿ガイドを参照してください。

インプレッション数