Share via

Java 用 Azure Remote Rendering クライアント ライブラリ - バージョン 1.1.23

  • [アーティクル]

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

この SDK では、アセットをランタイムで想定される形式に変換したり、リモート レンダリング セッションの有効期間を管理したりする機能が提供されます。

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

ソースコード | API リファレンス ドキュメント | 製品ドキュメント

作業の開始

前提条件

パッケージを組み込む

BOM ファイルを含める

ライブラリの一般提供 (GA) バージョンに依存するには、azure-sdk-bom をプロジェクトに含めてください。 次のスニペットでは、{bom_version_to_target} プレースホルダーをバージョン番号に置き換えます。 BOM の詳細については、 AZURE SDK BOM README に関するページを参照してください。

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

次に、次に示すように、バージョン タグを使用せずに、依存関係セクションに直接依存関係を含めます。

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-mixedreality-remoterendering</artifactId>
  </dependency>
</dependencies>

直接依存関係を含める

メモ：このバージョンは、Azure Remote Rendering サービス API バージョン v2021-01-01 を対象とします。

次の Maven 依存関係を追加します。

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-mixedreality-remoterendering</artifactId>
    <version>1.1.23</version>
</dependency>

クライアントを認証する

リモート レンダリング クライアントを構築するには、認証されたアカウントとリモート レンダリング エンドポイントが必要です。 アカウントは、その accountId とアカウント ドメインで構成されます。 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 にアクセスするための資格情報をクライアント アプリケーションに埋め込むことを回避できるため、運用アプリケーションではこの方法をお勧めします。

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

次のすべての例では、クライアントは オブジェクトを使用して RemoteRenderingClientBuilder 構築されます。 各例で説明されている資格情報オブジェクトを除き、パラメーターは常に同じです。 remoteRenderingEndpointパラメーターは、サービスが処理を実行するリージョンを決定する URL です。 たとえば https://remoterendering.eastus2.mixedreality.azure.com です。

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

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

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

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

AzureKeyCredential credential = new AzureKeyCredential(environment.getAccountKey());

RemoteRenderingClient client = new RemoteRenderingClientBuilder()
    .accountId(environment.getAccountId())
    .accountDomain(environment.getAccountDomain())
    .endpoint(environment.getServiceEndpoint())
    .credential(credential)
    .buildClient();

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

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

ClientSecretCredential credential = new ClientSecretCredentialBuilder()
    .tenantId(environment.getTenantId())
    .clientId(environment.getClientId())
    .clientSecret(environment.getClientSecret())
    .authorityHost("https://login.microsoftonline.com/" + environment.getTenantId())
    .build();

RemoteRenderingClient client = new RemoteRenderingClientBuilder()
    .accountId(environment.getAccountId())
    .accountDomain(environment.getAccountDomain())
    .endpoint(environment.getServiceEndpoint())
    .credential(credential)
    .buildClient();

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

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

DeviceCodeCredential credential = new DeviceCodeCredentialBuilder()
    .challengeConsumer((DeviceCodeInfo deviceCodeInfo) -> {
        logger.info(deviceCodeInfo.getMessage());
    })
    .clientId(environment.getClientId())
    .tenantId(environment.getTenantId())
    .authorityHost("https://login.microsoftonline.com/" + environment.getTenantId())
    .build();

RemoteRenderingClient client = new RemoteRenderingClientBuilder()
    .accountId(environment.getAccountId())
    .accountDomain(environment.getAccountDomain())
    .endpoint(environment.getServiceEndpoint())
    .credential(credential)
    .buildClient();

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

DefaultAzureCredential を使用した対話型認証

オブジェクトを使用します DefaultAzureCredential 。

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();

RemoteRenderingClient client = new RemoteRenderingClientBuilder()
    .accountId(environment.getAccountId())
    .accountDomain(environment.getAccountDomain())
    .endpoint(environment.getServiceEndpoint())
    .credential(credential)
    .buildClient();

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

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.
AccessToken accessToken = getMixedRealityAccessTokenFromWebService();

RemoteRenderingClient client = new RemoteRenderingClientBuilder()
    .accountId(environment.getAccountId())
    .accountDomain(environment.getAccountDomain())
    .endpoint(environment.getServiceEndpoint())
    .accessToken(accessToken)
    .buildClient();

主要な概念

RemoteRenderingClient

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

例

単純な資産を変換する

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

AssetConversionOptions conversionOptions = new AssetConversionOptions()
    .setInputStorageContainerUrl(getStorageURL())
    .setInputRelativeAssetPath("box.fbx")
    .setOutputStorageContainerUrl(getStorageURL());

// A randomly generated UUID is a good choice for a conversionId.
String conversionId = UUID.randomUUID().toString();

SyncPoller<AssetConversion, AssetConversion> conversionOperation = client.beginConversion(conversionId, conversionOptions);

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

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

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

AssetConversionOptions conversionOptions = new AssetConversionOptions()
    .setInputStorageContainerUrl(inputStorageURL)
    .setInputRelativeAssetPath("bicycle.gltf")
    .setInputBlobPrefix("Bicycle")
    .setOutputStorageContainerUrl(outputStorageURL)
    .setOutputBlobPrefix("ConvertedBicycle");

String conversionId = UUID.randomUUID().toString();

SyncPoller<AssetConversion, AssetConversion> conversionOperation = client.beginConversion(conversionId, conversionOptions);

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

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

資産の変換には、数秒から数時間かかる場合があります。 このコードでは、既存の conversionOperation を使用し、変換が完了または失敗するまで定期的にポーリングします。 既定のポーリング期間は 10 秒です。 conversionOperation は、既存の変換とクライアントの conversionId から構築できることに注意してください。

AssetConversion conversion = conversionOperation.getFinalResult();
if (conversion.getStatus() == AssetConversionStatus.SUCCEEDED) {
    logger.info("Conversion succeeded: Output written to {}", conversion.getOutputAssetUrl());
} else if (conversion.getStatus() == AssetConversionStatus.FAILED) {
    logger.error("Conversion failed: {} {}", conversion.getError().getCode(), conversion.getError().getMessage());
} else {
    logger.error("Unexpected conversion status: {}", conversion.getStatus());
}

リスト変換

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

for (AssetConversion conversion : client.listConversions()) {
    if ((conversion.getStatus() == AssetConversionStatus.SUCCEEDED)
        && (conversion.getCreationTime().isAfter(OffsetDateTime.now().minusDays(1)))) {
        logger.info("Output Asset URL: {}", conversion.getOutputAssetUrl());
    }
}

レンダリング セッションを作成する

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

BeginSessionOptions options = new BeginSessionOptions()
    .setMaxLeaseTime(Duration.ofMinutes(30))
    .setSize(RenderingSessionSize.STANDARD);

// A randomly generated GUID is a good choice for a sessionId.
String sessionId = UUID.randomUUID().toString();

SyncPoller<RenderingSession, RenderingSession> startSessionOperation = client.beginSession(sessionId, options);

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

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

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

RenderingSession currentSession = client.getSession(sessionId);

Duration sessionTimeAlive = Duration.between(OffsetDateTime.now(), currentSession.getCreationTime()).abs();
if (currentSession.getMaxLeaseTime().minus(sessionTimeAlive).toMinutes() < 2) {
    Duration newLeaseTime = currentSession.getMaxLeaseTime().plus(Duration.ofMinutes(30));
    UpdateSessionOptions longerLeaseOptions = new UpdateSessionOptions().maxLeaseTime(newLeaseTime);
    client.updateSession(sessionId, longerLeaseOptions);
}

レンダリング セッションを一覧表示する

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

for (RenderingSession session : client.listSessions()) {
    if (session.getStatus() == RenderingSessionStatus.STARTING) {
        logger.info("Session {} is starting.");
    } else if (session.getStatus() == RenderingSessionStatus.READY) {
        logger.info("Session {} is ready at host {}", session.getId(), session.getHostname());
    } else if (session.getStatus() == RenderingSessionStatus.ERROR) {
        logger.error("Session {} encountered an error: {} {}", session.getId(), session.getError().getCode(), session.getError().getMessage());
    } else {
        logger.error("Session {} has unexpected status {}", session.getId(), session.getStatus());
    }
}

セッションを停止する

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

client.endSession(sessionId);

トラブルシューティング

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

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

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

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

次の手順

  • 製品のドキュメントを読む
  • ランタイム SDK について説明します。
    • .NET: /dotnet/api/microsoft.azure.remoterendering
    • C++: /cpp/api/remote-rendering/

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。 ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。 詳細については、 https://cla.microsoft.com を参照してください。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。 ボットによって提供される手順にそのまま従ってください。 この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープン ソースの倫理規定を採用しています。 詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。

インプレッション数