PowerShell 指令碼範例

發行項
05/10/2023

Azure 遠端轉譯提供下列兩個 REST API：

ARR 範例存放庫的 Scripts 資料夾中包含範例指令碼，可供與服務的 REST API 互動。本文說明其使用方式。

提示

還有一個稱為 ARRT 的 UI 型工具可與服務互動，這是使用指令碼的便利替代方案。 ARRT ARRT

警告

太過頻繁呼叫 REST API 函式，最後會導致伺服器節流並傳回失敗。在此情況下，HTTP 失敗碼識別碼為 429 (「太多要求」) 。根據經驗法則，後續的呼叫之間應該會有 5-10 秒的延遲。

Prerequisites

若要執行範例指令碼，您需要 Azure PowerShell 的功能設定。

安裝 Azure PowerShell：
1. 以管理員權限開啟 PowerShell 視窗。
2. 執行：Install-Module -Name Az -AllowClobber
如果您收到有關執行指令碼的錯誤，請確定已適當設定執行原則：
1. 以管理員權限開啟 PowerShell 視窗。
2. 執行：Set-ExecutionPolicy -ExecutionPolicy Unrestricted
準備 Azure 儲存體帳戶
登入包含 Azure 遠端轉譯帳戶的訂用帳戶：
1. 開啟 PowerShell 視窗。
2. 執行：Connect-AzAccount並遵循螢幕上的指示操作。
注意

如果您的組織有多個訂用帳戶，您可能需要指定 SubscriptionId 和 Tenant 引數。在 Connect-AzAccount documentation 中尋找詳細資料。
從 Azure 遠端轉譯 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 遠端轉譯帳戶。 arrAccountDomain應該是可用區域清單中的區域。

renderingSessionSettings

如果您想要執行 RenderingSession.ps1，就必須填妥此結構：

vmSize： 選取虛擬機器的大小。選取標準或進階。當您不再需要轉譯工作階段時，請將其關閉。
maxLeaseTime： 您要租用 VM 的持續時間。當租用到期時，VM 會關閉。稍後可以擴充租用時間， (請參閱這裡) 。
remoteRenderingDomain： 遠端轉譯 VM 所在的區域。
- 可能與 arrAccountDomain 不同，但仍應該是可用區域清單中的區域

assetConversionSettings

如果您想要執行 Conversion.ps1，就必須填妥此結構。

如需詳細資訊，請參閱準備 Azure 儲存體帳戶。

指令碼：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 最初建立的時間算起。因此，若要將工作階段租用延長一小時，請將 maxLeaseTime 增加一小時。

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

指令碼：Conversion.ps1

此指令碼用於將輸入模型轉換成 Azure 遠端轉譯的特定執行階段格式。

重要

請確定您已填寫accountSettings和assetConversionSettings區段，以及 arrconfig.json 中renderingSessionSettings中的remoteRenderingDomain選項。

此指令碼示範使用儲存體帳戶搭配服務的兩個選項：

與 Azure 遠端轉譯帳戶連結的儲存體帳戶
可透過共用存取簽章 (SAS) 存取儲存體

連結的儲存體帳戶

完整填寫 arrconfig.json 並連結儲存體帳戶之後，您可以使用下列命令。如需連結儲存體帳戶的詳細說明，請參閱建立帳戶。

使用連結的儲存體帳戶是使用轉換服務的慣用方式，因為不需要產生共用存取簽章。

.\Conversion.ps1

將中包含的 assetConversionSettings.modelLocation 所有檔案上傳至指定 inputFolderPath 下的輸入 Blob 容器。
呼叫模型轉換 REST API以開始進行模型轉換
輪詢轉換狀態，直到轉換成功或失敗為止。
輸出已轉換檔案位置的詳細資料 (儲存體帳戶、輸出容器、容器中的檔案路徑)。

透過共用存取簽章存取儲存體

.\Conversion.ps1 -UseContainerSas

這將會：

將本機檔案從 assetConversionSettings.localAssetDirectoryPath 上傳至輸入 Blob 容器。
產生輸入容器的 SAS URI。
產生輸出容器的 SAS URI。
呼叫模型轉換 REST API以開始進行模型轉換。
輪詢轉換狀態，直到轉換成功或失敗為止。
輸出已轉換檔案位置的詳細資料 (儲存體帳戶、輸出容器、容器中的檔案路徑)。
將 SAS URI 輸出至輸出 Blob 容器中已轉換的模型。

其他命令列選項

若要使用替代組態檔案：

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

若只要啟動模型轉換但不輪詢，您可使用：

.\Conversion.ps1 -ConvertAsset

您可使用下列命令列參數，覆寫組態檔中的個別設定：

Id： 搭配 GetConversionStatus 使用的 ConversionId
ArrAccountId： accountSettings 的 arrAccountId
ArrAccountKey： 覆寫 accountSettings 的 arrAccountKey
ArrAccountDomain： 覆寫 accountSettings 的 arrAccountDomain
RemoteRenderingDomain： override for remoteRenderingDomain of renderingSessionSettings
ResourceGroup： 覆寫 assetConversionSettings 的 resourceGroup
StorageAccountName： 覆寫 assetConversionSettings 的 storageAccountName
BlobInputContainerName： 覆寫 assetConversionSettings 的 blobInputContainer
LocalAssetDirectoryPath： 覆寫 assetConversionSettings 的 localAssetDirectoryPath
InputAssetPath： 覆寫 assetConversionSettings 的 inputAssetPath
：覆寫 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 儲存體的模型轉換程式， (不會執行 Upload，請勿輪詢轉換狀態) 腳本會傳回 conversionId。

.\Conversion.ps1 -ConvertAsset

而您可使用以下項目來擷取此轉換的轉換狀態：

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

使用 -Poll 以等到轉換完成或發生錯誤。

共用方式為