Condividi tramite

Libreria client di Azure Rendering remoto per JavaScript - versione 1.0.0-beta.1

  • Articolo

Rendering remoto di Azure è un servizio che consente di eseguire il rendering di contenuti 3D interattivi di alta qualità nel cloud e di trasmetterli in streaming in tempo reale ai dispositivi come HoloLens 2.

Questo SDK offre funzionalità per convertire gli asset nel formato previsto dal runtime e anche per gestire la durata delle sessioni di rendering remoto.

NOTA: una volta eseguita una sessione, un'applicazione client si connetterà con esso usando uno degli SDK di runtime. Questi SDK sono progettati per supportare al meglio le esigenze di un'applicazione interattiva che esegue il rendering di 3d. Sono disponibili in (.net o (C++).

Documentazione del prodotto

Introduzione

Ambienti attualmente supportati

Prerequisiti

È necessaria una sottoscrizione di Azure e un account di Azure Rendering remoto per usare questo pacchetto.

Installare il pacchetto @azure/mixed-reality-remote-rendering

Installare la libreria client modello per JavaScript con npm:

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

Supporto browser

JavaScript Bundle

Per usare questa libreria client nel browser, è prima necessario usare un bundler. Per informazioni dettagliate su come eseguire questa operazione, vedere la documentazione di raggruppamento.

CORS

Questa libreria non può essere usata per effettuare chiamate dirette al servizio di Rendering remoto di Azure da un browser. Per indicazioni, vedere questo documento .

Autenticare il client

La creazione di un client di rendering remoto richiede un account autenticato e un endpoint di rendering remoto. Per un account creato nell'area eastus, il dominio dell'account avrà il formato "eastus.mixedreality.azure.com". Esistono diverse forme di autenticazione:

  • Autenticazione della chiave dell'account
    • Le chiavi dell'account consentono di iniziare rapidamente con l'uso di Azure Rendering remoto. Prima di distribuire l'applicazione in produzione, è consigliabile aggiornare l'app per usare l'autenticazione di Azure AD.
  • Autenticazione del token di Azure Active Directory (AD)
    • Se si crea un'applicazione aziendale e l'azienda usa Azure AD come sistema di identità, è possibile usare l'autenticazione di Azure AD basata sull'utente nell'app. Si concede quindi l'accesso agli account di Rendering remoto di Azure usando i gruppi di sicurezza di Azure AD esistenti. È anche possibile concedere l'accesso direttamente agli utenti dell'organizzazione.
    • In caso contrario, è consigliabile ottenere i token di Azure AD da un servizio Web che supporta l'app. È consigliabile questo metodo per le applicazioni di produzione perché consente di evitare di incorporare le credenziali per l'accesso ad Ancoraggi nello spazio di Azure nell'applicazione client.

Per istruzioni e informazioni dettagliate, vedere qui .

In tutti gli esempi seguenti, il client viene costruito con un remoteRenderingEndpointoggetto . Gli endpoint disponibili corrispondono alle aree e la scelta dell'endpoint determina l'area in cui il servizio esegue il suo lavoro. Un esempio è https://remoterendering.eastus2.mixedreality.azure.com.

NOTA: per la conversione degli asset, è preferibile selezionare un'area vicina all'archiviazione contenente gli asset.

NOTA: per il rendering, è consigliabile selezionare l'area più vicina ai dispositivi che usano il servizio. Il tempo necessario per comunicare con il server influisce sulla qualità dell'esperienza.

Autenticazione con l'autenticazione della chiave dell'account

Usare l'oggetto per usare un identificatore e una chiave dell'account per l'autenticazione AccountKeyCredential :

const credential = new AzureKeyCredential(accountKey);

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

Autenticazione con un segreto client AAD

Usare l'oggetto per eseguire l'autenticazione ClientSecretCredential del segreto client.

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

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

Autenticazione di un utente tramite l'autenticazione del codice del dispositivo

Usare l'oggetto per eseguire l'autenticazione del DeviceCodeCredential codice del dispositivo.

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);

Per altre informazioni sull'uso del flusso di autenticazione del codice del dispositivo, vedere qui .

Autenticazione interattiva con DefaultAzureCredential

Usare l'oggetto con includeInteractiveCredentials: true per usare il DefaultAzureCredential flusso di autenticazione interattiva predefinito:

let credential = new DefaultAzureCredential();

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

Autenticazione con un token di accesso statico

È possibile passare un token di accesso Realtà mista come AccessToken un token di accesso precedentemente recuperato dal servizio STS Realtà mista da usare con una libreria client Realtà mista:

// 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);

Concetti chiave

RemoteRenderingClient

La RemoteRenderingClient libreria client usata per accedere a RemoteRenderingService. Fornisce metodi per creare e gestire le conversioni degli asset e le sessioni di rendering.

Esempio

Convertire un asset semplice

Si supponga che un RemoteRenderingClient sia stato costruito come descritto nella sezione Autenticare il client . Il frammento di codice seguente descrive come richiedere che "box.fbx", trovato nella radice del contenitore BLOB all'URI specificato, viene convertito.

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
);

I file di output verranno posizionati accanto all'asset di input.

Convertire un asset più complesso

Gli asset possono fare riferimento ad altri file e i contenitori BLOB possono contenere file appartenenti a molti asset diversi. In questo esempio viene illustrato come usare i prefissi per organizzare i BLOB e come convertire un asset in modo da tenere conto di tale organizzazione. Si supponga che il contenitore inputStorageUrl BLOB in contiene molti file, tra cui "Bicicletta/bicicletta.gltf", "Bicicletta/bicicletta.bin" e "Bicicletta/saddleTexture.jpg". Quindi il prefisso "Bicicletta" agisce molto come una cartella. Si vuole convertire glTF in modo che abbia accesso agli altri file che condividono il prefisso, senza richiedere al servizio di conversione di accedere ad altri file. Per mantenere l'ordine delle cose, vogliamo anche che i file di output vengano scritti in un contenitore di archiviazione diverso e dato un prefisso comune: "ConvertBicycle". Il codice è indicato di seguito:

  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
  );

NOTA: quando viene specificato un prefisso nelle opzioni di input, si presuppone che il parametro del file di input sia relativo a tale prefisso. Lo stesso vale per il parametro del file di output nelle opzioni di output.

Ottenere l'output al termine di una conversione dell'asset

La conversione di un asset può richiedere da qualsiasi punto a ore. Questo codice usa la conversionePoller restituita da beginConversion per eseguire regolarmente il polling fino a quando la conversione non è stata completata o non riuscita. Il periodo di polling predefinito è di 10 secondi.

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);
}

Si noti che lo stato di un AssetConversionPollerLike può essere serializzato chiamando conversionPoller.toString(). Tale valore può essere passato in un secondo momento a beginConversion come resumeFrom valore, per costruire un nuovo poller che porta avanti da dove l'uno precedente ha lasciato:

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

Conversioni elenco

È possibile ottenere informazioni sulle conversioni usando il getConversions metodo . Questo metodo può restituire conversioni che devono ancora iniziare, conversioni che sono in esecuzione e conversioni che sono state completate. In questo esempio vengono elencati solo gli URI di output delle conversioni riuscite avviate nell'ultimo giorno.

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}`
    );
  }
}

Creare una sessione

Si supponga che un RemoteRenderingClient sia stato costruito come descritto nella sezione Autenticare il client . Il frammento di codice seguente descrive come richiedere l'avvio di una nuova sessione di rendering.

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
);

Si noti che lo stato di un RenderingSessionPollerLike può essere serializzato chiamando toString(). Tale valore può essere passato in beginSession come resumeFrom valore, per costruire un nuovo poller da dove l'uno precedente ha lasciato:

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

Estendere il tempo di lease di una sessione

Se una sessione si avvicina al tempo di lease massimo, ma si vuole mantenerla attiva, sarà necessario effettuare una chiamata per aumentare il tempo massimo di lease. In questo esempio viene illustrato come eseguire query sulle proprietà correnti e quindi estendere il lease se scade presto.

NOTA: gli SDK di runtime offrono anche questa funzionalità e in molti scenari tipici, è consigliabile usarli per estendere il lease di sessione.

/// 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 });
  }
}

Elencare le sessioni

È possibile ottenere informazioni sulle sessioni usando il getSessions metodo . Questo metodo può restituire sessioni che devono ancora iniziare e sessioni pronte.

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

Arrestare una sessione

Il codice seguente interromperà una sessione in esecuzione con id specificato.

client.endSession(sessionId);

Risoluzione dei problemi

Registrazione

L'abilitazione della registrazione consente di individuare informazioni utili sugli errori. Per visualizzare un log di richieste e risposte HTTP, impostare la variabile di ambiente AZURE_LOG_LEVEL su info. In alternativa, la registrazione può essere abilitata in fase di esecuzione chiamando setLogLevel in @azure/logger:

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

setLogLevel("info");

Risoluzione dei problemi di Azure Rendering remoto

Per consigli generali sulla risoluzione dei problemi relativi all'Rendering remoto di Azure, vedere la pagina Risoluzione dei problemi relativi al rendering remoto in docs.microsoft.com.

I metodi client genereranno eccezioni se la richiesta non può essere effettuata. Tuttavia, nel caso di conversioni e sessioni, le richieste possono avere esito positivo, ma l'operazione richiesta potrebbe non essere riuscita. In questo caso, non verrà generata alcuna eccezione, ma gli oggetti restituiti possono essere esaminati per comprendere cosa è successo.

Se l'asset in una conversione non è valido, l'operazione di conversione restituirà un oggetto AssetConversion con stato Non riuscito e con un oggetto RemoteRenderingServiceError con i dettagli. Una volta che il servizio di conversione è in grado di elaborare il file, verrà scritto un <file assetName.result.json> nel contenitore di output. Se l'asset di input non è valido, tale file conterrà una descrizione più dettagliata del problema.

Analogamente, a volte quando viene richiesta una sessione, la sessione termina in uno stato di errore. Il metodo startSessionOperation restituirà un oggetto RenderingSession, ma tale oggetto avrà uno stato Error e conterrà uno stato RemoteRenderingServiceError con i dettagli.

Passaggi successivi

Contributo

Per contribuire a questa libreria, leggere la guida ai contributi per altre informazioni su come compilare e testare il codice.

Impression