Script di Azure PowerShell di esempio

Rendering remoto di Azure include le due API REST seguenti:

• API REST di conversione
• API REST di sessione

Il repository di esempi di Rendering remoto di Azure contiene script di esempio nella cartella Scripts per interagire con le API REST del servizio. Questo articolo ne descrive l'utilizzo.

Suggerimento

Per interagire con il servizio, è anche disponibile uno strumento dell'interfaccia utente denominato ARRT, che rappresenta un'alternativa pratica all'uso degli script.

Attenzione

La chiamata di funzioni API REST troppo frequente causerà la limitazione del server e la restituzione di un errore. L'ID del codice di errore HTTP in questo caso è 429 ("troppe richieste"). Come regola generale, è necessario un ritardo di 5-10 secondi tra chiamate successive.

Prerequisiti

Per eseguire gli script di esempio, è necessario procedere a un'installazione funzionale di Azure PowerShell.

1. Installare Azure PowerShell:

   1. Aprire una finestra di PowerShell con diritti di amministratore.
   2. Eseguire: Install-Module -Name Az -AllowClobber

2. Se si ricevono errori relativi all'esecuzione di script, assicurarsi che i criteri di esecuzione siano impostati nel modo appropriato:

   1. Aprire una finestra di PowerShell con diritti di amministratore.
   2. Eseguire: Set-ExecutionPolicy -ExecutionPolicy Unrestricted

3. Preparare un account di archiviazione di Azure

4. Accedere alla sottoscrizione contenente l'account azure Rendering remoto:

   1. Aprire una finestra di PowerShell.
   2. Eseguire Connect-AzAccount e seguire le istruzioni visualizzate.

   Nota

   Se l'organizzazione ha più di una sottoscrizione, può essere necessario specificare gli argomenti SubscriptionId e Tenant. Per i dettagli, vedere la documentazione di Connect-AzAccount.

5. Scaricare la cartella Scripts dal repository GitHub di Rendering remoto di Azure.

File di configurazione

Oltre ai file .ps1, è presente un file arrconfig.json che è necessario compilare:

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

Attenzione

Assicurarsi di eseguire correttamente l'escape delle barre rovesciata nel percorso LocalAssetDirectoryPath usando doppie barre rovesciata: "\\" e usare le barre "/" in tutti gli altri percorsi, ad esempio inputFolderPath e inputAssetPath.

Attenzione

È necessario specificare i valori facoltativi oppure rimuovere del tutto la chiave e il valore. Ad esempio, se non si usa il "outputAssetFileName" parametro , è necessario eliminare l'intera riga all'interno di arrconfig.json.

accountSettings

Per arrAccountId e arrAccountKey, vedere Creare un account di Rendering remoto di Azure. arrAccountDomain Deve essere un'area dall'elenco delle aree disponibili.

renderingSessionSettings

Questa struttura deve essere completata se si vuole eseguire RenderingSession.ps1:

• vmSize: selezionare le dimensioni della macchina virtuale, Standard o Premium. Arrestare le sessioni di rendering quando non sono più necessarie.
• maxLeaseTime: la durata desiderata del lease della VM. La macchina virtuale viene arrestata alla scadenza del lease. Il tempo di lease può essere esteso in un secondo momento (vedere qui).
• remoteRenderingDomain: Area in cui si trova la macchina virtuale per il rendering remoto.
  • Può essere diverso da arrAccountDomain, ma deve comunque essere un'area dall'elenco delle aree disponibili

assetConversionSettings

Questa struttura deve essere completata se si vuole eseguire Conversion.ps1.

Per i dettagli, vedere Preparare un account di archiviazione di Azure.

Script: RenderingSession. ps1

Questo script consente di creare, sottoporre a query e arrestare le sessioni di rendering.

Importante

Assicurarsi di aver completato le sezioni accountSettings e renderingSessionSettings del file arrconfig.json.

Creare una sessione di rendering

Utilizzo normale con un file arrconfig.json completamente compilato:

.\RenderingSession.ps1

Lo script chiama l'API REST di gestione della sessione per avviare una macchina virtuale di rendering con le impostazioni specificate. In caso di esito positivo, recupera l'id sessione. Successivamente esegue il polling delle proprietà della sessione fino a quando la sessione non è pronta o si è verificato un errore.

Per usare un file di configurazione alternativo:

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

È possibile eseguire l'override di singole impostazioni del file di configurazione:

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

Per limitarsi ad avviare una sessione senza polling, è possibile usare:

.\RenderingSession.ps1 -CreateSession

Il valore di sessionId recuperato dallo script deve essere passato alla maggior parte degli altri comandi della sessione.

Recuperare le proprietà della sessione

Per ottenere le proprietà di una sessione, eseguire:

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

Usare -Poll per restare in attesa fino a quando la sessione non è pronta o si verifica un errore.

Elencare le sessioni attive

.\RenderingSession.ps1 -GetSessions

Arrestare una sessione

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

Cambiare le proprietà della sessione

Al momento, è supportata solo la modifica del valore maxLeaseTime di una sessione.

Nota

La durata del lease viene sempre conteggiata dal momento in cui viene inizialmente creata la VM della sessione. Quindi, per estendere il lease della sessione di un'altra ora, aumentare il valore di maxLeaseTime di un'ora.

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

Script: Conversion.ps1

Questo script consente di convertire i modelli di input nel formato di runtime specifico di Rendering remoto di Azure.

Importante

Assicurarsi di aver compilato le sezioni accountSettings e assetConversionSettings e l'opzione remoteRenderingDomain in renderingSessionSettings in arrconfig.json.

Lo script illustra le due opzioni disponibili per usare gli account di archiviazione con il servizio:

• Account di archiviazione collegato all'account di Rendering remoto di Azure
• Accesso all'archiviazione tramite firme di accesso condiviso

Account di archiviazione collegato

Dopo aver compilato completamente arrconfig.json e collegato un account di archiviazione, è possibile usare il comando seguente. Il collegamento dell'account di archiviazione viene descritto in Creare un account.

L'uso di un account di archiviazione collegato è il modo consigliato per usare il servizio di conversione, perché non è necessario generare firme di accesso condiviso.

.\Conversion.ps1

1. Caricare tutti i file contenuti in nel assetConversionSettings.modelLocation contenitore BLOB di input nell'oggetto specificato inputFolderPath.
2. Viene chiamata l'API REST di conversione di modelli per avviare la conversione del modello
3. Viene eseguito il polling dello stato della conversione finché l'operazione non riesce o si verifica un errore.
4. Vengono restituiti i dettagli della posizione del file convertito (account di archiviazione, contenitore di output, percorso del file nel contenitore).

Accedere all'archiviazione tramite firme di accesso condiviso

.\Conversion.ps1 -UseContainerSas

In tal modo, si verificheranno i seguenti eventi:

1. Il file locale viene caricato da assetConversionSettings.localAssetDirectoryPath al contenitore BLOB di input.
2. Viene generato un URI di firma di accesso condiviso per il contenitore di input.
3. Viene generato un URI di firma di accesso condiviso per il contenitore di output.
4. Viene chiamata l'API REST di conversione di modelli per avviare la conversione del modello.
5. Viene eseguito il polling dello stato della conversione finché l'operazione non riesce o si verifica un errore.
6. Vengono restituiti i dettagli della posizione del file convertito (account di archiviazione, contenitore di output, percorso del file nel contenitore).
7. Viene restituito un URI di firma di accesso condiviso del modello convertito nel contenitore BLOB di output.

Altre opzioni della riga di comando

Per usare un file di configurazione alternativo:

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

Per limitarsi ad avviare la conversione del modello senza polling, è possibile usare:

.\Conversion.ps1 -ConvertAsset

È possibile eseguire l'override delle singole impostazioni del file di configurazione usando le opzioni della riga di comando seguenti:

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

Ad esempio, è possibile combinare le opzioni specificate come segue:

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

Eseguire le singole fasi di conversione

Se si vogliono eseguire singoli passaggi del processo, è possibile usare:

Caricare solo i dati dal percorso LocalAssetDirectoryPath specificato.

.\Conversion.ps1 -Upload

Avviare solo il processo di conversione di un modello già caricato nell'archiviazione BLOB (non eseguire caricamento, non eseguire il polling dello stato di conversione) Lo script restituisce un oggetto conversionId.

.\Conversion.ps1 -ConvertAsset

È inoltre possibile recuperare lo stato di questa conversione usando:

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

Usare -Poll per restare in attesa fino a quando la conversione non viene eseguita o si verifica un errore.

Passaggi successivi

• Avvio rapido: Eseguire il rendering di un modello con Unity
• Avvio rapido: Convertire un modello per il rendering
• Conversione di modelli