Biblioteca cliente de Azure Remote Rendering para Python: versión 1.0.0b2

Azure Remote Rendering (ARR) es un servicio que permite representar contenido 3D interactivo de alta calidad en la nube y transmitirlo en tiempo real a los dispositivos, como HoloLens 2.

Este SDK ofrece funcionalidad para convertir recursos al formato esperado por el tiempo de ejecución y también para administrar la duración de las sesiones de representación remota.

Este SDK admite la versión "2021-01-01" de la API REST de Remote Rendering.

NOTA: Una vez que se ejecuta una sesión, una aplicación cliente se conectará a ella mediante uno de los "SDK en tiempo de ejecución". Estos SDK están diseñados para admitir mejor las necesidades de una aplicación interactiva que realiza la representación en 3d. Están disponibles en (.net o (C++).

Documentación del producto

Declinación de responsabilidades

Los paquetes de Python del SDK de Azure para Python 2.7 finalizaron el 01 de enero de 2022. Para más información y preguntas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691.

Introducción

Requisitos previos

Necesitará una suscripción de Azure y una cuenta de Azure Remote Rendering para usar este paquete.

Para seguir este tutorial, se recomienda encarecidamente vincular la cuenta de almacenamiento con su cuenta de ARR.

Instalar el paquete

Instale la biblioteca cliente de Azure Remote Rendering para Python con pip:

pip install --pre azure-mixedreality-remoterendering

Creación y autenticación del cliente

La construcción de un cliente de representación remota requiere una cuenta autenticada y un punto de conexión de representación remota. Para una cuenta creada en la región eastus, el dominio de cuenta tendrá el formato "eastus.mixedreality.azure.com". Hay varias formas diferentes de autenticación:

• Autenticación de clave de cuenta
  • Las claves de cuenta le permiten empezar a trabajar rápidamente con Azure Remote Rendering. Sin embargo, antes de implementar la aplicación en la producción, es recomendable actualizarla para que pueda usar la autenticación de Azure AD.
• Autenticación de tokens de Azure Active Directory (AD)
  • Si va a compilar una aplicación empresarial y su empresa usa Azure AD como sistema de identidades, puede usar en la aplicación la autenticación de Azure AD basada en el usuario. A continuación, conceda acceso a las cuentas de Azure Remote Rendering mediante los grupos de seguridad de Azure AD existentes. Igualmente, también puede conceder acceso directamente a los usuarios de la organización.
  • En caso contrario, es recomendable que obtenga los tokens de Azure AD de un servicio web que sea compatible con la aplicación. Se recomienda este método para aplicaciones de producción, ya que permite evitar la inserción de las credenciales para el acceso en la aplicación cliente.

Consulte aquí para obtener instrucciones e información detalladas.

En todos los ejemplos siguientes, el cliente se construye con un endpoint parámetro . Los puntos de conexión disponibles corresponden a regiones y la elección del punto de conexión determina la región en la que el servicio realiza su trabajo. Un ejemplo es https://remoterendering.eastus2.mixedreality.azure.com.

Puede encontrar una lista completa de los puntos de conexión en las regiones admitidas en la lista de regiones de Azure Remote Rendering.

NOTA: Para convertir recursos, es preferible elegir una región cercana al almacenamiento que contiene los recursos.

NOTA: Para la representación, se recomienda encarecidamente elegir la región más cercana a los dispositivos mediante el servicio. El tiempo necesario para comunicarse con el servidor afecta a la calidad de la experiencia.

Autenticación con autenticación de clave de cuenta

Use el AzureKeyCredential objeto para usar un identificador de cuenta y una clave de cuenta para autenticarse:

from azure.core.credentials import AzureKeyCredential
from azure.mixedreality.remoterendering import RemoteRenderingClient

account_id = "<ACCOUNT_ID>"
account_domain = "<ACCOUNT_DOMAIN>"
account_key = "<ACCOUNT_KEY>"
arr_endpoint = "<ARR_ENDPOINT>"

key_credential = AzureKeyCredential(account_key)
client = RemoteRenderingClient(
    endpoint=arr_endpoint,
    account_id=account_id,
    account_domain=account_domain,
    credential=key_credential
)

Autenticación con un token de acceso estático

Puede pasar un token de acceso de Mixed Reality como un AccessToken objeto recuperado previamente del servicio STS de Mixed Reality que se usará con una biblioteca cliente de Mixed Reality:

from azure.mixedreality.authentication import MixedRealityStsClient
from azure.mixedreality.remoterendering import RemoteRenderingClient
account_id = "<ACCOUNT_ID>"
account_domain = "<ACCOUNT_DOMAIN>"
account_key = "<ACCOUNT_KEY>"

key_credential = AzureKeyCredential(account_key)

client = MixedRealityStsClient(account_id, account_domain, key_credential)

token = client.get_token()

client = RemoteRenderingClient(
    endpoint=arr_endpoint,
    account_id=account_id,
    account_domain=account_domain,
    credential=token,
)

Autenticación con una credencial de Azure Active Directory

La autenticación de clave de cuenta se usa en la mayoría de los ejemplos, pero también puede autenticarse con Azure Active Directory mediante la biblioteca de identidades de Azure. Este es el método recomendado para aplicaciones de producción. Para usar el proveedor [DefaultAzureCredential][defaultazurecredential] que se muestra a continuación, u otros proveedores de credenciales proporcionados con el SDK de Azure, instale el @azure/identity paquete:

También deberá [registrar una nueva aplicación de AAD][register_aad_app] y conceder acceso al recurso de Mixed Reality asignando el rol adecuado para el servicio de Mixed Reality a la entidad de servicio.

from azure.identity import DefaultAzureCredential
from azure.mixedreality.remoterendering import RemoteRenderingClient

account_id = "<ACCOUNT_ID>"
account_domain = "<ACCOUNT_DOMAIN>"
default_credential = DefaultAzureCredential()

client = RemoteRenderingClient(
    endpoint=arr_endpoint,
    account_id=account_id,
    account_domain=account_domain,
    credential=default_credential
)

Conceptos clave

RemoteRenderingClient

RemoteRenderingClient es la biblioteca cliente que se usa para tener acceso a RemoteRenderingService. Proporciona métodos para crear y administrar conversiones de recursos y sesiones de representación.

Operaciones de Long-Running

Las operaciones de larga duración son operaciones que constan de una solicitud inicial enviada al servicio para iniciar una operación, seguidas de sondear el servicio a intervalos para determinar si la operación se ha completado o no, y si se ha realizado correctamente, para obtener el resultado.

Los métodos que convierten recursos o las sesiones de representación de número se modelan como operaciones de larga duración. El cliente expone un begin_<method-name> método que devuelve un LROPoller o AsyncLROPoller. Los autores de llamadas deben esperar a que se complete la operación llamando a result() en el objeto de sondeo devuelto por el begin_<method-name> método . A continuación se proporcionan fragmentos de código de ejemplo para ilustrar el uso de operaciones de larga duración .

Ejemplos

• Conversión de un recurso
• Enumeración de conversiones
• Creación de una sesión
• Extender el tiempo de concesión de una sesión
• Enumerar sesiones
• Detención de una sesión

Conversión de un recurso

Se supone que se ha construido un RemoteRenderingClient como se describe en la sección Autenticar el cliente . En el fragmento de código siguiente se describe cómo solicitar que "box.fbx", que se encuentra en una ruta de acceso de "/input/box/box.fbx" del contenedor de blobs en el URI del contenedor de almacenamiento especificado, se convierte.

La conversión de un recurso puede tardar entre segundos y horas. Este código usa un sondeo de conversión existente y sondea periódicamente hasta que la conversión haya finalizado o fallado. El período de sondeo predeterminado es de 5 segundos. Tenga en cuenta que un sondeo de conversión se puede recuperar mediante el client.get_asset_conversion_poller mediante el identificador de una conversión existente y un cliente.

Una vez que el proceso de conversión finaliza la salida se escribe en el contenedor de salida especificado en una ruta de acceso de "/output/<conversion_id>/box.arrAsset". La ruta de acceso se puede recuperar del output.asset_uri de una conversión correcta.

    conversion_id = str(uuid.uuid4()) # A randomly generated uuid is a good choice for a conversion_id.

    input_settings = AssetConversionInputSettings(
        storage_container_uri="<STORAGE CONTAINER URI>",
        relative_input_asset_path="box.fbx",
        blob_prefix="input/box"
    )
    output_settings = AssetConversionOutputSettings(
        storage_container_uri="<STORAGE CONTAINER URI>",
        blob_prefix="output/"+conversion_id,
        output_asset_filename="convertedBox.arrAsset" #if no output_asset_filename <input asset filename>.arrAsset will be the name of the resulting converted asset
    )
    try:
        conversion_poller = client.begin_asset_conversion(
            conversion_id=conversion_id,
            input_settings=input_settings,
            output_settings=output_settings
        )

        print("Conversion with id:", conversion_id, "created. Waiting for completion.")
        conversion = conversion_poller.result()
        print("conversion output:", conversion.output.asset_uri)

    except Exception as e:
        print("Conversion failed", e)

Enumeración de conversiones

Puede obtener información sobre las conversiones mediante el list_asset_conversions método . Este método puede devolver conversiones que aún no se han iniciado, conversiones que se ejecutan y conversiones que han finalizado. En este ejemplo, se enumeran todas las conversiones y el identificador de impresión y el anuncio de creación, así como los URI del recurso de salida de conversiones correctas.

    print("conversions:")
    for c in client.list_asset_conversions():
        print(
            "\t conversion:  id:",
            c.id,
            "status:",
            c.status,
            "created on:",
            c.created_on.strftime("%m/%d/%Y, %H:%M:%S"),
        )
        if c.status == AssetConversionStatus.SUCCEEDED:
            print("\t\tconversion result URI:", c.output.asset_uri)

Creación de una sesión

Se supone que se ha construido un RemoteRenderingClient como se describe en la sección Autenticar el cliente . En el fragmento de código siguiente se describe cómo solicitar que se inicie una nueva sesión de representación.

    print("starting rendering session with id:", session_id)
    try:
        session_poller = client.begin_rendering_session(
            session_id=session_id, size=RenderingSessionSize.STANDARD, lease_time_minutes=20
        )
        print(
            "rendering session with id:",
            session_id,
            "created. Waiting for session to be ready.",
        )
        session = session_poller.result()
        print(
            "session with id:",
            session.id,
            "is ready. lease_time_minutes:",
            session.lease_time_minutes,
        )
    except Exception as e:
        print("Session startup failed", e)

Extender el tiempo de concesión de una sesión

Si una sesión se acerca a su tiempo máximo de concesión, pero quiere mantenerla activa, deberá realizar una llamada para aumentar su tiempo máximo de concesión. En este ejemplo se muestra cómo consultar las propiedades actuales y, a continuación, extender la concesión si expirará pronto.

NOTA: Los SDK en tiempo de ejecución también ofrecen esta funcionalidad y, en muchos escenarios típicos, los usaría para ampliar la concesión de sesión.

    session = client.get_rendering_session(session_id)
    if session.lease_time_minutes - session.elapsed_time_minutes < 2:
        session = client.update_rendering_session(
            session_id=session_id, lease_time_minutes=session.lease_time_minutes + 10
        )

Enumerar sesiones

Puede obtener información sobre las sesiones mediante el list_rendering_sessions método del cliente. Este método puede devolver sesiones que aún no se han iniciado y las sesiones que están listas.

    print("sessions:")
    rendering_sessions = client.list_rendering_sessions()
    for session in rendering_sessions:
        print(
            "\t session:  id:",
            session.id,
            "status:",
            session.status,
            "created on:",
            session.created_on.strftime("%m/%d/%Y, %H:%M:%S"),
        )

Detener una sesión

El código siguiente detendrá una sesión en ejecución con un identificador determinado. Puesto que las sesiones en ejecución incurren en costos continuos, se recomienda detener las sesiones que ya no son necesarias.

    client.stop_rendering_session(session_id)
    print("session with id:", session_id, "stopped")

Solución de problemas

Para obtener consejos generales de solución de problemas sobre Azure Remote Rendering, consulte la página Solución de problemas de la representación remota en docs.microsoft.com.

Los métodos de cliente y la espera de los resultados del sondeo producirán excepciones si se produjo un error en la solicitud.

Si el recurso de una conversión no es válido, el sondeo de conversión producirá una excepción con un error que contiene detalles. Una vez que el servicio de conversión puede procesar el archivo, se escribirá un <archivo assetName.result.json> en el contenedor de salida. Si el recurso de entrada no es válido, ese archivo contendrá una descripción más detallada del problema.

De forma similar, a veces cuando se solicita una sesión, la sesión termina en un estado de error. El sondeo producirá una excepción que contiene los detalles del error en este caso. Los errores de sesión suelen ser transitorios y la solicitud de una nueva sesión debe realizarse correctamente.

Registro

Esta biblioteca usa la biblioteca estándar [logging][python_logging] para el registro.

La información básica sobre las sesiones HTTP (direcciones URL, encabezados, etc.) se registra en el INFO nivel.

El registro de nivel detallado DEBUG , incluidos los cuerpos de solicitud/respuesta y los encabezados no aprobados , se puede habilitar en el cliente o por operación con el argumento de palabra logging_enable clave.

Consulte la documentación completa del registro del SDK con ejemplos aquí.

Configuración opcional

Los argumentos de palabra clave opcionales se pueden pasar en el nivel de cliente y por operación. En la documentación de referencia de azure-core se describen las configuraciones disponibles para reintentos, registro, protocolos de transporte, etc.

Excepciones

La biblioteca cliente de Remote Rendering generará excepciones definidas en Azure Core.

API asincrónicas

Esta biblioteca también incluye una API asincrónica completa compatible con Python 3.7 y versiones posteriores. Para usarlo, primero debe instalar un transporte asincrónico, como aiohttp. Los clientes asincrónicos se encuentran en el azure.mixedreality.remoterendering.aio espacio de nombres .

Pasos siguientes

• Lea la documentación del producto.
• Obtenga información sobre los SDK en tiempo de ejecución:
  • .NET: /dotnet/api/microsoft.azure.remoterendering
  • C++: /cpp/api/remote-rendering/

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Si desea contribuir a esta biblioteca, lea la guía de contribución para obtener más información sobre cómo compilar y probar el código.