Bibliothèque cliente Azure Remote Rendering pour Python - version 1.0.0b2

Azure Remote Rendering (ARR) est un service qui vous permet d’effectuer le rendu de contenu 3D interactif de haute qualité dans le cloud et de le diffuser en temps réel sur des appareils comme HoloLens 2.

Ce KIT de développement logiciel (SDK) offre des fonctionnalités permettant de convertir des ressources au format attendu par le runtime, ainsi que de gérer la durée de vie des sessions de rendu à distance.

Ce KIT de développement logiciel (SDK) prend en charge la version « 2021-01-01 » de l’API REST Remote Rendering.

REMARQUE : Une fois qu’une session est en cours d’exécution, une application cliente s’y connecte à l’aide de l’un des « SDK runtime ». Ces SDK sont conçus pour prendre en charge au mieux les besoins d’une application interactive effectuant un rendu 3D. Ils sont disponibles dans (.net ou (C++).

Documentation du produit

Clause d’exclusion de responsabilité

La prise en charge des packages Python du SDK Azure pour Python 2.7 a pris fin le 1er janvier 2022. Pour obtenir plus d’informations et poser des questions, reportez-vous à https://github.com/Azure/azure-sdk-for-python/issues/20691

Prise en main

Prérequis

Vous aurez besoin d’un abonnement Azure et d’un compte Azure Remote Rendering pour utiliser ce package.

Pour suivre ce tutoriel, il est vivement recommandé de lier votre compte de stockage à votre compte ARR.

Installer le package

Installez la bibliothèque cliente Azure Remote Rendering pour Python avec pip :

pip install --pre azure-mixedreality-remoterendering

Créer et authentifier le client

La construction d’un client de rendu à distance nécessite un compte authentifié et un point de terminaison de rendu distant. Pour un compte créé dans la région eastus, le domaine du compte aura la forme « eastus.mixedreality.azure.com ». Il existe différentes formes d’authentification :

• Authentification par clé de compte
  • Les clés de compte vous permettent de commencer rapidement à utiliser Azure Remote Rendering. Mais avant de déployer votre application en production, nous vous recommandons de mettre à jour votre application pour utiliser l’authentification Azure AD.
• Authentification par jeton Azure Active Directory (AD)
  • Si vous créez une application d’entreprise et que votre entreprise utilise Azure AD comme système d’identité, vous pouvez utiliser l’authentification Azure AD basée sur l’utilisateur dans votre application. Vous accordez ensuite l’accès à vos comptes Azure Remote Rendering à l’aide de vos groupes de sécurité Azure AD existants. Vous pouvez également accorder l’accès directement aux utilisateurs de votre organisation.
  • Sinon, nous vous recommandons d’obtenir des jetons Azure AD à partir d’un service web prenant en charge votre application. Nous recommandons cette méthode pour les applications de production, car elle vous permet d’éviter d’incorporer les informations d’identification pour l’accès dans votre application cliente.

Consultez ici pour obtenir des instructions et des informations détaillées.

Dans tous les exemples suivants, le client est construit avec un endpoint paramètre. Les points de terminaison disponibles correspondent à des régions, et le choix du point de terminaison détermine la région dans laquelle le service effectue son travail. par exemple https://remoterendering.eastus2.mixedreality.azure.com.

Vous trouverez la liste complète des points de terminaison dans les régions prises en charge dans la liste des régions Azure Remote Rendering.

REMARQUE : Pour la conversion des ressources, il est préférable de choisir une région proche du stockage contenant les ressources.

REMARQUE : Pour le rendu, il est vivement recommandé de choisir la région la plus proche des appareils à l’aide du service. Le temps nécessaire pour communiquer avec le serveur a un impact sur la qualité de l’expérience.

Authentification avec l’authentification par clé de compte

Utilisez l’objet AzureKeyCredential pour utiliser un identificateur de compte et une clé de compte pour vous authentifier :

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
)

Authentification avec un jeton d’accès statique

Vous pouvez passer un jeton d’accès Mixed Reality en tant que AccessToken précédemment récupéré à partir du service STS Mixed Reality à utiliser avec une bibliothèque cliente 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,
)

Authentification avec des informations d’identification Azure Active Directory

L’authentification par clé de compte est utilisée dans la plupart des exemples, mais vous pouvez également vous authentifier auprès d’Azure Active Directory à l’aide de la bibliothèque Azure Identity. Il s’agit de la méthode recommandée pour les applications de production. Pour utiliser le fournisseur [DefaultAzureCredential][defaultazurecredential] indiqué ci-dessous, ou d’autres fournisseurs d’informations d’identification fournis avec le Kit de développement logiciel (SDK) Azure, installez le @azure/identity package :

Vous devez également [inscrire une nouvelle application AAD][register_aad_app] et accorder l’accès à votre ressource Mixed Reality en affectant le rôle approprié pour votre service Mixed Reality à votre principal de service.

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
)

Concepts clés

RemoteRenderingClient

RemoteRenderingClient est la bibliothèque cliente utilisée pour accéder au RemoteRenderingService. Il fournit des méthodes pour créer et gérer les conversions de ressources et les sessions de rendu.

opérations Long-Running

Les opérations de longue durée sont des opérations qui se composent d’une demande initiale envoyée au service pour démarrer une opération, suivie d’un interrogation du service à intervalles réguliers pour déterminer si l’opération s’est terminée ou échouée, et si elle a réussi, pour obtenir le résultat.

Les méthodes qui convertissent des ressources ou des sessions de rendu spin up sont modélisées comme des opérations de longue durée. Le client expose une begin_<method-name> méthode qui retourne un LROPoller ou un AsyncLROPoller. Les appelants doivent attendre que l’opération se termine en appelant result() sur l’objet poller retourné par la begin_<method-name> méthode. Des exemples d’extraits de code sont fournis pour illustrer l’utilisation d’opérations de longue durée ci-dessous.

Exemples

• Convertir une ressource
• Répertorier les conversions
• Créer une session
• Prolonger la durée du bail d’une session
• Répertorier les sessions
• Arrêter une session

Convertir une ressource

Nous partons du principe qu’un RemoteRenderingClient a été construit comme décrit dans la section Authentifier le client . L’extrait de code suivant explique comment demander que « box.fbx », qui se trouve à un chemin d’accès « /input/box/box.fbx » du conteneur d’objets blob à l’URI de conteneur de stockage donné, soit converti.

La conversion d’une ressource peut prendre de quelques secondes à des heures. Ce code utilise un pollueur de conversion existant et interroge régulièrement jusqu’à ce que la conversion soit terminée ou échouée. La période d’interrogation par défaut est de 5 secondes. Notez qu’un polleur de conversion peut être récupéré à l’aide de l’client.get_asset_conversion_poller à l’aide de l’ID d’une conversion existante et d’un client.

Une fois le processus de conversion terminé, la sortie est écrite dans le conteneur de sortie spécifié sous un chemin d’accès « /output/<conversion_id>/box.arrAsset ». Le chemin d’accès peut être récupéré à partir de la output.asset_uri d’une conversion réussie.

    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)

Répertorier les conversions

Vous pouvez obtenir des informations sur vos conversions à l’aide de la list_asset_conversions méthode . Cette méthode peut retourner des conversions qui n’ont pas encore démarré, des conversions qui sont en cours d’exécution et des conversions terminées. Dans cet exemple, nous listons toutes les conversions, l’ID d’impression et l’annonce de création, ainsi que les URI de ressource de sortie des conversions réussies.

    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)

Créer une session

Nous partons du principe qu’un RemoteRenderingClient a été construit comme décrit dans la section Authentifier le client . L’extrait de code suivant explique comment demander qu’une nouvelle session de rendu soit démarrée.

    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)

Prolonger la durée du bail d’une session

Si une session approche de sa durée maximale de bail, mais que vous souhaitez la maintenir en vie, vous devez passer un appel pour augmenter sa durée maximale de bail. Cet exemple montre comment interroger les propriétés actuelles, puis prolonger le bail s’il expire bientôt.

REMARQUE : Les SDK runtime offrent également cette fonctionnalité et, dans de nombreux scénarios classiques, vous les utiliserez pour étendre le bail de session.

    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
        )

Répertorier les sessions

Vous pouvez obtenir des informations sur vos sessions à l’aide de la list_rendering_sessions méthode du client. Cette méthode peut retourner des sessions qui n’ont pas encore démarré et des sessions qui sont prêtes.

    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"),
        )

Arrêter une session

Le code suivant arrête une session en cours d’exécution avec un ID donné. Étant donné que l’exécution de sessions entraîne des coûts permanents, il est recommandé d’arrêter les sessions qui ne sont plus nécessaires.

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

Dépannage

Pour obtenir des conseils généraux de résolution des problèmes concernant Azure Remote Rendering, consultez la page Résoudre les problèmes de rendu à distance sur docs.microsoft.com.

Les méthodes clientes et en attente des résultats du pollueur lèvent des exceptions si la demande a échoué.

Si la ressource d’une conversion n’est pas valide, l’polleur de conversion lève une exception avec une erreur contenant des détails. Une fois que le service de conversion est en mesure de traiter le fichier, un <fichier assetName.result.json> est écrit dans le conteneur de sortie. Si la ressource d’entrée n’est pas valide, ce fichier contient une description plus détaillée du problème.

De même, parfois, lorsqu’une session est demandée, la session se retrouve dans un état d’erreur. L’pollur lève une exception contenant les détails de l’erreur dans ce cas. Les erreurs de session sont généralement temporaires et la demande d’une nouvelle session doit réussir.

Journalisation

Cette bibliothèque utilise la bibliothèque [journalisation][python_logging] standard pour la journalisation.

Les informations de base sur les sessions HTTP (URL, en-têtes, etc.) sont enregistrées au INFO niveau.

La journalisation détaillée DEBUG de niveau, y compris les corps de requête/réponse et les en-têtes non expurgés, peut être activée sur le client ou par opération avec l’argument logging_enable mot clé.

Consultez la documentation complète sur la journalisation du KIT de développement logiciel (SDK) avec des exemples ici.

Configuration facultative

Les arguments facultatifs mot clé peuvent être transmis au niveau du client et par opération. La documentation de référence azure-core décrit les configurations disponibles pour les nouvelles tentatives, la journalisation, les protocoles de transport, etc.

Exceptions

La bibliothèque cliente Remote Rendering déclenche des exceptions définies dans Azure Core.

API asynchrones

Cette bibliothèque inclut également une API asynchrone complète prise en charge sur Python 3.7+. Pour l’utiliser, vous devez d’abord installer un transport asynchrone, tel que aiohttp. Les clients asynchrones se trouvent sous l’espace de azure.mixedreality.remoterendering.aio noms.

Étapes suivantes

• Lire la documentation du produit
• En savoir plus sur les KITS de développement logiciel (SDK) runtime :
  • .NET : /dotnet/api/microsoft.azure.remoterendering
  • C++: /cpp/api/remote-rendering/

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Si vous souhaitez contribuer à cette bibliothèque, lisez le guide de contribution pour en savoir plus sur la génération et le test du code.