Teilen über

PowerShell-Beispielskripts

  • Artikel

Azure Remote Rendering verfügt über die beiden folgenden REST-APIs:

Das Repository mit den ARR-Beispielen enthält im Ordner Scripts Beispielskripts für die Interaktion mit den REST-APIs des Diensts. In diesem Artikel wird die Nutzung beschrieben.

Tipp

Ferner ist ein Tool mit grafischer Benutzeroberfläche unter dem Namen ARRT für die Interaktion mit dem Dienst verfügbar, das eine komfortable Alternative zum Verwenden von Skripts darstellt. ARRT

Achtung

Zu häufiges Aufrufen von REST-API-Befehlen bewirkt, dass der Server eine Drosselung durchführt und schließlich einen Fehler zurückgibt. Die HTTP-Fehlercode-ID lautet in diesem Fall 429 („zu viele Anforderungen“). Als Faustregel sollte eine Verzögerung von 5–10 Sekunden zwischen nachfolgenden Aufrufen erfolgen.

Voraussetzungen

Zum Ausführen der Beispielskripts benötigen Sie eine funktionsfähige Azure PowerShell-Instanz.

  1. Installieren Sie Azure PowerShell:

    1. Öffnen Sie ein PowerShell-Fenster mit Administratorrechten.
    2. Führen Sie Install-Module -Name Az -AllowClobber aus.

  2. Vergewissern Sie sich, dass Ihre Ausführungsrichtlinie richtig festgelegt wurde, falls Sie beim Ausführen von Skripts Fehler erhalten:

    1. Öffnen Sie ein PowerShell-Fenster mit Administratorrechten.
    2. Führen Sie Set-ExecutionPolicy -ExecutionPolicy Unrestricted aus.

  3. Vorbereiten von Azure Storage-Konten

  4. Melden Sie sich bei Ihrem Abonnement an, unter dem sich Ihr Azure Remote Rendering-Konto befindet:

    1. Öffnen Sie ein PowerShell-Fenster.
    2. Führen Sie Connect-AzAccount aus, und befolgen Sie die Anweisungen auf dem Bildschirm.

    Hinweis

    Falls Ihre Organisation über mehrere Abonnements verfügt, müssen Sie ggf. die Argumente für die Abonnement-ID und den Mandanten angeben. Weitere Informationen finden Sie in der Dokumentation zu „Connect-AzAccount“.

  5. Laden Sie den Ordner Scripts aus dem Azure Remote Rendering GitHub-Repository herunter.

Konfigurationsdatei

Neben den .ps1-Dateien befindet sich das Element arrconfig.json, das Sie ausfüllen müssen:

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

Achtung

Ersetzen Sie die umgekehrten Schrägstriche im Pfad „LocalAssetDirectoryPath“, indem Sie doppelte umgekehrte Schrägstriche (\\) als Escapezeichen verwenden. Verwenden Sie in allen anderen Pfaden, z. B. „inputFolderPath“ und „inputAssetPath“ reguläre Schrägstriche (/).

Achtung

Optionale Werte müssen ausgefüllt werden, oder Sie müssen den Schlüssel und den Wert vollständig entfernen. Wenn Sie z. B. nicht den Parameter "outputAssetFileName" verwenden, müssen Sie die gesamte Zeile in arrconfig.json löschen.

accountSettings

Informationen zu arrAccountId und arrAccountKey finden Sie unter Erstellen eines Azure Remote Rendering-Kontos. Die arrAccountDomain sollte eine Region aus der Liste der verfügbaren Regionen sein.

renderingSessionSettings

Diese Struktur muss ausgefüllt werden, wenn Sie RenderingSession.ps1 ausführen möchten:

  • vmSize: Dient zum Auswählen der Größe des virtuellen Computers. Sie können zwischen standard und premium wählen. Beenden Sie Renderingsitzungen, wenn Sie sie nicht mehr benötigen.
  • maxLeaseTime: Der Zeitraum, wie lange Sie die VM leasen möchten. Die VM wird heruntergefahren, wenn die Leasedauer abläuft. Die Leasedauer kann später verlängert werden (siehe hier).
  • remoteRenderingDomain: Die Region, in der sich die Remoterendering-VM befindet.

assetConversionSettings

Diese Struktur muss ausgefüllt werden, wenn Sie Conversion.ps1 ausführen möchten.

Ausführliche Informationen finden Sie unter Vorbereiten von Azure Storage-Konten.

Skript: RenderingSession.ps1

Mit diesem Skript werden Renderingsitzungen erstellt, abgefragt und beendet.

Wichtig

Vergewissern Sie sich, dass Sie in „arrconfig.json“ die Abschnitte accountSettings und renderingSessionSettings ausgefüllt haben.

Erstellen einer Renderingsitzung

Übliche Nutzung mit vollständig ausgefüllter Datei „arrconfig.json“:

.\RenderingSession.ps1

Mit dem Skript wird die REST-API für die Sitzungsverwaltung aufgerufen, um eine Rendering-VM mit den angegebenen Einstellungen zu starten. Bei erfolgreicher Ausführung wird die sessionId abgerufen. Danach werden die Sitzungseigenschaften abgefragt, bis die Sitzung bereit ist oder ein Fehler auftritt.

Gehen Sie wie folgt vor, um eine andere Konfigurationsdatei zu verwenden:

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

Sie können einzelne Einstellungen der Konfigurationsdatei außer Kraft setzen:

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

Sie können Folgendes verwenden, um eine Sitzung ohne Abruf zu starten:

.\RenderingSession.ps1 -CreateSession

Die sessionId, die mit dem Skript abgerufen wird, muss an die meisten anderen Sitzungsbefehle übergeben werden.

Abrufen von Sitzungseigenschaften

Führen Sie Folgendes aus, um die Eigenschaften einer Sitzung abzurufen:

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

Verwenden Sie -Poll, wenn gewartet werden soll, bis die Sitzung bereit ist oder ein Fehler aufgetreten ist.

Auflisten der aktiven Sitzungen

.\RenderingSession.ps1 -GetSessions

Beenden einer Sitzung

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

Ändern von Sitzungseigenschaften

Derzeit wird nur die Änderung des maxLeaseTime-Elements einer Sitzung unterstützt.

Hinweis

Die Leasedauer beginnt immer ab dem Zeitpunkt, zu dem die Sitzungs-VM ursprünglich erstellt wurde. Erhöhen Sie also maxLeaseTime um eine Stunde, um die Leasedauer für die Sitzung um eine Stunde zu verlängern.

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

Skript: Conversion.ps1

Dieses Skript wird verwendet, um Eingabemodelle in das spezifische Runtimeformat für Azure Remote Rendering zu konvertieren.

Wichtig

Stellen Sie sicher, dass Sie die Abschnitte accountSettings und assetConversionSettings sowie die Option remoteRenderingDomain in der renderingSessionSettings in arrconfig.json ausgefüllt haben.

Mit dem Skript werden die beiden Optionen für die Nutzung von Speicherkonten für den Dienst veranschaulicht:

  • Mit dem Azure Remote Rendering-Konto verknüpftes Speicherkonto
  • Gewähren des Zugriffs auf Speicher über Shared Access Signatures (SAS)

Verknüpftes Speicherkonto

Nachdem Sie „arrconfig.json“ vollständig ausgefüllt und ein Speicherkonto verknüpft haben, können Sie den folgenden Befehl verwenden. Die Verknüpfung Ihres Speicherkontos ist unter Erstellen eines Kontos beschrieben.

Die Verwendung eines verknüpften Speicherkontos ist die bevorzugte Vorgehensweise zur Nutzung des Konvertierungsdiensts, da keine Shared Access Signatures generiert werden müssen.

.\Conversion.ps1
  1. Laden Sie alle in assetConversionSettings.modelLocation enthaltenen Dateien in den Eingabeblobcontainer hoch, der sich unter dem angegebenen inputFolderPath befindet.
  2. Rufen Sie die REST-API für die Modellkonvertierung auf, um die Modellkonvertierung zu starten.
  3. Rufen Sie den Konvertierungsstatus ab, bis die Konvertierung erfolgreich abgeschlossen wurde oder ein Fehler aufgetreten ist.
  4. Geben Sie die Details des Speicherorts der konvertierten Datei aus (Speicherkonto, Ausgabecontainer, Dateipfad im Container).

Zugriff auf Speicher über Shared Access Signatures

.\Conversion.ps1 -UseContainerSas

Dies bewirkt Folgendes:

  1. Hochladen der lokalen Datei aus assetConversionSettings.localAssetDirectoryPath in den Eingabeblobcontainer
  2. Generieren eines SAS-URI für den Eingabecontainer
  3. Generieren eines SAS-URI für den Ausgabecontainer
  4. Aufrufen der REST-API für die Modellkonvertierung, um die Modellkonvertierung zu starten
  5. Abrufen des Konvertierungsstatus, bis die Konvertierung erfolgreich abgeschlossen wurde oder ein Fehler aufgetreten ist
  6. Ausgeben der Details des Speicherorts der konvertierten Datei (Speicherkonto, Ausgabecontainer, Dateipfad im Container)
  7. Ausgeben eines SAS-URI für das konvertierte Modell im Ausgabeblobcontainer

Weitere Befehlszeilenoptionen

Gehen Sie wie folgt vor, um eine andere Konfigurationsdatei zu verwenden:

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

Sie können Folgendes verwenden, um nur die Modellkonvertierung ohne Abruf zu starten:

.\Conversion.ps1 -ConvertAsset

Sie können in der Konfigurationsdatei einzelne Einstellungen außer Kraft setzen, indem Sie die folgenden Befehlszeilenschalter verwenden:

  • Id: Für „GetConversionStatus“ verwendete „ConversionId“
  • ArrAccountId: „arrAccountId“ von „accountSettings“
  • ArrAccountKey: Außerkraftsetzung für „arrAccountKey“ von „accountSettings“
  • ArrAccountDomain: Außerkraftsetzung für arrAccountDomain von accountSettings
  • RemoteRenderingDomain: Außerkraftsetzung für remoteRenderingDomain von renderingSessionSettings
  • ResourceGroup: Außerkraftsetzung für „resourceGroup“ von „assetConversionSettings“
  • StorageAccountName: Außerkraftsetzung für „storageAccountName“ von „assetConversionSettings“
  • BlobInputContainerName: Außerkraftsetzung für „blobInputContainer“ von „assetConversionSettings“
  • LocalAssetDirectoryPath: Außerkraftsetzung für „localAssetDirectoryPath“ von „assetConversionSettings“
  • InputAssetPath: Außerkraftsetzung für „inputAssetPath“ von „assetConversionSettings“
  • BlobOutputContainerName: Außerkraftsetzung für „blobOutputContainerName“ von „assetConversionSettings“
  • OutputFolderPath: Außerkraftsetzung für „outputFolderPath“ von „assetConversionSettings“
  • OutputAssetFileName: Außerkraftsetzung für „outputAssetFileName“ von „assetConversionSettings“

Beispielsweise können Sie die angegebenen Optionen wie folgt kombinieren:

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

Ausführen der einzelnen Konvertierungsstufen

Sie können Folgendes verwenden, wenn Sie einzelne Schritte des Prozesses ausführen möchten:

Hochladen von Daten nur für „LocalAssetDirectoryPath“

.\Conversion.ps1 -Upload

Starten Sie nur den Konvertierungsprozess für ein Modell, das bereits in Blobspeicher hochgeladen wurde (kein Ausführen von „Hochladen“, kein Abruf des Konvertierungsstatus). Das Skript gibt eine conversionId zurück.

.\Conversion.ps1 -ConvertAsset

Sie können den Status für diese Konvertierung wie folgt abrufen:

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

Verwenden Sie -Poll, wenn gewartet werden soll, bis die Konvertierung abgeschlossen oder ein Fehler aufgetreten ist.

Nächste Schritte