Bibliothèque de client Azure Remote Rendering pour .NET - version 1.1.0

  • Article

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.

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

Prise en main

Installer le package

Installez la bibliothèque de client Azure Mixed Reality ARR pour .NET à l’aide de l’une des méthodes suivantes.

À partir du Gestionnaire de package Visual Studio :

Install-Package Azure.MixedReality.RemoteRendering

À partir de l’interface CLI .NET

dotnet add package Azure.MixedReality.RemoteRendering

Ajoutez une référence de package :

<PackageReference Include="Azure.MixedReality.RemoteRendering" Version="1.0.0" />

Prérequis

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

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 vous recommandons d’utiliser cette méthode pour les applications de production, car cela vous permet d’éviter d’incorporer les informations d’identification pour l’accès à Azure Spatial Anchors 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 remoteRenderingEndpoint objet URI. 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.

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 AccountKeyCredential pour utiliser un identificateur de compte et une clé de compte pour vous authentifier :

AzureKeyCredential accountKeyCredential = new AzureKeyCredential(accountKey);

RemoteRenderingClient client = new RemoteRenderingClient(remoteRenderingEndpoint, accountId, accountDomain, accountKeyCredential);

Authentification avec une clé secrète client AAD

Utilisez l’objet ClientSecretCredential pour effectuer l’authentification par clé secrète client.

TokenCredential credential = new ClientSecretCredential(tenantId, clientId, clientSecret, new TokenCredentialOptions
{
    AuthorityHost = new Uri($"https://login.microsoftonline.com/{tenantId}")
});

RemoteRenderingClient client = new RemoteRenderingClient(remoteRenderingEndpoint, accountId, accountDomain, credential);

Authentification d’un utilisateur à l’aide de l’authentification par code d’appareil

Utilisez l’objet pour effectuer l’authentification DeviceCodeCredential par code d’appareil.

Task deviceCodeCallback(DeviceCodeInfo deviceCodeInfo, CancellationToken cancellationToken)
{
    Debug.WriteLine(deviceCodeInfo.Message);
    Console.WriteLine(deviceCodeInfo.Message);
    return Task.FromResult(0);
}

TokenCredential credential = new DeviceCodeCredential(deviceCodeCallback, tenantId, clientId, new TokenCredentialOptions
{
    AuthorityHost = new Uri($"https://login.microsoftonline.com/{tenantId}"),
});

RemoteRenderingClient client = new RemoteRenderingClient(remoteRenderingEndpoint, accountId, accountDomain, credential);

Consultez ici pour plus d’informations sur l’utilisation du flux d’authentification par code d’appareil.

Authentification interactive avec DefaultAzureCredential

Utilisez l’objet avec includeInteractiveCredentials: true pour utiliser le DefaultAzureCredential flux d’authentification interactive par défaut :

TokenCredential credential = new DefaultAzureCredential(includeInteractiveCredentials: true);

RemoteRenderingClient client = new RemoteRenderingClient(remoteRenderingEndpoint, accountId, accountDomain, 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 :

// GetMixedRealityAccessTokenFromWebService is a hypothetical method that retrieves
// a Mixed Reality access token from a web service. The web service would use the
// MixedRealityStsClient and credentials to obtain an access token to be returned
// to the client.
AccessToken accessToken = GetMixedRealityAccessTokenFromWebService();

RemoteRenderingClient client = new RemoteRenderingClient(remoteRenderingEndpoint, accountId, accountDomain, accessToken);

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.

Exemples

Convertir une ressource simple

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 à la racine du conteneur d’objets blob à l’URI donné, soit converti.

    AssetConversionInputOptions inputOptions = new AssetConversionInputOptions(storageUri, "box.fbx");
    AssetConversionOutputOptions outputOptions = new AssetConversionOutputOptions(storageUri);
    AssetConversionOptions conversionOptions = new AssetConversionOptions(inputOptions, outputOptions);

    // A randomly generated GUID is a good choice for a conversionId.
    string conversionId = Guid.NewGuid().ToString();

    AssetConversionOperation conversionOperation = client.StartConversion(conversionId, conversionOptions);

Les fichiers de sortie seront placés à côté de la ressource d’entrée.

Convertir une ressource plus complexe

Les ressources peuvent référencer d’autres fichiers, et les conteneurs d’objets blob peuvent contenir des fichiers appartenant à de nombreuses ressources différentes. Dans cet exemple, nous montrons comment utiliser des préfixes pour organiser vos objets blob et comment convertir une ressource pour tenir compte de cette organization. Supposons que le conteneur d’objets blob à inputStorageUri contient de nombreux fichiers, notamment « Bicycle/bicycle.gltf », « Bicycle/bicycle.bin » et « Bicycle/saddleTexture.jpg ». (Par conséquent, le préfixe « Bicycle » est très semblable à un dossier.) Nous voulons convertir le gltf afin qu’il ait accès aux autres fichiers qui partagent le préfixe, sans exiger que le service de conversion accède à d’autres fichiers. Pour que les choses restent ordonnées, nous voulons également que les fichiers de sortie soient écrits dans un autre conteneur de stockage et donné un préfixe commun : « ConvertedBicycle ». Le code se présente comme suit :

    AssetConversionInputOptions input = new AssetConversionInputOptions(inputStorageUri, "bicycle.gltf")
    {
        BlobPrefix = "Bicycle"
    };
    AssetConversionOutputOptions output = new AssetConversionOutputOptions(outputStorageUri)
    {
        BlobPrefix = "ConvertedBicycle"
    };
    AssetConversionOptions conversionOptions = new AssetConversionOptions(inputOptions, outputOptions);

    string conversionId = Guid.NewGuid().ToString();

    AssetConversionOperation conversionOperation = client.StartConversion(conversionId, conversionOptions);

REMARQUE : lorsqu’un préfixe est donné dans les options d’entrée, le paramètre de fichier d’entrée est supposé être relatif à ce préfixe. Il en est de même pour le paramètre de fichier de sortie dans les options de sortie.

Obtenir la sortie lorsqu’une conversion de ressource est terminée

La conversion d’une ressource peut prendre de quelques secondes à des heures. Ce code utilise une conversionOperation existante 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 10 secondes. Notez qu’une conversionOperation peut être construite à partir de la conversionId d’une conversion existante et d’un client.

    AssetConversion conversion = conversionOperation.WaitForCompletionAsync().Result;
    if (conversion.Status == AssetConversionStatus.Succeeded)
    {
        Console.WriteLine($"Conversion succeeded: Output written to {conversion.Output.OutputAssetUri}");
    }
    else if (conversion.Status == AssetConversionStatus.Failed)
    {
        Console.WriteLine($"Conversion failed: {conversion.Error.Code} {conversion.Error.Message}");
    }

Répertorier les conversions

Vous pouvez obtenir des informations sur vos conversions à l’aide de la getConversions méthode . Cette méthode peut retourner des conversions qui n’ont pas encore démarré, des conversions en cours d’exécution et des conversions terminées. Dans cet exemple, nous allons simplement répertorier les URI de sortie des conversions réussies démarrées le dernier jour.

    foreach (var conversion in client.GetConversions())
    {
        if ((conversion.Status == AssetConversionStatus.Succeeded) && (conversion.CreatedOn > DateTimeOffset.Now.AddDays(-1)))
        {
            Console.WriteLine($"output asset URI: {conversion.Output.OutputAssetUri}");
        }
    }

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.

    RenderingSessionOptions options = new RenderingSessionOptions(TimeSpan.FromMinutes(30), RenderingServerSize.Standard);

    // A randomly generated GUID is a good choice for a sessionId.
    string sessionId = Guid.NewGuid().ToString();

    StartRenderingSessionOperation startSessionOperation = client.StartSession(sessionId, options);

    RenderingSession newSession = startSessionOperation.WaitForCompletionAsync().Result;
    if (newSession.Status == RenderingSessionStatus.Ready)
    {
        Console.WriteLine($"Session {sessionId} is ready.");
    }
    else if (newSession.Status == RenderingSessionStatus.Error)
    {
        Console.WriteLine($"Session {sessionId} encountered an error: {newSession.Error.Code} {newSession.Error.Message}");
    }

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.

    RenderingSession currentSession = client.GetSession(sessionId);

    if (currentSession.MaxLeaseTime - DateTimeOffset.Now.Subtract(currentSession.CreatedOn.Value) < TimeSpan.FromMinutes(2))
    {
        TimeSpan newLeaseTime = currentSession.MaxLeaseTime.Value.Add(TimeSpan.FromMinutes(30));

        UpdateSessionOptions longerLeaseSettings = new UpdateSessionOptions(newLeaseTime);

        client.UpdateSession(sessionId, longerLeaseSettings);
    }

Répertorier les sessions

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

    foreach (var properties in client.GetSessions())
    {
        if (properties.Status == RenderingSessionStatus.Starting)
        {
            Console.WriteLine($"Session \"{properties.SessionId}\" is starting.");
        }
        else if (properties.Status == RenderingSessionStatus.Ready)
        {
            Console.WriteLine($"Session \"{properties.SessionId}\" is ready at host {properties.Host}");
        }
    }

Arrêter une session

Le code suivant arrête une session en cours d’exécution avec un ID donné.

    client.StopSession(sessionId);

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 lèvent des exceptions si la demande ne peut pas être effectuée. Toutefois, dans le cas des conversions et des sessions, les demandes peuvent réussir, mais l’opération demandée peut ne pas réussir. Dans ce cas, aucune exception n’est levée, mais les objets retournés peuvent être inspectés pour comprendre ce qui s’est passé.

Si la ressource d’une conversion n’est pas valide, l’opération de conversion retourne un objet AssetConversion avec un status Failed et portant un RemoteRenderingServiceError avec 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. La méthode startSessionOperation retourne un objet RenderingSession, mais cet objet aura un status Error et contiendra un RemoteRenderingServiceError avec des détails.

Étapes suivantes

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.