次の方法で共有

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 パッケージをインストールする

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

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

ブラウザーのサポート

JavaScript バンドル

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

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 トークンを取得することをお勧めします。 運用環境のアプリケーションでは、クライアント アプリケーションに資格情報を埋め込むのを回避できるため、この方法をお勧めします。

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

次のすべての例では、クライアントは 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 を使用した対話型認証

既定の対話型認証フローを使用するには、includeInteractiveCredentials: true で DefaultAzureCredential オブジェクトを使用します。

let credential = new DefaultAzureCredential();

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

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

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

// 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() を呼び出すことによってシリアル化できることに注意してください。 その値を後で resumeFrom 値として beginConversion に渡して、前の値が中断された場所から引き継ぐ新しいポーリングャーを構築できます。

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 が実行されます。

次の手順

貢献

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

  • Microsoft Azure SDK for Javascript の

インプレッション