Scripts do PowerShell de exemplo

O Azure Remote Rendering fornece as duas APIs REST seguintes:

• API REST de Conversão
• API REST de Sessão

O repositório de exemplos de ARR contém scripts de exemplo na pasta Scripts para interagir com as APIs REST do serviço. Este artigo descreve a respetiva utilização.

Dica

Também existe uma ferramenta baseada na IU denominada ARRT para interagir com o serviço, que é uma alternativa conveniente à utilização de scripts.

Atenção

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

Pré-requisitos

Para executar os scripts de exemplo, 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 receber erros sobre a execução de scripts, certifique-se de que 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. Inicie sessão na sua subscrição que contém a sua conta do Azure Remote Rendering:

   1. Abra uma janela do PowerShell.
   2. Execute: Connect-AzAccount e siga as instruções apresentadas no ecrã.

   Nota

   Caso a sua organização tenha mais do que uma subscrição, poderá ter de especificar os argumentos SubscriptionId e Tenant. Encontre detalhes na documentação Connect-AzAccount.

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

Ficheiro de configuração

Junto aos .ps1 ficheiros, existe um arrconfig.json que precisa de 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>"
  }
}

Atenção

Certifique-se de que escapa corretamente às barras invertidas no caminho LocalAssetDirectoryPath ao utilizar barras invertidas duplas: "\\" e utilize barras "/" em todos os outros caminhos, como inputFolderPath e inputAssetPath.

Atenção

Os valores opcionais têm de ser preenchidos ou tem de remover completamente a chave e o valor. Por exemplo, se não utilizar o "outputAssetFileName" parâmetro , terá de eliminar toda a linha dentro arrconfig.jsonde .

accountSettings

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

renderingSessionSettings

Esta estrutura tem de ser preenchida se quiser executar RenderingSession.ps1:

• vmSize: Seleciona o tamanho da máquina virtual. Selecione standard ou premium. Encerre as sessões de composição quando já não precisar delas.
• maxLeaseTime: A duração para a qual pretende alugar a VM. A VM é encerrada quando a concessão expirar. O tempo de concessão pode ser prolongado mais tarde (veja aqui).
• remoteRenderingDomain: A região onde reside a VM de composição remota.
  • Pode ser diferente de arrAccountDomain, mas ainda deve ser uma região da lista de regiões disponíveis

assetConversionSettings

Esta estrutura tem de ser preenchida se quiser executar Conversion.ps1.

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

Script: RenderingSession.ps1

Este script é utilizado para criar, consultar e parar a composição de sessões.

Importante

Certifique-se de que preencheu as secções accountSettings e renderingSessionSettings em arrconfig.json.

Criar uma sessão de composição

Utilização normal com um arrconfig.json totalmente preenchido:

.\RenderingSession.ps1

O script chama a API REST de gestão de sessões para criar uma VM de composição com as definições especificadas. Após o êxito, obtém o sessionId. Posteriormente, consulta as propriedades da sessão até que a sessão esteja pronta ou ocorreu um erro.

Para utilizar um ficheiro de configuração alternativo :

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

Pode substituir as definições individuais do ficheiro de configuração:

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

Para iniciar apenas uma sessão sem consulta, pode utilizar:

.\RenderingSession.ps1 -CreateSession

O sessionId que o script obtém tem de ser transmitido para a maioria dos outros comandos de sessão.

Obter propriedades da sessão

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

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

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

Listar sessões ativas

.\RenderingSession.ps1 -GetSessions

Parar uma sessão

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

Alterar as propriedades da sessão

De momento, só suportamos a alteração do maxLeaseTime de uma sessão.

Nota

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

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

Script: Conversion.ps1

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

Importante

Certifique-se de que preencheu as secções accountSettings e assetConversionSettings e a opção remoteRenderingDomain na composiçãoSessionSettings em arrconfig.json.

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

• Conta de armazenamento associada à Conta de Remote Rendering do Azure
• Fornecer acesso ao armazenamento através de Assinaturas de Acesso Partilhado (SAS)

Conta de armazenamento associada

Depois de preencher completamente arrconfig.json e associar uma conta de armazenamento, pode utilizar o seguinte comando. A ligação da conta de armazenamento está descrita em Criar uma Conta.

A utilização de uma conta de armazenamento ligada é a forma preferencial de utilizar o serviço de conversão, uma vez que não é necessário gerar Assinaturas de Acesso Partilhado.

.\Conversion.ps1

1. Carregue todos os ficheiros contidos no para o assetConversionSettings.modelLocation contentor de blobs de entrada no .inputFolderPath
2. Chamar a API REST de conversão de modelos para iniciar a conversão do modelo
3. Consulte o estado de conversão até que a conversão tenha sido concluída com êxito ou falhe.
4. Detalhes de saída da localização do ficheiro convertido (conta de armazenamento, contentor de saída, caminho do ficheiro no contentor).

Acesso ao armazenamento através de Assinaturas de Acesso Partilhado

.\Conversion.ps1 -UseContainerSas

Isto irá:

1. Carregue o ficheiro local do assetConversionSettings.localAssetDirectoryPath para o contentor de blobs de entrada.
2. Gere um URI de SAS para o contentor de entrada.
3. Gere um URI de SAS para o contentor de saída.
4. Chame a API REST de conversão de modelos para iniciar a conversão do modelo.
5. Consulte o estado de conversão até que a conversão tenha sido concluída com êxito ou falhe.
6. Detalhes de saída da localização do ficheiro convertido (conta de armazenamento, contentor de saída, caminho do ficheiro no contentor).
7. Produza um URI de SAS para o modelo convertido no contentor de blobs de saída.

Opções adicionais da linha de comandos

Para utilizar um ficheiro de configuração alternativo :

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

Para iniciar apenas a conversão de modelos sem consulta, pode utilizar:

.\Conversion.ps1 -ConvertAsset

Pode substituir as definições individuais do ficheiro de configuração com os seguintes parâmetros da linha de comandos:

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

Por exemplo, pode combinar as opções especificadas como esta:

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

Executar as fases de conversão individuais

Se quiser executar passos individuais do processo, pode utilizar:

Carregue apenas dados do LocalAssetDirectoryPath especificado.

.\Conversion.ps1 -Upload

Inicie apenas o processo de conversão de um modelo já carregado para o armazenamento de blobs (não execute Carregar, não consulte o estado de conversão) O script devolve um conversionId.

.\Conversion.ps1 -ConvertAsset

Além disso, pode obter o estado de conversão desta conversão com:

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

Utilize -Poll para aguardar até que a conversão seja concluída ou ocorreu um erro.

Passos seguintes

• Início Rápido: Compor um modelo com o Unity
• Início Rápido: Converter um modelo para composição
• Conversão de modelos