PowerShell-voorbeeldscripts

  • Artikel

Azure Remote Rendering bevat de volgende twee REST API's:

De ARR-opslagplaats bevat voorbeeldscripts in de map Scripts voor het werken met de REST API's van de service. In dit artikel wordt het gebruik hiervan beschreven.

Tip

Er is ook een op de gebruikersinterface gebaseerd hulpprogramma met de naam ARRT om met de service te communiceren. Dit is een handig alternatief in plaats van scripts. ARRT

Waarschuwing

Als REST API-functies te vaak worden aangeroepen, wordt de server trager en wordt er uiteindelijk een fout geretourneerd. De HTTP-foutcode-id is in dit geval 429 ('te veel aanvragen'). Als vuistregel moet er een vertraging van 5-10 seconden tussen opeenvolgende aanroepen in acht worden genomen.

Vereisten

Als u de voorbeeldscripts wilt uitvoeren, hebt u een functionele installatie van Azure PowerShell nodig.

  1. Installeer Azure PowerShell:

    1. Open een PowerShell-venster met beheerdersrechten.
    2. Voer dit uit: Install-Module -Name Az -AllowClobber

  2. Als er fouten optreden bij het uitvoeren van scripts, controleert u of het uitvoeringsbeleid op de juiste wijze is ingesteld:

    1. Open een PowerShell-venster met beheerdersrechten.
    2. Voer dit uit: Set-ExecutionPolicy -ExecutionPolicy Unrestricted

  3. Een Azure-opslagaccount voorbereiden

  4. Meld u aan bij uw abonnement met uw Azure Remote Rendering-account:

    1. Open een Powershell-venster.
    2. Voer Connect-AzAccount uit en volg de aanwijzingen op het scherm.

    Notitie

    Als uw organisatie meerdere abonnementen heeft, moet u mogelijk de argumenten SubscriptionId en Tenant opgeven. Meer informatie vindt u in de documentatie bij Connect-AzAccount.

  5. Download de map Scripts in de Azure Remote Rendering GitHub-opslagplaats.

Configuratiebestand

Naast de .ps1-bestanden ziet u een arrconfig.json die u moet invullen:

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

Waarschuwing

Zorg ervoor dat u backslashes in het pad LocalAssetDirectoryPath op de juiste manier escapet met behulp van dubbele backslashes: "\\" en gebruik slashes "/" in alle andere paden, zoals inputFolderPath en inputAssetPath.

Waarschuwing

Optionele waarden moeten worden ingevuld of u verwijdert de sleutel en de waarde helemaal. Als u bijvoorbeeld de "outputAssetFileName" parameter niet gebruikt, moet u de hele regel in arrconfig.jsonverwijderen.

accountSettings

Zie Een Azure Remote Rendering-account maken voor arrAccountId en arrAccountKey. De arrAccountDomain moet een regio zijn uit de lijst met beschikbare regio's.

renderingSessionSettings

Deze structuur moet worden ingevuld als u RenderingSession.ps1 wilt uitvoeren:

  • vmSize: Hiermee wordt de grootte van de virtuele machine geselecteerd. Selecteer standard of premium. Schakel renderingsessies uit wanneer u deze niet meer nodig hebt.
  • maxLeaseTime: De duur waarvoor u de virtuele machine wilt leasen. De VM wordt afgesloten wanneer de lease verloopt. De leasetijd kan later worden verlengd (zie hier).
  • remoteRenderingDomain: De regio waarin de externe rendering-VM zich bevindt.

assetConversionSettings

Deze structuur moet worden ingevuld als u Conversion.ps1 wilt uitvoeren.

Zie Een Azure-opslagaccount voorbereiden voor meer informatie.

Script: RenderingSession.ps1

Dit script wordt gebruikt om renderingsessies te maken, op te vragen en te stoppen.

Belangrijk

Zorg ervoor dat u de secties accountSettings en renderingSessionSettings in arrconfig.json hebt ingevuld.

Een renderingsessie maken

Normaal gebruik met een volledig ingevulde arrconfig.json:

.\RenderingSession.ps1

Het script roept de REST API voor sessiebeheer aan om een rendering-VM te maken met de opgegeven instellingen. Als dit is gelukt, wordt de sessionId opgehaald. Daarna worden de sessie-eigenschappen gepeild totdat de sessie gereed is of er een fout is opgetreden.

Een alternatief configuratiebestand gebruiken:

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

U kunt de afzonderlijke instellingen van het configuratiebestand overschrijven:

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

Als u alleen een sessie wilt starten zonder polling, kunt u het volgende gebruiken:

.\RenderingSession.ps1 -CreateSession

De sessionId die het script ophaalt, moet worden doorgegeven aan de meeste andere sessieopdrachten.

Sessie-eigenschappen ophalen

Als u de eigenschappen van een sessie wilt ophalen, voert u het volgende uit:

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

Gebruik -Poll om te wachten tot de sessie gereed is of er een fout is opgetreden.

Actieve sessies weergeven

.\RenderingSession.ps1 -GetSessions

Een sessie stoppen

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

Sessie-eigenschappen wijzigen

Op dit moment ondersteunen we alleen het wijzigen van de maxLeaseTime van een sessie.

Notitie

De leasetijd wordt altijd geteld vanaf het moment waarop de sessie-VM voor het eerst is gemaakt. Als u de sessielease wilt uitbreiden met een uur, moet u maxLeaseTime verhogen met één uur.

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

Script: Conversion.ps1

Dit script wordt gebruikt om invoermodellen te converteren naar de specifieke runtime-indeling van Azure Remote Rendering.

Belangrijk

Zorg ervoor dat u de secties accountSettings en assetConversionSettings en de optie remoteRenderingDomain in de renderingSessionSettings in arrconfig.json hebt ingevuld.

In het script ziet u de twee opties voor het gebruik van opslagaccounts met de service:

  • Opslagaccount gekoppeld aan Azure Remote Rendering-account
  • Toegang verlenen tot opslag via Shared Access Signatures (SAS)

Gekoppeld opslagaccount

Zodra u arrconfig.json volledig hebt ingevuld en een opslagaccount hebt gekoppeld, kunt u de volgende opdracht gebruiken. Het koppelen van uw opslagaccount wordt beschreven in Een account maken.

Het gebruik van een gekoppeld opslagaccount is de voorkeursmanier voor het gebruik van de conversieservice, omdat er geen Shared Access Signatures hoeven te worden gegenereerd.

.\Conversion.ps1
  1. Upload alle bestanden in de assetConversionSettings.modelLocation naar de invoer-blobcontainer onder de opgegeven inputFolderPath.
  2. De REST API voor modelconversie aanroepen om de modelconversie te starten
  3. De conversiestatus pollen totdat de conversie is geslaagd of mislukt.
  4. Uitvoerdetails van de geconverteerde bestandslocatie (opslagaccount, uitvoercontainer en bestandspad in de container).

Toegang tot opslag via Shared Access Signatures

.\Conversion.ps1 -UseContainerSas

Hiermee wordt:

  1. Het lokale bestand van de assetConversionSettings.localAssetDirectoryPath geüpload naar de invoerblobcontainer.
  2. Een SAS-URI gegenereerd voor de invoercontainer.
  3. Een SAS-URI gegenereerd voor de uitvoercontainer.
  4. De REST API voor modelconversie aanroepen om de modelconversie te starten.
  5. De conversiestatus pollen totdat de conversie is geslaagd of mislukt.
  6. Uitvoerdetails van de geconverteerde bestandslocatie (opslagaccount, uitvoercontainer en bestandspad in de container).
  7. Een SAS-URI uitvoeren naar het geconverteerde model in de uitvoerblobcontainer.

Aanvullende opdrachtregelopties

Een alternatief configuratiebestand gebruiken:

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

Als u alleen een modelconversie wilt starten zonder polling, kunt u het volgende gebruiken:

.\Conversion.ps1 -ConvertAsset

Met de volgende opdrachtregelopties kunt u de afzonderlijke instellingen uit het configuratiebestand overschrijven:

  • Id: ConversionId gebruikt met GetConversionStatus
  • ArrAccountId: arrAccountId van accountSettings
  • ArrAccountKey: overschrijving voor arrAccountKey van accountSettings
  • ArrAccountDomain: overschrijven voor arrAccountDomain van accountSettings
  • RemoteRenderingDomain: override for remoteRenderingDomain of renderingSessionSettings
  • ResourceGroup: overschrijving voor resourceGroup van assetConversionSettings
  • StorageAccountName: overschrijving voor storageAccountName van assetConversionSettings
  • BlobInputContainerName: overschrijving voor blobInputContainer van assetConversionSettings
  • LocalAssetDirectoryPath: overschrijving voor localAssetDirectoryPath van assetConversionSettings
  • InputAssetPath: overschrijving voor inputAssetPath van assetConversionSettings
  • BlobOutputContainerName: overschrijving voor blobOutputContainerName van assetConversionSettings
  • OutputFolderPath: overschrijving voor outputFolderPath van assetConversionSettings
  • OutputAssetFileName: overschrijving voor outputAssetFileName van assetConversionSettings

U kunt bijvoorbeeld de opgegeven opties als volgt combineren:

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

De afzonderlijke conversiefasen uitvoeren

Als u afzonderlijke stappen van het proces wilt uitvoeren, kunt u het volgende gebruiken:

Alleen gegevens uit het opgegeven LocalAssetDirectoryPath uploaden.

.\Conversion.ps1 -Upload

Start alleen het conversieproces van een model dat al is geüpload naar blobopslag (voer Uploaden niet uit, controleer de conversiestatus niet). Het script retourneert een conversionId.

.\Conversion.ps1 -ConvertAsset

En u kunt de conversiestatus van deze conversie ophalen met:

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

Gebruik -Poll om te wachten tot de conversie gereed is of er een fout is opgetreden.

Volgende stappen