Przykładowe skrypty programu PowerShell

  • Artykuł

Usługa Azure Remote Rendering udostępnia następujące dwa interfejsy API REST:

Repozytorium przykładów usługi ARR zawiera przykładowe skrypty w folderze Scripts na potrzeby interakcji z interfejsami API REST usługi. W tym artykule opisano ich użycie.

Porada

Istnieje również narzędzie oparte na interfejsie użytkownika o nazwie ARRT do interakcji z usługą, które jest wygodną alternatywą dla korzystania ze skryptów. Zrzut ekranu ARRT ARRT

Przestroga

Zbyt częste wywoływanie funkcji interfejsu API REST spowoduje, że serwer będzie ograniczał i zwracał awarię. Identyfikator kodu błędu HTTP w tym przypadku to 429 ("zbyt wiele żądań"). Zgodnie z zasadą kciuka opóźnienie między kolejnymi wywołaniami powinno być opóźnione o 5–10 sekund.

Wymagania wstępne

Aby wykonać przykładowe skrypty, potrzebna jest konfiguracja funkcjonalna Azure PowerShell.

  1. Zainstaluj moduł Azure PowerShell:

    1. Otwórz okno programu PowerShell z uprawnieniami administratora.
    2. Uruchom polecenie Install-Module -Name Az -AllowClobber

  2. Jeśli wystąpią błędy dotyczące uruchamiania skryptów, upewnij się, że zasady wykonywania są odpowiednio ustawione:

    1. Otwórz okno programu PowerShell z uprawnieniami administratora.
    2. Uruchom polecenie Set-ExecutionPolicy -ExecutionPolicy Unrestricted

  3. Przygotowywanie konta usługi Azure Storage

  4. Zaloguj się do subskrypcji zawierającej konto usługi Azure Remote Rendering:

    1. Otwórz okno programu PowerShell.
    2. Uruchom polecenie: Connect-AzAccount i postępuj zgodnie z instrukcjami wyświetlanymi na ekranie.

    Uwaga

    W przypadku, gdy organizacja ma więcej niż jedną subskrypcję, może być konieczne określenie argumentów SubscriptionId i Tenant. Szczegółowe informacje można znaleźć w dokumentacji connect-AzAccount.

  5. Pobierz folder Scripts z repozytorium Usługi Azure Remote Rendering GitHub.

Plik konfiguracji

.ps1 Obok plików znajduje się elementarrconfig.json, który należy wypełnić:

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

Przestroga

Upewnij się, że prawidłowo unikniesz ukośników odwrotnych w ścieżce LocalAssetDirectoryPath przy użyciu podwójnych ukośników odwrotnych: "\\" i użyj ukośników "/" we wszystkich innych ścieżkach, takich jak inputFolderPath i inputAssetPath.

Przestroga

Opcjonalne wartości należy wypełnić lub całkowicie usunąć klucz i wartość. Jeśli na przykład nie używasz parametru "outputAssetFileName" , musisz usunąć cały wiersz wewnątrz arrconfig.jsonelementu .

accountSettings

Aby uzyskać arrAccountId informacje i arrAccountKey, zobacz Tworzenie konta usługi Azure Remote Rendering. Element arrAccountDomain powinien być regionem z listy dostępnych regionów.

renderingSessionSettings

Tę strukturę należy wypełnić, jeśli chcesz uruchomić RenderingSession.ps1:

  • vmSize: Wybiera rozmiar maszyny wirtualnej. Wybierz pozycję Standardowa lub Premium. Zamknij sesje renderowania, gdy nie są już potrzebne.
  • maxLeaseTime: Czas trwania dzierżawy maszyny wirtualnej. Maszyna wirtualna zostanie zamknięta po wygaśnięciu dzierżawy. Czas dzierżawy można przedłużyć później (zobacz tutaj).
  • remoteRenderingDomain: Region, w którym znajduje się maszyna wirtualna renderowania zdalnego.

assetConversionSettings

Ta struktura musi zostać wypełniona, jeśli chcesz uruchomić Conversion.ps1.

Aby uzyskać szczegółowe informacje, zobacz Przygotowywanie konta usługi Azure Storage.

Skrypt: RenderingSession.ps1

Ten skrypt służy do tworzenia, wykonywania zapytań i zatrzymywania sesji renderowania.

Ważne

Upewnij się, że zostały wypełnione sekcje accountSettings i renderingSessionSettings w pliku arrconfig.json.

Tworzenie sesji renderowania

Normalne użycie z w pełni wypełnionym plikiem arrconfig.json:

.\RenderingSession.ps1

Skrypt wywołuje interfejs API REST zarządzania sesjami , aby uruchomić maszynę wirtualną renderowania z określonymi ustawieniami. W przypadku powodzenia pobiera identyfikator sesji. Następnie sonduje właściwości sesji, dopóki sesja nie będzie gotowa lub wystąpi błąd.

Aby użyć alternatywnego pliku konfiguracji :

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

Poszczególne ustawienia można zastąpić z pliku konfiguracji:

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

Aby rozpocząć sesję tylko bez sondowania, możesz użyć:

.\RenderingSession.ps1 -CreateSession

SessionId pobierany skrypt musi zostać przekazany do większości innych poleceń sesji.

Pobieranie właściwości sesji

Aby uzyskać właściwości sesji, uruchom polecenie:

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

Użyj polecenia -Poll , aby poczekać, aż sesja będzie gotowa lub wystąpił błąd.

Wyświetlanie listy aktywnych sesji

.\RenderingSession.ps1 -GetSessions

Zatrzymywanie sesji

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

Zmienianie właściwości sesji

Obecnie obsługujemy tylko zmianę wartości maxLeaseTime sesji.

Uwaga

Czas dzierżawy jest zawsze liczone od momentu utworzenia maszyny wirtualnej sesji. Aby więc przedłużyć dzierżawę sesji o inną godzinę, zwiększ wartość maxLeaseTime o jedną godzinę.

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

Skrypt: Conversion.ps1

Ten skrypt służy do konwertowania modeli wejściowych na określony format środowiska uruchomieniowego platformy Azure Remote Rendering.

Ważne

Upewnij się, że wypełniono sekcje accountSettings i assetConversionSettings oraz opcję remoteRenderingDomain w pliku renderingSessionSettings w pliku arrconfig.json.

Skrypt przedstawia dwie opcje używania kont magazynu z usługą:

  • Konto magazynu połączone z kontem usługi Azure Remote Rendering
  • Zapewnianie dostępu do magazynu za pośrednictwem sygnatur dostępu współdzielonego (SAS)

Połączone konto magazynu

Po wypełnieniu pliku arrconfig.json i połączeniu konta magazynu można użyć następującego polecenia. Łączenie konta magazynu zostało opisane w temacie Tworzenie konta.

Użycie połączonego konta magazynu jest preferowanym sposobem korzystania z usługi konwersji, ponieważ nie ma potrzeby generowania sygnatur dostępu współdzielonego.

.\Conversion.ps1
  1. Przekaż wszystkie pliki zawarte w assetConversionSettings.modelLocation kontenerze wejściowych obiektów blob w ramach danego inputFolderPathelementu .
  2. Wywoływanie interfejsu API REST konwersji modelu w celu rozpoczęcia konwersji modelu
  3. Sonduj stan konwersji do momentu pomyślnego lub zakończonego niepowodzeniem konwersji.
  4. Szczegóły wyjściowe przekonwertowanej lokalizacji pliku (konto magazynu, kontener wyjściowy, ścieżka pliku w kontenerze).

Dostęp do magazynu za pośrednictwem sygnatur dostępu współdzielonego

.\Conversion.ps1 -UseContainerSas

Spowoduje to:

  1. Przekaż plik lokalny z assetConversionSettings.localAssetDirectoryPath kontenera wejściowego obiektu blob.
  2. Wygeneruj identyfikator URI sygnatury dostępu współdzielonego dla kontenera wejściowego.
  3. Wygeneruj identyfikator URI sygnatury dostępu współdzielonego dla kontenera wyjściowego.
  4. Wywołaj interfejs API REST konwersji modelu , aby rozpocząć konwersję modelu.
  5. Sonduj stan konwersji do momentu pomyślnego lub zakończonego niepowodzeniem konwersji.
  6. Szczegóły wyjściowe przekonwertowanej lokalizacji pliku (konto magazynu, kontener wyjściowy, ścieżka pliku w kontenerze).
  7. Dane wyjściowe identyfikatora URI sygnatury dostępu współdzielonego do przekonwertowanego modelu w wyjściowym kontenerze obiektów blob.

Dodatkowe opcje wiersza polecenia

Aby użyć alternatywnego pliku konfiguracji :

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

Aby rozpocząć konwersję modelu tylko bez sondowania, można użyć:

.\Conversion.ps1 -ConvertAsset

Poszczególne ustawienia można zastąpić z pliku konfiguracji przy użyciu następujących przełączników wiersza polecenia:

  • Identyfikator: ConversionId używany z parametrem GetConversionStatus
  • ArrAccountId: arrAccountId kontaUstawienia
  • ArrAccountKey: przesłoń dla wartości arrAccountKey elementu accountSettings
  • ArrAccountDomain: zastąpienie dla arrAccountDomain kontaUstawienia
  • RemoteRenderingDomain: zastąpienie dla remoteRenderingDomain renderowaniaSessionSettings
  • ResourceGroup: zastępowanie elementu resourceGroup elementu assetConversionSettings
  • StorageAccountName: zastąpienie wartości storageAccountName elementu assetConversionSettings
  • BlobInputContainerName: zastąpienie obiektu blobInputContainer elementu assetConversionSettings
  • LocalAssetDirectoryPath: przesłonięcie elementu localAssetDirectoryPath elementu assetConversionSettings
  • InputAssetPath: przesłonięcie parametru inputAssetPath of assetConversionSettings
  • BlobOutputContainerName: zastąpienie dla obiektu blobOutputContainerName elementu assetConversionSettings
  • OutputFolderPath: przesłonięcie elementu outputFolderPath elementu assetConversionSettings
  • OutputAssetFileName: przesłonięcie elementu outputAssetFileName elementu assetConversionSettings

Na przykład możesz połączyć podane opcje w następujący sposób:

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

Uruchamianie poszczególnych etapów konwersji

Jeśli chcesz uruchomić poszczególne kroki procesu, możesz użyć następujących funkcji:

Przekaż tylko dane z danego elementu LocalAssetDirectoryPath.

.\Conversion.ps1 -Upload

Uruchom tylko proces konwersji modelu, który został już przekazany do magazynu obiektów blob (nie uruchamiaj przekazywania, nie sonduj stanu konwersji) Skrypt zwraca identyfikator konwersji.

.\Conversion.ps1 -ConvertAsset

Stan konwersji tej konwersji można pobrać przy użyciu:

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

Użyj -Poll polecenia , aby poczekać na zakończenie konwersji lub wystąpił błąd.

Następne kroki