PowerShell スクリプトの例

[アーティクル]
05/15/2023

Azure Remote Rendering には、次の 2 つの REST API が用意されています。

ARR サンプルリポジトリには、Scripts フォルダーに、サービスの REST API を操作するためのサンプルスクリプトがあります。この記事では、その使用方法について説明します。

ヒント

また、サービスと対話するための ARRT と呼ばれる UI ベースのツールもあります。これは、スクリプトの使用に代わる便利な方法です。 ARRT

注意事項

REST API 関数を頻繁に呼び出すと、サーバーが調整され、最終的にエラーが返されます。この場合の HTTP エラーコード ID は 429 ("要求が多すぎます") です。経験則として、次の呼び出しとの間に 5 秒から 10 秒の間隔が必要です。

前提条件

サンプルスクリプトを実行するには、Azure PowerShell の機能設定が必要です。

Azure PowerShell をインストールします。
1. 管理者権限で PowerShell ウィンドウを開きます。
2. Install-Module -Name Az -AllowClobber を実行します。
スクリプトの実行に関するエラーが発生した場合は、実行ポリシーが適切に設定されていることを確認してください。
1. 管理者権限で PowerShell ウィンドウを開きます。
2. Set-ExecutionPolicy -ExecutionPolicy Unrestricted を実行します。
Azure Storage アカウントを準備します
Azure Remote Rendering アカウントを含むサブスクリプションにログインします。
1. PowerShell ウィンドウを開きます。
2. Connect-AzAccount を実行し、画面の指示に従います。
注意

組織に複数のサブスクリプションがある場合は、SubscriptionId および Tenant 引数の指定が必要になることがあります。詳細については、Connect-AzAccount のドキュメントを参照してください。
Azure Remote Rendering GitHub リポジトリから Scripts フォルダーをダウンロードします。

構成ファイル

.ps1 ファイルの次に arrconfig.json があり、これに入力する必要があります。

{
    "accountSettings": {
        "arrAccountId": "<fill in the account ID from the Azure Portal>",
        "arrAccountKey": "<fill in the account key from the Azure Portal>",
        "arrAccountDomain": "<select from available regions: australiaeast, eastus, eastus2, japaneast, northeurope, southcentralus, southeastasia, uksouth, westeurope, westus2 or specify the full url>"
    },
    "renderingSessionSettings": {
        "remoteRenderingDomain": "<select from available regions: australiaeast, eastus, eastus2, japaneast, northeurope, southcentralus, southeastasia, uksouth, westeurope, westus2 or specify the full url>",
        "vmSize": "<select standard or premium>",
        "maxLeaseTime": "<hh:mm:ss>"
    },
  "assetConversionSettings": {
    "resourceGroup": "<resource group which contains the storage account you created, only needed when uploading or generating SAS>",
    "storageAccountName": "<name of the storage account you created>",
    "blobInputContainerName": "<input container inside the storage container>",
    "blobOutputContainerName": "<output container inside the storage container>",
    "localAssetDirectoryPath": "<fill in a path to a local directory containing your asset (and files referenced from it like textures)>",
    "inputFolderPath": "<optional: base folderpath in the input container for asset upload. uses / as dir separator>",
    "inputAssetPath": "<the path to the asset under inputcontainer/inputfolderpath pointing to the input asset e.g. box.fbx>",
    "outputFolderPath": "<optional: base folderpath in the output container - the converted asset and log files will be placed here>",
    "outputAssetFileName": "<optional: filename for the converted asset, this will be placed in the output container under the outputpath>"
  }
}

注意事項

LocalAssetDirectoryPath パスのバックスラッシュは、二重のバックスラッシュ "\\" を使用して正しくエスケープするようにし、inputFolderPath や inputAssetPath などの他のすべてのパスにはスラッシュ "/" を使用するようにしてください。

注意事項

オプションの値を入力するか、キーと値をすべて削除する必要があります。たとえば、"outputAssetFileName" パラメーターを使用しない場合は、arrconfig.json 内の行全体を削除する必要があります。

accountSettings

arrAccountId と arrAccountKey については、「Azure Remote Rendering アカウントを作成する」を参照してください。 arrAccountDomain は、使用可能なリージョンの一覧のリージョンである必要があります。

renderingSessionSettings

RenderingSession.ps1 を実行する場合は、この構造を入力する必要があります。

vmSize: 仮想マシンのサイズを選択します。 Standard または Premium を選択します。不要になったレンダリングセッションをシャットダウンします。
maxLeaseTime: VM をリースする期間です。リースの有効期限が切れると、VM はシャットダウンします。リース時間は後で延長できます (こちらを参照してください)。
remoteRenderingDomain: リモートレンダリング VM が存在するリージョン。
- arrAccountDomain と異なっていてもかまいませんが、使用可能なリージョンの一覧のリージョンである必要があります

assetConversionSettings

Conversion.ps1 を実行する場合は、この構造を入力する必要があります。

詳細については、Azure Storage アカウントの準備に関する記事を参照してください。

スクリプト:RenderingSession.ps1

このスクリプトは、レンダリングセッションを作成、クエリ、および停止するために使用されます。

重要

arrconfig.json の accountSettings と renderingSessionSettings セクションを入力したことを確認してください。

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

完全に入力した arrconfig. json での標準的な使用方法:

.\RenderingSession.ps1

このスクリプトは、セッション管理 REST API を呼び出して、指定された設定でレンダリング VM を起動します。成功すると、sessionId が取得されます。その後、セッションの準備が完了するか、エラーが発生するまで、セッションのプロパティがポーリングされます。

代替の構成ファイルを使用するには、次のようにします。

.\RenderingSession.ps1 -ConfigFile D:\arr\myotherconfigFile.json

構成ファイルから個々の設定をオーバーライドすることができます。

.\RenderingSession.ps1 -ArrAccountDomain <arrAccountDomain> -RemoteRenderingDomain <remoteRenderingDomain> -VmSize <vmsize> -MaxLeaseTime <hh:mm:ss>

ポーリングせずにセッションの開始のみを行うには、以下を使用します。

.\RenderingSession.ps1 -CreateSession

スクリプトが取得する sessionId は、他のほとんどのセッションコマンドに渡す必要があります。

セッションのプロパティを取得する

セッションのプロパティを取得するには、次のように実行します。

.\RenderingSession.ps1 -GetSessionProperties -Id <sessionID> [-Poll]

-Poll を使用して、セッションの "準備が完了" するか、エラーが発生するまで待機します。

アクティブなセッションを一覧表示する

.\RenderingSession.ps1 -GetSessions

セッションを停止する

.\RenderingSession.ps1 -StopSession -Id <sessionID>

セッションのプロパティを変更する

現時点では、セッションの maxLeaseTime の変更のみがサポートされています。

注意

リース時間は、セッション VM が最初に作成された時点から常にカウントされます。そのため、セッションリースをさらに 1 時間延長するには、maxLeaseTime を 1 時間増やします。

.\RenderingSession.ps1 -UpdateSession -Id <sessionID> -MaxLeaseTime <hh:mm:ss>

スクリプト:Conversion.ps1

このスクリプトは、入力モデルを Azure Remote Rendering 固有のランタイム形式に変換するために使用されます。

重要

arrconfig.json で、accountSettings セクション、assetConversionSettings セクション、renderingSessionSettings の remoteRenderingDomain オプションを入力していることを確認します。

このスクリプトは、サービスでストレージアカウントを使用する 2 つのオプションを示しています。

Azure Remote Rendering アカウントにリンクされているストレージアカウント
Shared Access Signature (SAS) 経由のストレージへのアクセスを提供する

リンクされたストレージアカウント

arrconfig.json を完全に入力し、ストレージアカウントをリンクすると、次のコマンドを使用できます。ストレージアカウントのリンクについては、「アカウントの作成」に記載されています。

Shared Access Signature を生成する必要がないため、変換サービスの使用には、リンクされたストレージアカウントを使用することをお勧めします。

.\Conversion.ps1

assetConversionSettings.modelLocation に格納されているすべてのファイルを、指定した inputFolderPath の下の入力 BLOB コンテナーにアップロードします。
モデルの変換 REST API を呼び出して、モデルの変換を開始します
変換が成功または失敗するまで変換ステータスをポーリングします。
変換されたファイルの場所の詳細 (ストレージアカウント、出力コンテナー、コンテナー内のファイルパス) を出力します。

Shared Access Signature 経由のストレージへのアクセス

.\Conversion.ps1 -UseContainerSas

リセットすると、以下のようになります。

assetConversionSettings.localAssetDirectoryPath から入力 BLOB コンテナーにローカルファイルをアップロードします。
入力コンテナーの SAS URI を生成します。
出力コンテナーの SAS URI を生成します。
モデルの変換 REST API を呼び出して、モデルの変換を開始します。
変換が成功または失敗するまで変換ステータスをポーリングします。
変換されたファイルの場所の詳細 (ストレージアカウント、出力コンテナー、コンテナー内のファイルパス) を出力します。
出力 BLOB コンテナー内の変換されたモデルの SAS URI を出力します。

追加のコマンドラインオプション

代替の構成ファイルを使用するには、次のようにします。

.\Conversion.ps1 -ConfigFile D:\arr\myotherconfigFile.json

ポーリングせずにモデルの変換の開始のみを行うには、以下を使用できます。

.\Conversion.ps1 -ConvertAsset

次のコマンドラインスイッチを使用して、構成ファイルから個々の設定をオーバーライドすることができます。

Id: GetConversionStatus で使用される ConversionId
ArrAccountId: accountSettings の arrAccountId
ArrAccountKey: accountSettings の arrAccountKey のオーバーライド
ArrAccountDomain: accountSettings の arrAccountDomain のオーバーライド
RemoteRenderingDomain: renderingSessionSettings の remoteRenderingDomain のオーバーライド
ResourceGroup: assetConversionSettings の resourceGroup のオーバーライド
StorageAccountName: assetConversionSettings の storageAccountName のオーバーライド
BlobInputContainerName: assetConversionSettings の blobInputContainer のオーバーライド
LocalAssetDirectoryPath: assetConversionSettings のlocalAssetDirectoryPath のオーバーライド
InputAssetPath: assetConversionSettings の inputAssetPath のオーバーライド
BlobOutputContainerName: assetConversionSettings の BlobOutputContainerName のオーバーライド
OutputFolderPath: assetConversionSettings の outputFolderPath のオーバーライド
OutputAssetFileName: assetConversionSettings の outputAssetFileName のオーバーライド

たとえば、次のように指定のオプションを組み合わせることができます。

.\Conversion.ps1 -LocalAssetDirectoryPath "C:\\models\\box" -InputAssetPath box.fbx -OutputFolderPath another/converted/box -OutputAssetFileName newConversionBox.arrAsset

個々の変換ステージを実行する

プロセスの個々のステップを実行する場合は、以下を使用できます。

指定された LocalAssetDirectoryPath からのデータのアップロードのみ行います。

.\Conversion.ps1 -Upload

BLOB ストレージに既にアップロードされているモデルの変換プロセスの開始のみを行います (アップロードは実行せず、変換の状態はポーリングしません)。このスクリプトは、conversionId を返します。

.\Conversion.ps1 -ConvertAsset

また、以下を使用して、この変換の変換状態を取得できます。

.\Conversion.ps1 -GetConversionStatus -Id <conversionId> [-Poll]

-Poll を使用して、変換が完了するか、エラーが発生するまで待機します。

次の方法で共有

PowerShell スクリプトの例

前提条件

構成ファイル

accountSettings

renderingSessionSettings

assetConversionSettings

スクリプト:RenderingSession.ps1

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

セッションのプロパティを取得する

アクティブなセッションを一覧表示する

セッションを停止する

セッションのプロパティを変更する

スクリプト:Conversion.ps1

リンクされたストレージアカウント

Shared Access Signature 経由のストレージへのアクセス

追加のコマンドラインオプション

個々の変換ステージを実行する

次のステップ

フィードバック

その他のリソース

次の方法で共有

PowerShell スクリプトの例

前提条件

構成ファイル

accountSettings

renderingSessionSettings

assetConversionSettings

スクリプト:RenderingSession.ps1

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

セッションのプロパティを取得する

アクティブなセッションを一覧表示する

セッションを停止する

セッションのプロパティを変更する

スクリプト:Conversion.ps1

リンクされたストレージ アカウント

Shared Access Signature 経由のストレージへのアクセス

追加のコマンド ライン オプション

個々の変換ステージを実行する

次のステップ

フィードバック

その他のリソース

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

リンクされたストレージアカウント

追加のコマンドラインオプション