Примеры скриптов PowerShell

  • Статья

Служба "Удаленная отрисовка Azure" предоставляет следующие два REST API:

Репозиторий примеров для ARR содержит в папке Scripts примеры скриптов для взаимодействия с REST API этой службы. В этой статье описывается их использование.

Совет

Существует также средство ARRT на базе пользовательского интерфейса, предназначенное для взаимодействия со службой. Это хорошая альтернатива использованию скриптов. Снимок экрана ARRT ARRT

Внимание!

Слишком частые вызовы функций REST API приведут к тому, что сервер начнет использовать регулирование и в итоге вернет ошибку. В этом случае идентификатор кода ошибки HTTP будет таким: 429 ("Слишком много запросов"). Поэтому очень важно, чтобы между последовательными вызовами была задержка в 5–10 секунд.

Предварительные требования

Для выполнения примеров скриптов требуется действующая оболочка Azure PowerShell.

  1. Чтобы установить Azure PowerShell, выполните следующие действия.

    1. Откройте окно PowerShell с правами администратора.
    2. Выполните Install-Module -Name Az -AllowClobber.

  2. Если при выполнении скриптов будут возникать ошибки, проверьте правильность политики выполнения.

    1. Откройте окно PowerShell с правами администратора.
    2. Выполните Set-ExecutionPolicy -ExecutionPolicy Unrestricted.

  3. Подготовьте учетную запись хранения Azure

  4. Войдите в подписку, содержащую учетную запись azure Удаленная отрисовка:

    1. Откройте окно PowerShell.
    2. Выполните Connect-AzAccount и следуйте инструкциям на экране.

    Примечание

    Если в организации есть несколько подписок, может потребоваться указать аргументы SubscriptionId и Tenant. См. документацию по Connect-AzAccount.

  5. Скачайте папку Scripts в репозитории службы "Удаленная отрисовка Azure" на сайте GitHub.

Файл конфигурации

Рядом с файлами .ps1 есть файл arrconfig.json, который нужно заполнить следующим образом.

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

Внимание!

Убедитесь, что в пути LocalAssetDirectoryPath следует правильно экранировать обратную косую черту, используя двойные обратные косые черты : "\\" и используйте косую черту "/" во всех других путях, таких как inputFolderPath и inputAssetPath.

Внимание!

Необязательные значения должны быть заполнены либо необходимо удалить ключ и значение. Например, если параметр не используется "outputAssetFileName" , необходимо удалить всю строку внутри arrconfig.json.

accountSettings

Инструкции по arrAccountId и arrAccountKey см. в статье Создание учетной записи для Удаленной отрисовки Azure. Должен arrAccountDomain быть регионом из списка доступных регионов.

renderingSessionSettings

Эта структура должна быть заполнена, если вы намерены выполнять RenderingSession.ps1:

  • vmSize. Определяет размер виртуальной машины. Выберите standard или premium. Завершайте сеансы отрисовки, когда они становятся не нужны.
  • maxLeaseTime. Прогнозируемая продолжительность аренды виртуальной машины. Виртуальная машина завершает работу по истечении срока аренды. Срок аренды можно продлить позже (см. здесь).
  • remoteRenderingDomain: Регион, в котором находится виртуальная машина удаленной отрисовки.

assetConversionSettings

Эта структура должна быть заполнена, если вы намерены выполнять Conversion.ps1.

Подробные сведения см. в статье Подготовка учетной записи хранения Azure.

Скрипт: RenderingSession.ps1

Этот скрипт используется для создания, запрашивания и завершения сеансов отрисовки.

Важно!

Обязательно заполните разделы accountSettings и renderingSessionSettings в файле arrconfig.json.

Создание сеанса отрисовки

Обычное использование с полностью заполненным файлом arrconfig.json:

.\RenderingSession.ps1

Скрипт вызывает REST API управления сеансами для запуска виртуальной машины отрисовки с указанными параметрами. При успешном выполнении он получает sessionId. Затем он опрашивает свойства сеанса, пока сеанс не будет готов или не произошла ошибка.

Чтобы использовать альтернативный файл конфигурации, выполните:

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

Вы можете переопределить отдельные параметры из файла конфигурации:

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

Вы можете запустить сеанс без опроса:

.\RenderingSession.ps1 -CreateSession

Полученный скриптом параметр sessionId нужно передавать в большинство команд сеанса.

Получение свойств сеанса

Чтобы получить свойства сеанса, выполните:

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

Команда -Poll ожидает, пока сеанс не перейдет в состояние готовности или не завершится ошибкой.

Перечисление активных сеансов

.\RenderingSession.ps1 -GetSessions

Остановка сеанса

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

Изменение свойств сеанса

Сейчас мы поддерживаем для сеанса только изменение параметра maxLeaseTime.

Примечание

Срок аренды всегда отсчитывается от момента первоначального создания виртуальной машины сеанса. Чтобы продлить аренду сеанса еще на час, увеличьте значение maxLeaseTime на один час.

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

Скрипт: Conversion.ps1

Этот скрипт используется для преобразования входных моделей в формат среды выполнения, характерный для Удаленной отрисовки Azure.

Важно!

Убедитесь, что вы заполнили разделы accountSettings и assetConversionSettings и параметр remoteRenderingDomain в файле renderingSessionSettings в файле arrconfig.json.

В этом скрипте демонстрируются два варианта использования учетных записей хранения со службой:

  • учетная запись хранения, связанная с учетной записью Удаленной отрисовки Azure;
  • предоставление доступа к хранилищу через подписанный URL-адрес (SAS).

Связанная учетная запись хранения

После полного заполнения файла arrconfig.json и привязки учетной записи хранения можно использовать следующую команду. Связывание учетной записи хранения описано в разделе о создании учетной записи.

Использование связанной учетной записи хранения является предпочтительным способом использования службы преобразования, так как для него не нужно создавать подписанные URL-адреса.

.\Conversion.ps1
  1. Отправьте все файлы, содержащиеся в , assetConversionSettings.modelLocation во входной контейнер BLOB-объектов в заданном inputFolderPathобъекте .
  2. Вызовите REST API преобразования модели, чтобы начать преобразование модели.
  3. Состояние преобразования будет опрашиваться, пока преобразование не завершится (успешно или с ошибкой).
  4. Будут выведены сведения о расположении преобразованного файла (учетная запись хранения, контейнер выходных данных, путь к файлу в контейнере).

Доступ к хранилищу через подписанные URL-адреса

.\Conversion.ps1 -UseContainerSas

В результате:

  1. Будет передан файл из локальной среды assetConversionSettings.localAssetDirectoryPath во входной контейнер больших двоичных объектов.
  2. Будет создан подписанный URL-адрес для контейнера входных данных.
  3. Будет создан подписанный URL-адрес для контейнера выходных данных.
  4. Будет вызван REST API преобразования модели, чтобы начать преобразование модели.
  5. Состояние преобразования будет опрашиваться, пока преобразование не завершится (успешно или с ошибкой).
  6. Будут выведены сведения о расположении преобразованного файла (учетная запись хранения, контейнер выходных данных, путь к файлу в контейнере).
  7. Будет выведен подписанный URL-адрес преобразованной модели в выходном контейнере больших двоичных объектов.

Дополнительные параметры командной строки

Чтобы использовать альтернативный файл конфигурации, выполните:

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

Вы можете запустить преобразование модели без опроса:

.\Conversion.ps1 -ConvertAsset

Вы можете переопределить отдельные параметры из файла конфигурации, указав следующие аргументы командной строки:

  • Id: идентификатор преобразования, указанный для получения состояния преобразования (GetConversionStatus).
  • ArrAccountId: значение arrAccountId из accountSettings.
  • ArrAccountKey: переопределение значения arrAccountKey из accountSettings.
  • ArrAccountDomain: переопределение для arrAccountDomain accountSettings
  • RemoteRenderingDomain: переопределение для remoteRenderingDomain renderingSessionSettings
  • ResourceGroup: переопределение значения resourceGroup из assetConversionSettings.
  • StorageAccountName: переопределение значения storageAccountName из assetConversionSettings.
  • BlobInputContainerName: переопределение значения blobInputContainer из assetConversionSettings.
  • LocalAssetDirectoryPath: переопределение значения localAssetDirectoryPath из assetConversionSettings.
  • InputAssetPath: переопределение значения inputAssetPath из assetConversionSettings.
  • BlobOutputContainerName: переопределение значения blobOutputContainerName из assetConversionSettings.
  • OutputFolderPath: переопределение значения outputFolderPath из assetConversionSettings.
  • OutputAssetFileName: переопределение значения outputAssetFileName из assetConversionSettings.

Например, можно объединить указанные параметры следующим образом:

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

Запуск отдельных этапов преобразования

Если вы хотите выполнить отдельные шаги этого процесса, можно сделать следующее.

Отправить данные только из заданного пути LocalAssetDirectoryPath.

.\Conversion.ps1 -Upload

Только запустите процесс преобразования модели, уже отправленной в хранилище BLOB-объектов (не запускайте отправку, не опрашивайте состояние преобразования). Скрипт возвращает значение conversionId.

.\Conversion.ps1 -ConvertAsset

Чтобы получить состояние преобразования в этом случае, используйте:

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

Команда -Poll ожидает, пока преобразование не завершится (успешно или с ошибкой).

Дальнейшие действия