Bibliothèque de client Azure Remote Rendering pour Java - version 1.1.23

Article
10/21/2023

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 kits SDK sont conçus pour prendre au mieux en charge les besoins d’une application interactive effectuant un rendu 3D. Ils sont disponibles dans .NET et C++.

| Code source Documentation de référence sur les | APIDocumentation produit

Prise en main

Prérequis

Kit de développement Java (JDK), version 8 ou ultérieure.
Abonnement Azure
Compte Azure Remote Rendering pour utiliser ce package.

Inclure le package

Inclure le fichier de nomenclature

Incluez azure-sdk-bom dans votre projet pour dépendre de la version de disponibilité générale de la bibliothèque. Dans l’extrait de code suivant, remplacez l’espace réservé {bom_version_to_target} par le numéro de version. Pour en savoir plus sur la nomenclature, consultez le README BOM du KIT DE DÉVELOPPEMENT LOGICIEL AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

puis incluez la dépendance directe dans la section dépendances sans la balise de version, comme indiqué ci-dessous.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-mixedreality-remoterendering</artifactId>
  </dependency>
</dependencies>

Inclure une dépendance directe

Note: Cette version cible azure Remote Rendering version de l’API de service v2021-01-01.

Ajoutez la dépendance Maven suivante :

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-mixedreality-remoterendering</artifactId>
    <version>1.1.23</version>
</dependency>

Authentifier le client

La construction d’un client de rendu à distance nécessite un compte authentifié et un point de terminaison de rendu à distance. Un compte se compose de son accountId et d’un domaine de compte. Pour un compte créé dans la région eastus, le domaine du compte aura la forme « eastus.mixedreality.azure.com ». Il existe plusieurs 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 RemoteRenderingClientBuilder objet . Les paramètres sont toujours les mêmes, à l’exception de l’objet d’informations d’identification, qui est expliqué dans chaque exemple. Le remoteRenderingEndpoint paramètre est une URL qui détermine la région dans laquelle le service effectue son travail. par exemple https://remoterendering.eastus2.mixedreality.azure.com.

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

REMARQUE : Pour le rendu, il est fortement 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 l’authentification :

AzureKeyCredential credential = new AzureKeyCredential(environment.getAccountKey());

RemoteRenderingClient client = new RemoteRenderingClientBuilder()
    .accountId(environment.getAccountId())
    .accountDomain(environment.getAccountDomain())
    .endpoint(environment.getServiceEndpoint())
    .credential(credential)
    .buildClient();

Authentification avec une clé secrète client AAD

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

ClientSecretCredential credential = new ClientSecretCredentialBuilder()
    .tenantId(environment.getTenantId())
    .clientId(environment.getClientId())
    .clientSecret(environment.getClientSecret())
    .authorityHost("https://login.microsoftonline.com/" + environment.getTenantId())
    .build();

RemoteRenderingClient client = new RemoteRenderingClientBuilder()
    .accountId(environment.getAccountId())
    .accountDomain(environment.getAccountDomain())
    .endpoint(environment.getServiceEndpoint())
    .credential(credential)
    .buildClient();

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.

DeviceCodeCredential credential = new DeviceCodeCredentialBuilder()
    .challengeConsumer((DeviceCodeInfo deviceCodeInfo) -> {
        logger.info(deviceCodeInfo.getMessage());
    })
    .clientId(environment.getClientId())
    .tenantId(environment.getTenantId())
    .authorityHost("https://login.microsoftonline.com/" + environment.getTenantId())
    .build();

RemoteRenderingClient client = new RemoteRenderingClientBuilder()
    .accountId(environment.getAccountId())
    .accountDomain(environment.getAccountDomain())
    .endpoint(environment.getServiceEndpoint())
    .credential(credential)
    .buildClient();

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

Authentification interactive avec DefaultAzureCredential

Utilisez l’objet DefaultAzureCredential :

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();

RemoteRenderingClient client = new RemoteRenderingClientBuilder()
    .accountId(environment.getAccountId())
    .accountDomain(environment.getAccountDomain())
    .endpoint(environment.getServiceEndpoint())
    .credential(credential)
    .buildClient();

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 RemoteRenderingClientBuilder()
    .accountId(environment.getAccountId())
    .accountDomain(environment.getAccountDomain())
    .endpoint(environment.getServiceEndpoint())
    .accessToken(accessToken)
    .buildClient();

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
Convertir une ressource plus complexe
Obtenir la sortie lorsqu’une conversion de ressource est terminée
Conversions de liste
Créer une session
Prolonger la durée de bail d’une session
Répertorier les sessions
Arrêter une session

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’URL donnée, soit converti.

AssetConversionOptions conversionOptions = new AssetConversionOptions()
    .setInputStorageContainerUrl(getStorageURL())
    .setInputRelativeAssetPath("box.fbx")
    .setOutputStorageContainerUrl(getStorageURL());

// A randomly generated UUID is a good choice for a conversionId.
String conversionId = UUID.randomUUID().toString();

SyncPoller<AssetConversion, AssetConversion> conversionOperation = client.beginConversion(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 dans inputStorageURL contient de nombreux fichiers, notamment « Bicycle/bicycle.gltf », « Bicycle/bicycle.bin » et « Bicycle/saddleTexture.jpg ». (Ainsi, le préfixe « Bicycle » agit très comme un dossier.) Nous voulons convertir le fichier 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 reçoivent un préfixe commun : « ConvertedBicycle ». Le code se présente comme suit :

AssetConversionOptions conversionOptions = new AssetConversionOptions()
    .setInputStorageContainerUrl(inputStorageURL)
    .setInputRelativeAssetPath("bicycle.gltf")
    .setInputBlobPrefix("Bicycle")
    .setOutputStorageContainerUrl(outputStorageURL)
    .setOutputBlobPrefix("ConvertedBicycle");

String conversionId = UUID.randomUUID().toString();

SyncPoller<AssetConversion, AssetConversion> conversionOperation = client.beginConversion(conversionId, conversionOptions);

REMARQUE : lorsqu’un préfixe est fourni dans les options d’entrée, le paramètre de fichier d’entrée est supposé être relatif à ce préfixe. Il en va 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 entre quelques secondes et quelques 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 l’id de conversion d’une conversion existante et d’un client.

AssetConversion conversion = conversionOperation.getFinalResult();
if (conversion.getStatus() == AssetConversionStatus.SUCCEEDED) {
    logger.info("Conversion succeeded: Output written to {}", conversion.getOutputAssetUrl());
} else if (conversion.getStatus() == AssetConversionStatus.FAILED) {
    logger.error("Conversion failed: {} {}", conversion.getError().getCode(), conversion.getError().getMessage());
} else {
    logger.error("Unexpected conversion status: {}", conversion.getStatus());
}

Conversions de liste

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

for (AssetConversion conversion : client.listConversions()) {
    if ((conversion.getStatus() == AssetConversionStatus.SUCCEEDED)
        && (conversion.getCreationTime().isAfter(OffsetDateTime.now().minusDays(1)))) {
        logger.info("Output Asset URL: {}", conversion.getOutputAssetUrl());
    }
}

Créer une session de rendu

BeginSessionOptions options = new BeginSessionOptions()
    .setMaxLeaseTime(Duration.ofMinutes(30))
    .setSize(RenderingSessionSize.STANDARD);

// A randomly generated GUID is a good choice for a sessionId.
String sessionId = UUID.randomUUID().toString();

SyncPoller<RenderingSession, RenderingSession> startSessionOperation = client.beginSession(sessionId, options);

Prolonger la durée de bail d’une session

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

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

RenderingSession currentSession = client.getSession(sessionId);

Duration sessionTimeAlive = Duration.between(OffsetDateTime.now(), currentSession.getCreationTime()).abs();
if (currentSession.getMaxLeaseTime().minus(sessionTimeAlive).toMinutes() < 2) {
    Duration newLeaseTime = currentSession.getMaxLeaseTime().plus(Duration.ofMinutes(30));
    UpdateSessionOptions longerLeaseOptions = new UpdateSessionOptions().maxLeaseTime(newLeaseTime);
    client.updateSession(sessionId, longerLeaseOptions);
}

Répertorier les sessions de rendu

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

for (RenderingSession session : client.listSessions()) {
    if (session.getStatus() == RenderingSessionStatus.STARTING) {
        logger.info("Session {} is starting.");
    } else if (session.getStatus() == RenderingSessionStatus.READY) {
        logger.info("Session {} is ready at host {}", session.getId(), session.getHostname());
    } else if (session.getStatus() == RenderingSessionStatus.ERROR) {
        logger.error("Session {} encountered an error: {} {}", session.getId(), session.getError().getCode(), session.getError().getMessage());
    } else {
        logger.error("Session {} has unexpected status {}", session.getId(), session.getStatus());
    }
}

Arrêter une session

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

client.endSession(sessionId);

Dépannage

Pour obtenir des conseils généraux sur la résolution des problèmes liés aux Remote Rendering Azure, consultez la page Résoudre les problèmes de rendu à distance à 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 requêtes peuvent réussir, mais l’opération demandée peut ne pas réussir. Dans ce cas, aucune exception ne sera 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 transportant 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 renvoie un objet RenderingSession, mais cet objet aura un status Error et contiendra un RemoteRenderingServiceError avec des détails.

Étapes suivantes

Lire la documentation du produit
En savoir plus sur les kits SDK d’exécution :
- .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.

Impressions

Partager via