Scripts de PowerShell de ejemplo

  • Artículo

Azure Remote Rendering proporciona las dos API REST siguientes:

El repositorio de ejemplos de ARR contiene scripts de ejemplo en la carpeta Scripts para interactuar con las API REST del servicio. En este artículo se describe su uso.

Sugerencia

También hay una herramienta basada en la interfaz de usuario llamada ARRT para interactuar con el servicio, que es una alternativa práctica al uso de scripts. ARRT

Precaución

Llamar a las funciones de la API REST con demasiada frecuencia hará que el servidor se limite y devuelva el error finalmente. El identificador del código de error HTTP en este caso es 429 ("demasiadas solicitudes"). Como regla general, debería haber un retraso de entre 5 y 10 segundos entre las llamadas subsiguientes.

Requisitos previos

Para ejecutar los scripts de ejemplo, necesita una configuración funcional de Azure PowerShell.

  1. Instale Azure PowerShell:

    1. Abra una ventana de PowerShell con derechos de administrador.
    2. Ejecute Install-Module -Name Az -AllowClobber.

  2. Si recibe errores en la ejecución de scripts, asegúrese de que la directiva de ejecución está establecida correctamente:

    1. Abra una ventana de PowerShell con derechos de administrador.
    2. Ejecute Set-ExecutionPolicy -ExecutionPolicy Unrestricted.

  3. Prepare una cuenta de Azure Storage

  4. Inicie sesión en la suscripción que contiene la cuenta de Azure Remote Rendering:

    1. Abra una ventana de PowerShell.
    2. Ejecute: Connect-AzAccount y siga las instrucciones que aparecen en pantalla.

    Nota

    Si la organización tiene más de una suscripción, puede que tenga que especificar los argumentos de SubscriptionId y Tenant. Busque los detalles en la documentación de Connect-AzAccount.

  5. Descargue la carpeta Scripts desde el repositorio de GitHub de Azure Remote Rendering.

Archivo de configuración

Junto a los archivos .ps1 hay un arrconfig.json que tiene que rellenar:

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

Precaución

Asegúrese de realizar correctamente el escape de las barras diagonales inversas en la ruta de acceso LocalAssetDirectoryPath mediante el uso de barras diagonales inversas dobles: "\\" y use barras diagonales "/" en todas las demás rutas de acceso como inputFolderPath y inputAssetPath.

Precaución

Se deben rellenar los valores opcionales o deberá quitar la clave y el valor por completo. Por ejemplo, si no usa el parámetro "outputAssetFileName", debe eliminar toda la línea que hay dentro de arrconfig.json.

accountSettings

Para arrAccountId y arrAccountKey, consulte Creación de una cuenta de Azure Remote Rendering. El valor de arrAccountDomain debe ser una región de la lista de regiones disponibles.

renderingSessionSettings

Si quiere ejecutar RenderingSession.ps1, se debe rellenar esta estructura:

  • vmSize: Selecciona el tamaño de la máquina virtual. Seleccione, estándar o premium. Cierre las sesiones de representación cuando ya no las necesite.
  • maxLeaseTime: La duración del tiempo de la concesión de la máquina virtual que desea realizar. La máquina virtual se apaga cuando expira la concesión. El tiempo de la concesión se puede ampliar más tarde (obtenga más información aquí).
  • remoteRenderingDomain: región en la que reside la máquina virtual de representación remota.

assetConversionSettings

Si desea ejecutar Conversion.ps1 tiene que rellenar esta estructura.

Para más información, consulte Preparación de una cuenta de Azure Storage.

Script: RenderingSession.ps1

Este script se usa para crear, consultar y detener sesiones de representación.

Importante

Asegúrese de que ha rellenado las secciones accountSettings y renderingSessionSettings en arrconfig.json.

Creación de una sesión de representación

Uso normal con un arrconfig.json totalmente rellenado:

.\RenderingSession.ps1

El script llama a la API REST de administración de sesión para poner en marcha una máquina virtual de representación con los valores especificados. Si se ejecuta correctamente, recupera el valor de sessionId. Después, sondea las propiedades de la sesión hasta que esta esté preparada o se produzca un error.

Para usar un archivo de configuración alternativo:

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

Puede invalidar valores individuales del archivo de configuración:

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

Si desea solamente iniciar una sesión sin sondeo, puede usar:

.\RenderingSession.ps1 -CreateSession

El sessionId que recupera el script tiene que pasarse a la mayoría de los demás comandos de sesión.

Recuperación de las propiedades de sesión

Para obtener las propiedades de una sesión, ejecute:

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

Use -Poll para esperar hasta que la sesión esté lista o se produzca un error.

Enumeración de sesiones activas

.\RenderingSession.ps1 -GetSessions

Detención de una sesión

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

Cambio de las propiedades de una sesión

En este momento, solo se admite el cambio de maxLeaseTime de una sesión.

Nota

El tiempo de la concesión siempre se cuenta desde el momento en que se creó inicialmente la máquina virtual de sesión. Por lo tanto, para prorrogar el tiempo de concesión de sesión otra hora más, aumente maxLeaseTime en una hora.

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

Script: Conversion.ps1

Este script se usa para convertir los modelos de entrada en el formato en tiempo de ejecución específico de Azure Remote Rendering.

Importante

Asegúrese de que ha rellenado las secciones accountSettings y assetConversionSettings y la opción remoteRenderingDomain de renderingSessionSettings en arrconfig.json.

El script muestra las dos opciones para usar las cuentas de almacenamiento con el servicio:

  • Cuenta de almacenamiento vinculada con la cuenta de Azure Remote Rendering
  • Proporcionar acceso al almacenamiento mediante firmas de acceso compartido (SAS)

Cuenta de almacenamiento vinculada

Una vez que haya rellenado por completo arrconfig.json y vinculado una cuenta de almacenamiento, puede usar el siguiente comando. La vinculación de la cuenta de almacenamiento se describe en Creación de una cuenta.

La manera preferida de utilizar el servicio de conversión es usando una cuenta de almacenamiento vinculada, ya que de esta forma no es necesario generar firmas de acceso compartido.

.\Conversion.ps1
  1. Cargue todos los archivos contenidos en assetConversionSettings.modelLocation en el contenedor de blobs de entrada que se encuentra en el elemento inputFolderPath proporcionado.
  2. Llame a la API REST de conversión de modelos para iniciar la conversión de modelos
  3. Sondee el estado de conversión hasta que esta se realice correctamente o se produzca un error.
  4. Genere los detalles de la ubicación del archivo convertido (cuenta de almacenamiento, contenedor de salida, ruta de acceso del archivo en el contenedor).

Acceso al almacenamiento mediante firmas de acceso compartido

.\Conversion.ps1 -UseContainerSas

De este modo:

  1. Cargue el archivo local desde assetConversionSettings.localAssetDirectoryPath en el contenedor de blobs de entrada.
  2. Genere un URI de SAS para el contenedor de entrada.
  3. Genere un URI de SAS para el contenedor de salida.
  4. Llame a la API REST de conversión de modelos para iniciar la conversión de modelos.
  5. Sondee el estado de conversión hasta que esta se realice correctamente o se produzca un error.
  6. Genere los detalles de la ubicación del archivo convertido (cuenta de almacenamiento, contenedor de salida, ruta de acceso del archivo en el contenedor).
  7. Genere un URI de SAS para el modelo convertido en el contenedor de blobs de salida.

Opciones adicionales de la línea de comandos

Para usar un archivo de configuración alternativo:

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

Si desea solamente iniciar la conversión del modelo sin sondeo, puede usar:

.\Conversion.ps1 -ConvertAsset

Puede invalidar valores individuales del archivo de configuración mediante los siguientes modificadores de línea de comandos:

  • Id: ConversionId usado con GetConversionStatus
  • ArrAccountId: arrAccountId de accountSettings
  • ArrAccountKey: reemplazo de arrAccountKey de accountSettings
  • ArrAccountDomain: reemplazo de arrAccountDomain de accountSettings
  • RemoteRenderingDomain: reemplazo de remoteRenderingDomain de renderingSessionSettings
  • ResourceGroup: reemplazo de resourceGroup de assetConversionSettings
  • StorageAccountName: reemplazo de storageAccountName de assetConversionSettings
  • BlobInputContainerName: reemplazo de blobInputContainer de assetConversionSettings
  • LocalAssetDirectoryPath: reemplazo de localAssetDirectoryPath de assetConversionSettings
  • InputAssetPath: reemplazo de inputAssetPath de assetConversionSettings
  • BlobOutputContainerName: reemplazo de blobOutputContainerName de assetConversionSettings
  • OutputFolderPath: reemplazo de outputFolderPath de assetConversionSettings
  • OutputAssetFileName: reemplazo de outputAssetFileName de assetConversionSettings

Por ejemplo, puede combinar las opciones proporcionadas como se puede ver a continuación:

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

Ejecución de las fases de conversión individuales

Si desea ejecutar pasos individuales del proceso, puede usar:

Cargue solo los datos del elemento LocalAssetDirectoryPath dado.

.\Conversion.ps1 -Upload

Inicie solo el proceso de conversión de un modelo ya cargado en el almacenamiento de blobs (no ejecute la carga, no sondee el estado de conversión). El script devuelve un valor de conversionId.

.\Conversion.ps1 -ConvertAsset

Y puede recuperar el estado de conversión de esta conversión mediante:

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

Use -Poll para esperar hasta que se realice la conversión o se produzca un error.

Pasos siguientes