Exemples de scripts PowerShell

Azure Remote Rendering fournit les deux API REST suivantes :

• L’API REST Conversion
• L’API REST Session

Le dépôt d’exemples ARR contient des exemples de scripts situés dans le dossier Scripts qui permettent d’interagir avec les API REST du service. Cet article décrit leur utilisation.

Conseil

Il existe également un outil basé sur l’interface utilisateur appelé ARRT, qui permet d’interagir avec le service, ce qui constitue une alternative pratique à l’utilisation de scripts.

Attention

Une fréquence trop élevée d’appels aux fonctions de l’API REST provoque la limitation du serveur, qui retourne une défaillance. Dans ce cas, l’ID de code d’échec HTTP est 429 (« trop de demandes »). En règle générale, il doit y avoir un délai de 5 à 10 secondes entre les appels successifs.

Prérequis

Pour exécuter les exemples de scripts, vous avez besoin d’une configuration fonctionnelle d’Azure PowerShell.

1. Installez Azure PowerShell :

   1. Ouvrez une fenêtre PowerShell avec des droits d’administrateur.
   2. Exécutez l’instruction suivante : Install-Module -Name Az -AllowClobber

2. Si vous recevez des erreurs concernant l’exécution des scripts, vérifiez que votre stratégie d’exécution est correctement configurée :

   1. Ouvrez une fenêtre PowerShell avec des droits d’administrateur.
   2. Exécutez l’instruction suivante : Set-ExecutionPolicy -ExecutionPolicy Unrestricted

3. Préparer un compte de stockage Azure

4. Connectez-vous à l’abonnement qui contient votre compte Azure Remote Rendering :

   1. Ouvrez une fenêtre PowerShell.
   2. Exécutez Connect-AzAccount, puis suivez les instructions à l’écran.

   Notes

   Si votre organisation a plusieurs abonnements, vous devrez peut-être spécifier les arguments SubscriptionId et Tenant. Pour plus d’informations, consultez la documentation sur Connect-AzAccount.

5. Téléchargez le dossier Scripts à partir du dépôt GitHub Azure Remote Rendering.

Fichier de configuration

À côté des fichiers .ps1, vous devez renseigner 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>"
  }
}

Attention

Veillez à placer correctement les barres obliques inverses dans le chemin LocalAssetDirectoryPath en utilisant des barres obliques inverses doubles (« \\ »). Vous pouvez utiliser des barres obliques (« / ») dans tous les autres chemins tels que inputFolderPath et inputAssetPath.

Attention

Les valeurs facultatives doivent être renseignées ; sinon, vous devez supprimer entièrement la clé et la valeur. Par exemple, si vous n’utilisez pas le paramètre "outputAssetFileName", supprimez toute la ligne dans arrconfig.json.

accountSettings

Pour arrAccountId et arrAccountKey, consultez Créer un compte Azure Remote Rendering. Le arrAccountDomain doit être une région de la liste des régions disponibles.

renderingSessionSettings

Cette structure doit être remplie si vous souhaitez exécuter RenderingSession.ps1 :

• vmSize : sélectionnez la taille de la machine virtuelle. Sélectionnez standard ou premium. Arrêtez les sessions de rendu lorsque vous n’en avez plus besoin.
• maxLeaseTime : durée souhaitée du bail pour la machine virtuelle. La machine virtuelle s’arrête à l’expiration du bail. La durée du bail peut être prolongée (voir ici).
• remoteRenderingDomain : La région dans laquelle se trouve la machine virtuelle de rendu à distance.
  • Peut différer de arrAccountDomain, mais doit toujours se trouver dans une région de la liste des régions disponibles

assetConversionSettings

Cette structure doit être remplie si vous souhaitez exécuter Conversion.ps1.

Pour plus d’informations, consultez Préparer un compte de stockage Azure.

Script : RenderingSession.ps1

Ce script est utilisé pour créer, interroger et arrêter les sessions de rendu.

Important

Vérifiez que vous avez rempli les sections accountSettings et renderingSessionSettings du fichier arrconfig.json.

Créer une session de rendu

Utilisation normale avec un fichier arrconfig.json entièrement rempli :

.\RenderingSession.ps1

Le script appelle l’API REST de gestion des sessions pour lancer une machine virtuelle de rendu avec les paramètres spécifiés. Si l’opération réussit, il récupère le sessionId. Il interroge par la suite les propriétés de la session jusqu’à ce que la session soit prête ou qu’une erreur survienne.

Pour utiliser un autre fichier de configuration :

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

Vous pouvez remplacer certains paramètres dans le fichier de configuration :

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

Si vous souhaitez démarrer une session sans l’interroger, vous pouvez utiliser ceci :

.\RenderingSession.ps1 -CreateSession

Le sessionId que le script récupère doit être passé à la plupart des autres commandes de session.

Récupérer les propriétés de session

Pour obtenir les propriétés d’une session, exécutez ceci :

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

Utilisez -Poll pour attendre que la session soit prête ou qu’une erreur se produise.

Lister les sessions actives

.\RenderingSession.ps1 -GetSessions

Arrêter une session

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

Modifier les propriétés de session

Pour le moment, seule la modification du maxLeaseTime d’une session est prise en charge.

Notes

La durée du bail démarre toujours à partir de l’heure de création de la machine virtuelle de la session. Par conséquent, pour prolonger d’une heure le bail de la session, augmentez maxLeaseTime d’une heure.

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

Script : Conversion.ps1

Ce script est utilisé pour convertir les modèles d’entrée au format d’exécution propre à Azure Remote Rendering.

Important

Assurez-vous d’avoir rempli les sections accountSettings et assetConversionSettings, tout comme l’option remoteRenderingDomain dans le renderingSessionSettings du fichier arrconfig.json.

Le script montre les deux utilisations possibles des comptes de stockage avec le service :

• Associer le compte de stockage au compte Azure Remote Rendering
• Fournir l’accès au stockage via des signatures d’accès partagé (SAS)

Compte de stockage lié

Une fois que vous avez entièrement rempli le fichier arrconfig.json et que vous l’avez lié à un compte de stockage, vous pouvez utiliser la commande suivante. La procédure à suivre pour lier votre compte de stockage est décrite dans Créer un compte.

L’utilisation d’un compte de stockage lié est la meilleure façon d’utiliser le service de conversion, puisqu’il n’est pas nécessaire de générer des signatures d’accès partagé.

.\Conversion.ps1

1. Chargez tous les fichiers dans le assetConversionSettings.modelLocation vers le conteneur d’objets blob d’entrée sous le inputFolderPath donné.
2. Appelez l’API REST de conversion des modèles pour lancer la conversion du modèle
3. Interrogez l’état de la conversion jusqu’à la réussite ou l’échec de celle-ci.
4. Affichez les informations concernant l’emplacement du fichier converti (compte de stockage, conteneur de sortie, chemin du fichier dans le conteneur).

Accéder au stockage via des signatures d’accès partagé

.\Conversion.ps1 -UseContainerSas

Avec cette opération, vous pouvez :

1. Charger le fichier local à partir de assetConversionSettings.localAssetDirectoryPath dans le conteneur d’objets blob d’entrée.
2. Générer un URI SAS pour le conteneur d’entrée.
3. Générer un URI SAS pour le conteneur de sortie.
4. Appeler l’API REST de conversion des modèles pour lancer la conversion du modèle.
5. Interroger l’état de la conversion jusqu’à la réussite ou l’échec de celle-ci.
6. Afficher les informations concernant l’emplacement du fichier converti (compte de stockage, conteneur de sortie, chemin du fichier dans le conteneur).
7. Afficher l’URI SAS du modèle converti dans le conteneur d’objets blob de sortie.

Options supplémentaires de la ligne de commande

Pour utiliser un autre fichier de configuration :

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

Si vous souhaitez démarrer une conversion de modèle sans l’interroger, vous pouvez utiliser ceci :

.\Conversion.ps1 -ConvertAsset

Vous pouvez remplacer certains paramètres du fichier de configuration à l’aide des commutateurs de ligne de commande suivants :

• Id : ConversionId utilisé avec GetConversionStatus
• ArrAccountId : arrAccountId de accountSettings
• ArrAccountKey : remplacement pour l’arrAccountKey de accountSettings
• ArrAccountDomain : substituer pour arrAccountDomain de accountSettings
• RemoteRenderingDomain : substituer pour remoteRenderingDomain de renderingSessionSettings
• ResourceGroup : remplacement pour le resourceGroup de assetConversionSettings
• StorageAccountName : remplacement pour le storageAccountName de assetConversionSettings
• BlobInputContainerName : remplacement pour le blobInputContainer de assetConversionSettings
• LocalAssetDirectoryPath : remplacement pour le localAssetDirectoryPath de assetConversionSettings
• InputAssetPath : remplacement pour l’inputAssetPath de assetConversionSettings
• BlobOutputContainerName : remplacement pour le blobOutputContainerName de assetConversionSettings
• OutputFolderPath : remplacement pour le outputFolderPath de assetConversionSettings
• OutputAssetFileName : remplacement pour le outputAssetFileName de assetConversionSettings

Vous pouvez par exemple combiner les options présentées de la façon suivante :

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

Exécuter les étapes de conversion séparément

Si vous souhaitez exécuter uniquement certaines étapes du processus, vous pouvez procéder de la façon suivante :

Chargez uniquement les données à partir du LocalAssetDirectoryPath donné.

.\Conversion.ps1 -Upload

Démarrez uniquement le processus de conversion d’un modèle déjà chargé dans le stockage de Blob (sans exécuter de chargement ni interroger l’état de la conversion). Le script retourne un conversionId.

.\Conversion.ps1 -ConvertAsset

Vous pouvez récupérer l’état de la conversion à l’aide de ceci :

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

Utilisez -Poll pour attendre que la conversion soit terminée ou qu’une erreur se produise.

Étapes suivantes

• Démarrage rapide : Afficher un modèle avec Unity
• Démarrage rapide : Convertir un modèle pour le rendu
• Conversion de modèle