次の方法で共有

  • [アーティクル]

ビルドの状態

Python 用 Azure Remote Rendering クライアント ライブラリ - バージョン 1.0.0b2

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

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

この SDK では、Remote Rendering REST API のバージョン "2021-01-01" がサポートされています。

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

製品ドキュメント

免責事項

Python 2.7 の Azure SDK Python パッケージのサポートは、2022 年 1 月 1 日に終了しました。 詳細と質問については、https://github.com/Azure/azure-sdk-for-python/issues/20691 を参照してください

作業の開始

前提条件

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

このチュートリアルに従うには、 ストレージ アカウントを ARR アカウントにリンクすることを強くお勧めします。

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

pip を使用して Python 用 Azure Remote Rendering クライアント ライブラリをインストールします。

pip install --pre azure-mixedreality-remoterendering

クライアントを作成して認証する

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

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

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

サポートされているリージョン内のエンドポイントの完全な一覧については、Azure Remote Rendering リージョンの一覧を参照してください。

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

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

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

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

from azure.core.credentials import AzureKeyCredential
from azure.mixedreality.remoterendering import RemoteRenderingClient

account_id = "<ACCOUNT_ID>"
account_domain = "<ACCOUNT_DOMAIN>"
account_key = "<ACCOUNT_KEY>"
arr_endpoint = "<ARR_ENDPOINT>"

key_credential = AzureKeyCredential(account_key)
client = RemoteRenderingClient(
    endpoint=arr_endpoint,
    account_id=account_id,
    account_domain=account_domain,
    credential=key_credential
)

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

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

from azure.mixedreality.authentication import MixedRealityStsClient
from azure.mixedreality.remoterendering import RemoteRenderingClient
account_id = "<ACCOUNT_ID>"
account_domain = "<ACCOUNT_DOMAIN>"
account_key = "<ACCOUNT_KEY>"

key_credential = AzureKeyCredential(account_key)

client = MixedRealityStsClient(account_id, account_domain, key_credential)

token = client.get_token()

client = RemoteRenderingClient(
    endpoint=arr_endpoint,
    account_id=account_id,
    account_domain=account_domain,
    credential=token,
)

Azure Active Directory 資格情報を使用した認証

アカウント キー認証はほとんどの例で使用されますが、Azure Id ライブラリを使用して Azure Active Directory で認証することもできます。 これは、運用アプリケーションに推奨される方法です。 次に示す [DefaultAzureCredential][defaultazurecredential] プロバイダー、または Azure SDK で提供されているその他の資格情報プロバイダーを使用するには、パッケージを @azure/identity インストールしてください。

また、[新しい AAD アプリケーションの登録][register_aad_app] を行い、Mixed Reality サービスの適切なロールをサービス プリンシパルに割り当てることで、Mixed Reality リソースへのアクセス権を付与する必要があります。

from azure.identity import DefaultAzureCredential
from azure.mixedreality.remoterendering import RemoteRenderingClient

account_id = "<ACCOUNT_ID>"
account_domain = "<ACCOUNT_DOMAIN>"
default_credential = DefaultAzureCredential()

client = RemoteRenderingClient(
    endpoint=arr_endpoint,
    account_id=account_id,
    account_domain=account_domain,
    credential=default_credential
)

主要な概念

RemoteRenderingClient

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

Long-Running操作

実行時間の長い操作は、操作を開始するためにサービスに送信された最初の要求で構成される操作です。その後、間隔を指定してサービスをポーリングし、操作が完了したか失敗したか、成功したかどうかを判断して結果を取得します。

アセットを変換したり、レンダリング セッションをスピンアップしたりするメソッドは、実行時間の長い操作としてモデル化されます。 クライアントは、 begin_<method-name> LROPoller または AsyncLROPoller を返すメソッドを公開します。 呼び出し元は、 メソッドから返された poller オブジェクトに対して result() を呼び出して、操作が完了するまで待機する begin_<method-name> 必要があります。 実行時間の長い操作の使用例を示すために、サンプル コード スニペット 用意されています。

例

資産を変換する

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

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

変換プロセスが完了すると、出力は"/output/conversion_id>/<box.arrAsset" のパスの下にある指定された出力コンテナーに書き込まれます。 パスは、変換が成功したoutput.asset_uriから取得できます。

    conversion_id = str(uuid.uuid4()) # A randomly generated uuid is a good choice for a conversion_id.

    input_settings = AssetConversionInputSettings(
        storage_container_uri="<STORAGE CONTAINER URI>",
        relative_input_asset_path="box.fbx",
        blob_prefix="input/box"
    )
    output_settings = AssetConversionOutputSettings(
        storage_container_uri="<STORAGE CONTAINER URI>",
        blob_prefix="output/"+conversion_id,
        output_asset_filename="convertedBox.arrAsset" #if no output_asset_filename <input asset filename>.arrAsset will be the name of the resulting converted asset
    )
    try:
        conversion_poller = client.begin_asset_conversion(
            conversion_id=conversion_id,
            input_settings=input_settings,
            output_settings=output_settings
        )

        print("Conversion with id:", conversion_id, "created. Waiting for completion.")
        conversion = conversion_poller.result()
        print("conversion output:", conversion.output.asset_uri)

    except Exception as e:
        print("Conversion failed", e)

リスト変換

変換に関する情報は、 メソッドを list_asset_conversions 使用して取得できます。 このメソッドは、まだ開始していない変換、実行中の変換、完了した変換を返す場合があります。 この例では、すべてのコンバージョンと印刷 ID と作成広告、および成功したコンバージョンの出力アセット URI を一覧表示します。

    print("conversions:")
    for c in client.list_asset_conversions():
        print(
            "\t conversion:  id:",
            c.id,
            "status:",
            c.status,
            "created on:",
            c.created_on.strftime("%m/%d/%Y, %H:%M:%S"),
        )
        if c.status == AssetConversionStatus.SUCCEEDED:
            print("\t\tconversion result URI:", c.output.asset_uri)

セッションを作成する

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

    print("starting rendering session with id:", session_id)
    try:
        session_poller = client.begin_rendering_session(
            session_id=session_id, size=RenderingSessionSize.STANDARD, lease_time_minutes=20
        )
        print(
            "rendering session with id:",
            session_id,
            "created. Waiting for session to be ready.",
        )
        session = session_poller.result()
        print(
            "session with id:",
            session.id,
            "is ready. lease_time_minutes:",
            session.lease_time_minutes,
        )
    except Exception as e:
        print("Session startup failed", e)

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

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

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

    session = client.get_rendering_session(session_id)
    if session.lease_time_minutes - session.elapsed_time_minutes < 2:
        session = client.update_rendering_session(
            session_id=session_id, lease_time_minutes=session.lease_time_minutes + 10
        )

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

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

    print("sessions:")
    rendering_sessions = client.list_rendering_sessions()
    for session in rendering_sessions:
        print(
            "\t session:  id:",
            session.id,
            "status:",
            session.status,
            "created on:",
            session.created_on.strftime("%m/%d/%Y, %H:%M:%S"),
        )

セッションを停止する

次のコードは、指定された ID を持つ実行中のセッションを停止します。実行中のセッションでは継続的なコストが発生するため、不要になったセッションを停止することをお勧めします。

    client.stop_rendering_session(session_id)
    print("session with id:", session_id, "stopped")

トラブルシューティング

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

クライアント メソッドとポーリング結果を待機すると、要求が失敗した場合に例外がスローされます。

変換内の資産が無効な場合、変換ポーリングツールは、詳細を含むエラーを含む例外をスローします。 変換サービスがファイルを処理できるようになると <、assetName.result.json> ファイルが出力コンテナーに書き込まれます。 入力資産が無効な場合、そのファイルには問題の詳細な説明が含まれます。

同様に、セッションが要求されると、セッションがエラー状態になることがあります。 この場合、投票者はエラーの詳細を含む例外をスローします。 通常、セッション エラーは一時的なものであり、新しいセッションの要求は成功するはずです。

ログ記録

このライブラリでは、標準の [ログ記録][python_logging] ライブラリを使用してログを記録します。

HTTP セッション (URL、ヘッダーなど) に関する基本情報は、レベルで INFO ログに記録されます。

要求/応答本文や未作成のヘッダーなど、詳細なDEBUGレベルのログ記録は、クライアントで有効にすることも、キーワード (keyword)引数を使用してlogging_enable操作ごとに有効にすることもできます。

SDK のログ記録に関する完全なドキュメントと例 については、こちらを参照してください。

オプションの構成

省略可能なキーワード (keyword)引数は、クライアントレベルと操作ごとのレベルで渡すことができます。 azure-core リファレンス ドキュメント では、再試行、ログ記録、トランスポート プロトコルなどの使用可能な構成について説明しています。

例外

Remote Rendering クライアント ライブラリでは、Azure Core で定義されている例外が発生します。

非同期 API

このライブラリには、Python 3.7 以降でサポートされている完全な非同期 API も含まれています。 これを使用するには、まず、 aiohttp などの非同期トランスポートをインストールする必要があります。 非同期クライアントは 名前空間の下にあります azure.mixedreality.remoterendering.aio 。

次の手順

  • 製品のドキュメントを読む
  • ランタイム 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 宛てに質問またはコメントをお送りください。

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

インプレッション数