.NET 用 Azure Remote Rendering クライアント ライブラリ - バージョン 1.1.0

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

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

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

製品ドキュメント

作業の開始

パッケージをインストールする

次のいずれかの方法を使用して、.NET 用の Azure Mixed Reality ARR クライアント ライブラリをインストールします。

Visual Studio パッケージ マネージャーから:

Install-Package Azure.MixedReality.RemoteRendering

.NET CLI から

dotnet add package Azure.MixedReality.RemoteRendering

パッケージ参照を追加します。

<PackageReference Include="Azure.MixedReality.RemoteRendering" Version="1.0.0" />

前提条件

このパッケージを使用するには、Azure サブスクリプションと 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 にアクセスするための資格情報をクライアント アプリケーションに埋め込むことを回避できるため、運用アプリケーションではこの方法をお勧めします。

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

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

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

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

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

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

AzureKeyCredential accountKeyCredential = new AzureKeyCredential(accountKey);

RemoteRenderingClient client = new RemoteRenderingClient(remoteRenderingEndpoint, accountId, accountDomain, accountKeyCredential);

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

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

TokenCredential credential = new ClientSecretCredential(tenantId, clientId, clientSecret, new TokenCredentialOptions
{
    AuthorityHost = new Uri($"https://login.microsoftonline.com/{tenantId}")
});

RemoteRenderingClient client = new RemoteRenderingClient(remoteRenderingEndpoint, accountId, accountDomain, credential);

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

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

Task deviceCodeCallback(DeviceCodeInfo deviceCodeInfo, CancellationToken cancellationToken)
{
    Debug.WriteLine(deviceCodeInfo.Message);
    Console.WriteLine(deviceCodeInfo.Message);
    return Task.FromResult(0);
}

TokenCredential credential = new DeviceCodeCredential(deviceCodeCallback, tenantId, clientId, new TokenCredentialOptions
{
    AuthorityHost = new Uri($"https://login.microsoftonline.com/{tenantId}"),
});

RemoteRenderingClient client = new RemoteRenderingClient(remoteRenderingEndpoint, accountId, accountDomain, credential);

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

DefaultAzureCredential を使用した対話型認証

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

TokenCredential credential = new DefaultAzureCredential(includeInteractiveCredentials: true);

RemoteRenderingClient client = new RemoteRenderingClient(remoteRenderingEndpoint, accountId, accountDomain, credential);

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

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

// 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 RemoteRenderingClient(remoteRenderingEndpoint, accountId, accountDomain, accessToken);

主要な概念

RemoteRenderingClient

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

例

• 単純な資産を変換する
• より複雑な資産を変換する
• 資産変換が完了したときに出力を取得する
• 変換を一覧表示する
• セッションを作成する
• セッションのリース時間を延長する
• セッションを一覧表示する
• セッションを停止する

単純な資産を変換する

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

    AssetConversionInputOptions inputOptions = new AssetConversionInputOptions(storageUri, "box.fbx");
    AssetConversionOutputOptions outputOptions = new AssetConversionOutputOptions(storageUri);
    AssetConversionOptions conversionOptions = new AssetConversionOptions(inputOptions, outputOptions);

    // A randomly generated GUID is a good choice for a conversionId.
    string conversionId = Guid.NewGuid().ToString();

    AssetConversionOperation conversionOperation = client.StartConversion(conversionId, conversionOptions);

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

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

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

    AssetConversionInputOptions input = new AssetConversionInputOptions(inputStorageUri, "bicycle.gltf")
    {
        BlobPrefix = "Bicycle"
    };
    AssetConversionOutputOptions output = new AssetConversionOutputOptions(outputStorageUri)
    {
        BlobPrefix = "ConvertedBicycle"
    };
    AssetConversionOptions conversionOptions = new AssetConversionOptions(inputOptions, outputOptions);

    string conversionId = Guid.NewGuid().ToString();

    AssetConversionOperation conversionOperation = client.StartConversion(conversionId, conversionOptions);

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

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

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

    AssetConversion conversion = conversionOperation.WaitForCompletionAsync().Result;
    if (conversion.Status == AssetConversionStatus.Succeeded)
    {
        Console.WriteLine($"Conversion succeeded: Output written to {conversion.Output.OutputAssetUri}");
    }
    else if (conversion.Status == AssetConversionStatus.Failed)
    {
        Console.WriteLine($"Conversion failed: {conversion.Error.Code} {conversion.Error.Message}");
    }

変換を一覧表示する

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

    foreach (var conversion in client.GetConversions())
    {
        if ((conversion.Status == AssetConversionStatus.Succeeded) && (conversion.CreatedOn > DateTimeOffset.Now.AddDays(-1)))
        {
            Console.WriteLine($"output asset URI: {conversion.Output.OutputAssetUri}");
        }
    }

セッションを作成する

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

    RenderingSessionOptions options = new RenderingSessionOptions(TimeSpan.FromMinutes(30), RenderingServerSize.Standard);

    // A randomly generated GUID is a good choice for a sessionId.
    string sessionId = Guid.NewGuid().ToString();

    StartRenderingSessionOperation startSessionOperation = client.StartSession(sessionId, options);

    RenderingSession newSession = startSessionOperation.WaitForCompletionAsync().Result;
    if (newSession.Status == RenderingSessionStatus.Ready)
    {
        Console.WriteLine($"Session {sessionId} is ready.");
    }
    else if (newSession.Status == RenderingSessionStatus.Error)
    {
        Console.WriteLine($"Session {sessionId} encountered an error: {newSession.Error.Code} {newSession.Error.Message}");
    }

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

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

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

    RenderingSession currentSession = client.GetSession(sessionId);

    if (currentSession.MaxLeaseTime - DateTimeOffset.Now.Subtract(currentSession.CreatedOn.Value) < TimeSpan.FromMinutes(2))
    {
        TimeSpan newLeaseTime = currentSession.MaxLeaseTime.Value.Add(TimeSpan.FromMinutes(30));

        UpdateSessionOptions longerLeaseSettings = new UpdateSessionOptions(newLeaseTime);

        client.UpdateSession(sessionId, longerLeaseSettings);
    }

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

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

    foreach (var properties in client.GetSessions())
    {
        if (properties.Status == RenderingSessionStatus.Starting)
        {
            Console.WriteLine($"Session \"{properties.SessionId}\" is starting.");
        }
        else if (properties.Status == RenderingSessionStatus.Ready)
        {
            Console.WriteLine($"Session \"{properties.SessionId}\" is ready at host {properties.Host}");
        }
    }

セッションを停止する

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

    client.StopSession(sessionId);

トラブルシューティング

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

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

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

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

次のステップ

• 製品のドキュメントを読む
• ランタイム SDK について説明します。
  • .NET: https://docs.microsoft.com/dotnet/api/microsoft.azure.remoterendering
  • C++: https://docs.microsoft.com/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 宛てに質問またはコメントをお送りください。