Edit

Example PowerShell scripts

  • Article

Azure Remote Rendering provides the following two REST APIs:

The ARR samples repository contains sample scripts in the Scripts folder for interacting with the REST APIs of the service. This article describes their usage.

Tip

There is also a UI-based tool called ARRT to interact with the service, which is a convenient alternative to using scripts. ARRT

Caution

Calling REST API functions too frequently will cause the server to throttle and return failure eventually. The HTTP failure code id in this case is 429 ("too many requests"). As a rule of thumb, there should be a delay of 5-10 seconds between subsequent calls.

Prerequisites

To execute the sample scripts, you need a functional setup of Azure PowerShell.

  1. Install Azure PowerShell:

    1. Open a PowerShell window with admin rights.
    2. Run: Install-Module -Name Az -AllowClobber

  2. If you get errors about running scripts, ensure your execution policy is set appropriately:

    1. Open a PowerShell window with admin rights.
    2. Run: Set-ExecutionPolicy -ExecutionPolicy Unrestricted

  3. Prepare an Azure Storage account

  4. Log in to your subscription containing your Azure Remote Rendering account:

    1. Open a PowerShell window.
    2. Run: Connect-AzAccount and follow the on-screen directions.

    Note

    In case your organization has more than one subscription you might need to specify the SubscriptionId and Tenant arguments. Find details in the Connect-AzAccount documentation.

  5. Download the Scripts folder from the Azure Remote Rendering GitHub repository.

Configuration file

Next to the .ps1 files there's an arrconfig.json that you need to fill out:

{
    "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>"
  }
}

Caution

Make sure to properly escape backslashes in the LocalAssetDirectoryPath path by using double backslashes: "\\" and use forward slashes "/" in all other paths like inputFolderPath and inputAssetPath.

Caution

Optional values need to be filled out or you need to remove the key and value altogether. For example, if you do not use the "outputAssetFileName" parameter, you need to delete the whole line inside arrconfig.json.

accountSettings

For arrAccountId and arrAccountKey, see Create an Azure Remote Rendering account. The arrAccountDomain should be a region from list of available regions.

renderingSessionSettings

This structure must be filled out if you want to run RenderingSession.ps1:

  • vmSize: Selects the size of the virtual machine. Select standard or premium. Shut down rendering sessions when you don't need them anymore.
  • maxLeaseTime: The duration for which you want to lease the VM. The VM shuts down when the lease expires. The lease time can be extended later (see here).
  • remoteRenderingDomain: The region where the remote rendering VM resides in.

assetConversionSettings

This structure must be filled out if you want to run Conversion.ps1.

For details, see Prepare an Azure Storage account.

Script: RenderingSession.ps1

This script is used to create, query, and stop rendering sessions.

Important

Make sure you have filled out the accountSettings and renderingSessionSettings sections in arrconfig.json.

Create a rendering session

Normal usage with a fully filled out arrconfig.json:

.\RenderingSession.ps1

The script calls the session management REST API to spin up a rendering VM with the specified settings. On success, it retrieves the sessionId. Afterwards it polls the session properties until the session is ready or an error occurred.

To use an alternative config file:

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

You can override individual settings from the config file:

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

To only start a session without polling, you can use:

.\RenderingSession.ps1 -CreateSession

The sessionId that the script retrieves must be passed to most other session commands.

Retrieve session properties

To get a session's properties, run:

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

Use -Poll to wait until the session is ready or an error occurred.

List active sessions

.\RenderingSession.ps1 -GetSessions

Stop a session

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

Change session properties

At the moment, we only support changing the maxLeaseTime of a session.

Note

The lease time is always counted from the time when the session VM was initially created. So to extend the session lease by another hour, increase maxLeaseTime by one hour.

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

Script: Conversion.ps1

This script is used to convert input models into the Azure Remote Rendering specific runtime format.

Important

Make sure you have filled out the accountSettings and assetConversionSettings sections, and the remoteRenderingDomain option in the renderingSessionSettings in arrconfig.json.

The script demonstrates the two options to use storage accounts with the service:

  • Storage account linked with Azure Remote Rendering Account
  • Providing access to storage via Shared Access Signatures (SAS)

Linked storage account

Once you have fully filled out arrconfig.json and linked a storage account, you can use the following command. Linking your storage account is described at Create an Account.

Using a linked storage account is the preferred way to use the conversion service since there's no need to generate Shared Access Signatures.

.\Conversion.ps1
  1. Upload all files contained in the assetConversionSettings.modelLocation to the input blob container under the given inputFolderPath.
  2. Call the model conversion REST API to kick off the model conversion
  3. Poll the conversion status until the conversion succeeded or failed.
  4. Output details of the converted file location (storage account, output container, file path in the container).

Access to storage via Shared Access Signatures

.\Conversion.ps1 -UseContainerSas

This will:

  1. Upload the local file from the assetConversionSettings.localAssetDirectoryPath to the input blob container.
  2. Generate a SAS URI for the input container.
  3. Generate a SAS URI for the output container.
  4. Call the model conversion REST API to kick off the model conversion.
  5. Poll the conversion status until the conversion succeeded or failed.
  6. Output details of the converted file location (storage account, output container, file path in the container).
  7. Output a SAS URI to the converted model in the output blob container.

Additional command-line options

To use an alternative config file:

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

To only start model conversion without polling, you can use:

.\Conversion.ps1 -ConvertAsset

You can override individual settings from the config file using the following command-line switches:

  • Id: ConversionId used with GetConversionStatus
  • ArrAccountId: arrAccountId of accountSettings
  • ArrAccountKey: override for arrAccountKey of accountSettings
  • ArrAccountDomain: override for arrAccountDomain of accountSettings
  • RemoteRenderingDomain: override for remoteRenderingDomain of renderingSessionSettings
  • ResourceGroup: override for resourceGroup of assetConversionSettings
  • StorageAccountName: override for storageAccountName of assetConversionSettings
  • BlobInputContainerName: override for blobInputContainer of assetConversionSettings
  • LocalAssetDirectoryPath: override for localAssetDirectoryPath of assetConversionSettings
  • InputAssetPath: override for inputAssetPath of assetConversionSettings
  • BlobOutputContainerName: override for blobOutputContainerName of assetConversionSettings
  • OutputFolderPath: override for the outputFolderPath of assetConversionSettings
  • OutputAssetFileName: override for outputAssetFileName of assetConversionSettings

For example you can combine the given options like this:

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

Run the individual conversion stages

If you want to run individual steps of the process, you can use:

Only upload data from the given LocalAssetDirectoryPath.

.\Conversion.ps1 -Upload

Only start the conversion process of a model already uploaded to blob storage (don't run Upload, don't poll the conversion status) The script returns a conversionId.

.\Conversion.ps1 -ConvertAsset

And you can retrieve the conversion status of this conversion using:

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

Use -Poll to wait until conversion is done or an error occurred.

Next steps