共用方式為


PowerShell 指令碼範例

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

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

提示

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

警告

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

Prerequisites

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

  1. 安裝 Azure PowerShell:

    1. 以管理員權限開啟 PowerShell 視窗。
    2. 執行:Install-Module -Name Az -AllowClobber
  2. 如果您收到有關執行指令碼的錯誤,請確定已適當設定執行原則

    1. 以管理員權限開啟 PowerShell 視窗。
    2. 執行:Set-ExecutionPolicy -ExecutionPolicy Unrestricted
  3. 準備 Azure 儲存體帳戶

  4. 登入包含 Azure 遠端轉譯 帳戶的訂用帳戶:

    1. 開啟 PowerShell 視窗。
    2. 執行:Connect-AzAccount並遵循螢幕上的指示操作。

    注意

    如果您的組織有多個訂用帳戶,您可能需要指定 SubscriptionId 和 Tenant 引數。 在 Connect-AzAccount documentation 中尋找詳細資料。

  5. 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

對於 arrAccountIdarrAccountKey,請參閱建立 Azure 遠端轉譯帳戶arrAccountDomain應該是可用區域清單中的區域

renderingSessionSettings

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

  • vmSize: 選取虛擬機器的大小。 選取標準進階。 當您不再需要轉譯工作階段時,請將其關閉。
  • maxLeaseTime: 您要租用 VM 的持續時間。 當租用到期時,VM 會關閉。 稍後可以擴充租用時間, (請參閱這裡) 。
  • remoteRenderingDomain: 遠端轉譯 VM 所在的區域。

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 遠端轉譯的特定執行階段格式。

重要

請確定您已填寫accountSettingsassetConversionSettings區段,以及 arrconfig.json 中renderingSessionSettings中的remoteRenderingDomain選項。

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

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

連結的儲存體帳戶

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

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

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

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

.\Conversion.ps1 -UseContainerSas

這將會:

  1. 將本機檔案從 assetConversionSettings.localAssetDirectoryPath 上傳至輸入 Blob 容器。
  2. 產生輸入容器的 SAS URI。
  3. 產生輸出容器的 SAS URI。
  4. 呼叫模型轉換 REST API以開始進行模型轉換
  5. 輪詢轉換狀態,直到轉換成功或失敗為止。
  6. 輸出已轉換檔案位置的詳細資料 (儲存體帳戶、輸出容器、容器中的檔案路徑)。
  7. 將 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 以等到轉換完成或發生錯誤。

後續步驟