Partager via

Bibliothèque de client Azure Remote Rendering pour JavaScript - version 1.0.0-beta.1

  • 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 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 ou (C++).

Documentation du produit

Prise en main

Environnements actuellement pris en charge

Prérequis

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

Installez le package @azure/mixed-reality-remote-rendering

Installez la bibliothèque cliente de modèle pour JavaScript avec npm:

npm install @azure/mixed-reality-remote-rendering

Prise en charge des navigateurs

Ensemble JavaScript

Pour utiliser cette bibliothèque cliente dans le navigateur, vous devez d’abord utiliser un bundler. Pour plus d’informations sur la procédure à suivre, reportez-vous à notre documentation sur le regroupement.

CORS

Cette bibliothèque ne peut pas être utilisée pour effectuer des appels directs au service Azure Remote Rendering à partir d’un navigateur. Reportez-vous à ce document pour obtenir des conseils.

Authentifier le client

La construction d’un client de rendu à distance nécessite un compte authentifié et un point de terminaison de rendu à distance. 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. 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 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 AccountKeyCredential pour utiliser un identificateur de compte et une clé de compte pour l’authentification :

const credential = new AzureKeyCredential(accountKey);

const client = new RemoteRenderingClient(serviceEndpoint, accountId, accountDomain, credential);

Authentification avec une clé secrète client AAD

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

let credential = new ClientSecretCredential(tenantId, clientId, clientSecret, {
  authorityHost: "https://login.microsoftonline.com/" + tenantId
});

const client = new RemoteRenderingClient(serviceEndpoint, 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.

let deviceCodeCallback = (deviceCodeInfo: DeviceCodeInfo) => {
  console.debug(deviceCodeInfo.message);
  console.log(deviceCodeInfo.message);
};

let credential = new DeviceCodeCredential(tenantId, clientId, deviceCodeCallback, {
  authorityHost: "https://login.microsoftonline.com/" + tenantId
});

const client = new RemoteRenderingClient(serviceEndpoint, 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 DefaultAzureCredential avec includeInteractiveCredentials: true pour utiliser le flux d’authentification interactive par défaut :

let credential = new DefaultAzureCredential();

return new RemoteRenderingClient(serviceEndpoint, accountId, accountDomain, credential, {
  authenticationEndpointUrl: "https://sts.mixedreality.azure.com"
});

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.
const accessToken = GetMixedRealityAccessTokenFromWebService();

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

const inputSettings: AssetConversionInputSettings = {
  storageContainerUrl,
  relativeInputAssetPath: "box.fbx"
};
const outputSettings: AssetConversionOutputSettings = {
  storageContainerUrl
};
const conversionSettings: AssetConversionSettings = { inputSettings, outputSettings };

// A randomly generated UUID is a good choice for a conversionId.
const conversionId = uuid();

const conversionPoller: AssetConversionPollerLike = await client.beginConversion(
  conversionId,
  conversionSettings
);

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 organisation. 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 garder les choses en ordre, 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 :

  const inputSettings: AssetConversionInputSettings = {
    storageContainerUrl: inputStorageUrl,
    blobPrefix: "Bicycle"
    relativeInputAssetPath: "bicycle.gltf"
  };
  const outputSettings: AssetConversionOutputSettings = {
    storageContainerUrl: outputStorageUrl,
    blobPrefix: "ConvertedBicycle"
  };
  const conversionSettings: AssetConversionSettings = { inputSettings, outputSettings };

  const conversionId = uuid();

  const conversionPoller: AssetConversionPollerLike = await client.beginConversion(
    conversionId,
    conversionSettings
  );

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 le conversionPoller retourné par beginConversion pour interroger 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.

const conversion = await conversionPoller.pollUntilDone();

console.log("== Check results ==");

if (conversion.status === "Succeeded") {
  console.log("Conversion succeeded: Output written to " + conversion.output?.outputAssetUrl);
} else if (conversion.status === "Failed") {
  console.log("Conversion failed: " + conversion.error.code + " " + conversion.error.message);
}

Notez que l’état d’un AssetConversionPollerLike peut être sérialisé en appelant conversionPoller.toString(). Cette valeur peut ensuite être passée dans beginConversion en tant que resumeFrom valeur, pour construire un nouvel polleur qui continue à partir de là où le précédent s’est arrêté :

const serializedPollerString = conversionPoller.toString();
// ...
const resumedPoller = client.beginConversion({ resumeFrom: serializedPollerString });

Conversions de liste

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 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 URI de sortie des conversions réussies démarrées le dernier jour.

for await (const conversion of client.listConversions()) {
  if (conversion.status === "Succeeded") {
    console.log(
      `Conversion ${conversion.conversionId} succeeded: Output written to ${conversion.output?.outputAssetUrl}`
    );
  } else if (conversion.status === "Failed") {
    console.log(
      `Conversion ${conversion.conversionId} failed: ${conversion.error.code} ${conversion.error.message}`
    );
  }
}

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 le démarrage d’une nouvelle session de rendu.

const sessionSettings: RenderingSessionSettings = {
  maxLeaseTimeInMinutes: 4,
  size: "Standard"
};

// A randomly generated UUID is a good choice for a conversionId.
const sessionId = uuid();

const sessionPoller: RenderingSessionPollerLike = await client.beginSession(
  sessionId,
  sessionSettings
);

Notez que l’état d’un RenderingSessionPollerLike peut être sérialisé en appelant toString(). Cette valeur peut ensuite être passée dans beginSession en tant que resumeFrom valeur, pour construire un nouvel pollinisateur qui continue à partir de là où le précédent s’est arrêté :

const serializedPollerString = sessionPoller.toString();
// ...
const resumedPoller = client.beginSession({ resumeFrom: serializedPollerString });

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 kits SDK runtime offrent également cette fonctionnalité et, dans de nombreux scénarios classiques, vous les utiliseriez pour étendre le bail de session.

/// When the lease is within 2 minutes of expiring, extend it by 15 minutes.
let currentSession = await client.getSession(sessionId);
if (currentSession.status == "Ready") {
  if (
    currentSession.maxLeaseTimeInMinutes -
      (Date.now() - currentSession.properties.createdOn.valueOf()) / 60000 <
    2
  ) {
    let newLeaseTime = currentSession.maxLeaseTimeInMinutes + 15;

    await client.updateSession(sessionId, { maxLeaseTimeInMinutes: newLeaseTime });
  }
}

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 commencé et des sessions qui sont prêtes.

for await (const session of client.listSessions()) {
  console.log(`Session ${session.sessionId} is ${session.status}`);
}

Arrêter une session

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

client.endSession(sessionId);

Résolution des problèmes

Journalisation

L’activation de la journalisation peut vous aider à mieux comprendre les échecs. Pour avoir un journal des requêtes et réponses HTTP, définissez la variable d’environnement AZURE_LOG_LEVEL sur info. Vous pouvez également activer la journalisation au moment de l’exécution en appelant setLogLevel dans @azure/logger :

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Résolution des problèmes de Remote Rendering Azure

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 état Échec 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 renvoie un objet RenderingSession, mais cet objet a l’état Error et comporte un RemoteRenderingServiceError avec des détails.

Étapes suivantes

Contribution

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.

Impressions