Scripts de exemplo do PowerShell

  • Artigo

O Azure Remote Rendering fornece essas duas APIs REST:

O repositório de amostras do ARR contém scripts de exemplo na pasta Scripts para interagir com as APIs REST do serviço. Este artigo descreve o uso desses scripts.

Dica

Também há uma ferramenta baseada em interface do usuário chamada ARRT para fazer a interação com o serviço, que é uma alternativa conveniente ao uso de scripts. ARRT

Cuidado

Chamar funções da API REST com muita frequência fará com que o servidor seja limitado e retorne uma falha eventualmente. Nesse caso, a ID do código de falha HTTP é 429 ("muitas solicitações"). Como regra geral, deve haver um atraso de 5 a 10 segundos entre as chamadas subsequentes.

Pré-requisitos

Para executar os scripts de exemplo, você precisa de uma configuração funcional do Azure PowerShell.

  1. Instalar o Azure PowerShell:

    1. Abra uma janela do PowerShell com direitos de administrador.
    2. Execute: Install-Module -Name Az -AllowClobber

  2. Se você obtiver erros sobre a execução de scripts, verifique se a política de execução está definida adequadamente:

    1. Abra uma janela do PowerShell com direitos de administrador.
    2. Execute: Set-ExecutionPolicy -ExecutionPolicy Unrestricted

  3. Preparar uma conta de Armazenamento do Azure

  4. Entre na sua assinatura que contém sua conta do Azure Remote Rendering:

    1. Abra uma janela do PowerShell.
    2. Execute: Connect-AzAccount e siga as instruções na tela.

    Observação

    Caso sua organização tenha mais de uma assinatura, talvez seja necessário especificar os argumentos SubscriptionId e Tenant. Encontre detalhes na Documentação sobre Connect-AzAccount.

  5. Baixe a pasta Scripts do repositório do GitHub do Azure Remote Rendering.

Arquivo de configuração

Ao lado dos arquivos .ps1 há um arrconfig.json que você precisa preencher:

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

Cuidado

Certifique-se de escapar as barras invertidas corretamente no caminho LocalAssetDirectoryPath usando barras invertidas duplas: "\\" e usar barras "/" em todos os outros caminhos, como inputFolderPath e inputAssetPath.

Cuidado

Os valores opcionais precisam ser preenchidos ou você precisará remover a chave e o valor por completo. Por exemplo, se você não usar o parâmetro "outputAssetFileName", precisará excluir a linha inteira dentro de arrconfig.json.

accountSettings

Para arrAccountId e arrAccountKey, confira Criar uma conta do Azure Remote Rendering. A arrAccountDomain deve ser uma região da lista de regiões disponíveis .

renderingSessionSettings

Esta estrutura precisa ser preenchida caso você deseje executar RenderingSession.ps1:

  • vmSize: Seleciona o tamanho da máquina virtual. Selecione standard ou premium. Desligue as sessões de renderização quando você não precisar mais delas.
  • maxLeaseTime: A duração pela qual você deseja arrendar a VM. A VM é desligada quando a concessão expira. O tempo de locação pode ser estendido posteriormente (confira aqui).
  • remoteRenderingDomain: a região onde reside a VM de renderização remota.
    • Pode ser diferente do arrAccountDomain, mas ainda deve ser uma região da lista de regiões disponíveis

assetConversionSettings

Essa estrutura deverá ser preenchida se você quiser executar Conversion.ps1.

Para obter detalhes, confira Preparar uma conta de Armazenamento do Azure.

Script: RenderingSession.ps1

Esse script é usado para criar, consultar e parar sessões de renderização.

Importante

Confirme se você preencheu as seções accountSettings e renderingSessionSettings no arrconfig.json.

Criar uma sessão de renderização

Uso normal com um arrconfig.json totalmente preenchido:

.\RenderingSession.ps1

O script chama a API REST de gerenciamento de sessão para ativar uma VM de renderização com as configurações especificadas. Em caso de êxito, ele recupera a sessionId. Depois, ele pesquisa as propriedades da sessão até que a sessão esteja pronta ou ocorra um erro.

Para usar um arquivo configuração alternativa:

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

Você pode substituir configurações individuais do arquivo de configuração:

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

Para apenas iniciar uma sessão sem sondagem, você pode usar:

.\RenderingSession.ps1 -CreateSession

A sessionId que o script recupera deve ser passada para a maioria dos outros comandos da sessão.

Recuperar propriedades da sessão

Para obter as propriedades de uma sessão, execute:

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

Use -Poll para aguardar até que a sessão esteja pronta ou até que ocorra um erro.

Listar sessões ativas

.\RenderingSession.ps1 -GetSessions

Parar uma sessão

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

Alterar propriedades da sessão

No momento, só é possível a alteração do maxLeaseTime de uma sessão.

Observação

O tempo de concessão sempre é contado tendo por base o momento em que a VM da sessão foi criada inicialmente. Assim, para estender a concessão da sessão por mais uma hora, aumente o maxLeaseTime em uma hora.

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

Script: Conversion.ps1

Esse script é usado para converter modelos de entrada no formato do runtime específico do Azure Remote Rendering.

Importante

Certifique-se de ter preenchido as seções accountSettings e assetConversionSettings e a opção remoteRenderingDomain na opção renderingSessionSettings no arrconfig.json.

O script demonstra as duas opções para usar contas de armazenamento com o serviço:

  • Conta de armazenamento vinculada à conta do Azure Remote Rendering
  • Fornecendo acesso ao armazenamento por meio de SAS (Assinaturas de Acesso Compartilhado)

Conta de armazenamento vinculada

Depois de preencher totalmente o arrconfig.json e vincular uma conta de armazenamento, você pode usar o comando a seguir. A vinculação da sua conta de armazenamento é descrita em Criar uma conta.

O uso de uma conta de armazenamento vinculada é a maneira preferencial para usar o serviço de conversão, visto que não há necessidade de gerar Assinaturas de Acesso Compartilhado.

.\Conversion.ps1
  1. Carregue todos os arquivos contidos no assetConversionSettings.modelLocation no contêiner de blobs de entrada sob o inputFolderPath fornecido.
  2. Chamar a API REST de conversão do modelo para iniciar a conversão do modelo
  3. Sondar o status da conversão até a conversão ser bem-sucedida ou falhar.
  4. Gerar detalhes da localização do arquivo convertido (conta de armazenamento, contêiner de saída e caminho do arquivo no contêiner).

Acesso ao armazenamento por meio Assinaturas de Acesso Compartilhado

.\Conversion.ps1 -UseContainerSas

Isso vai:

  1. Carregar o arquivo local do assetConversionSettings.localAssetDirectoryPath no contêiner de blob de entrada.
  2. Gerar um URI de SAS para o contêiner de entrada.
  3. Gerar um URI de SAS para o contêiner de saída.
  4. Chamar a API REST de conversão do modelo para iniciar a conversão do modelo.
  5. Sondar o status da conversão até a conversão ser bem-sucedida ou falhar.
  6. Gerar detalhes da localização do arquivo convertido (conta de armazenamento, contêiner de saída e caminho do arquivo no contêiner).
  7. Gerar um URI de SAS para o modelo convertido no contêiner de blob de saída.

Opções adicionais de linha de comando

Para usar um arquivo configuração alternativa:

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

Para apenas iniciar conversão de modelo sem sondagem, você pode usar:

.\Conversion.ps1 -ConvertAsset

Você pode substituir configurações individuais do arquivo de configuração usando as seguintes opções de linha de comando:

  • Id: ConversionId usada com GetConversionStatus
  • ArrAccountId: arrAccountId de accountSettings
  • ArrAccountKey: substituição para arrAccountKey de accountSettings
  • ArrAccountDomain: substitui arrAccountDomain de accountSettings
  • RemoteRenderingDomain: substituir remoteRenderingDomain de renderingSessionSettings
  • ResourceGroup: substituição para resourceGroup de assetConversionSettings
  • StorageAccountName: substituição para storageAccountName de assetConversionSettings
  • BlobInputContainerName: substituição para blobInputContainer de assetConversionSettings
  • LocalAssetDirectoryPath: substituição para localAssetDirectoryPath de assetConversionSettings
  • InputAssetPath: substituição para inputAssetPath de assetConversionSettings
  • BlobOutputContainerName: substituição para blobOutputContainerName de assetConversionSettings
  • OutputFolderPath: substituição para outputFolderPath de assetConversionSettings
  • OutputAssetFileName: substituição para outputAssetFileName de assetConversionSettings

Por exemplo, você pode combinar as opções fornecidas da seguinte forma:

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

Executar os estágios de conversão individuais

Se você quiser executar etapas individuais do processo, poderá usar:

Somente carregar dados do LocalAssetDirectoryPath especificado.

.\Conversion.ps1 -Upload

Inicie apenas o processo de conversão de um modelo já carregado no armazenamento de blobs (não executa o Upload, não pesquisa o status da conversão). O script retorna um conversionId.

.\Conversion.ps1 -ConvertAsset

E você pode recuperar o status de conversão dessa conversão usando:

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

Use -Poll para aguardar até que a conversão seja concluída ou um erro tenha ocorrido.

Próximas etapas