你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

PowerShell 脚本示例

项目
05/10/2023

Azure 远程渲染提供以下两个 REST API：

ARR 示例存储库的 Scripts 文件夹中包含了用来与服务的 REST API 进行交互的示例脚本。本文介绍这些脚本的用法。

提示

还可以使用基于 UI 的 ARRT 工具与服务进行交互，这是使用脚本的另一种简便方法。 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 存储帐户
登录到包含 Azure 远程渲染帐户的订阅：
1. 打开 PowerShell 窗口。
2. 运行 Connect-AzAccount，并按照屏幕上的指示进行操作。
注意

如果你的组织有多个订阅，你可能需要指定 SubscriptionId 和 Tenant 参数。在 Connect-AzAccount 文档中可以找到详细信息。
从 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：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 等待转换完成或出错。

通过