Condividi tramite

Libreria client di Rendering remoto di Azure 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 tempo reale ai dispositivi, ad esempio 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à a essa usando uno degli "SDK di runtime". Questi SDK sono progettati per supportare al meglio le esigenze di un'applicazione interattiva che esegue il rendering 3d. Sono disponibili in (.net o (C++).

documentazione del prodotto

Introduttiva

Ambienti attualmente supportati

Prerequisiti

Per usare questo pacchetto è necessario un di sottoscrizione di Azure e un account di Rendering remoto di Azure .

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 creazione di bundle .

CORS

Questa libreria non può essere usata per effettuare chiamate dirette al servizio 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 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 a usare Rendering remoto di Azure. Ma prima di distribuire l'applicazione nell'ambiente di produzione, è consigliabile aggiornare l'app per usare l'autenticazione di Azure AD.
  • Autenticazione del token di Azure Active Directory (AD)
    • Se si sta creando 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 usare questo metodo per le applicazioni di produzione perché consente di evitare di incorporare le credenziali nell'applicazione client.

Per istruzioni dettagliate e informazioni , vedere qui.

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

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

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

Autenticazione con l'autenticazione della chiave dell'account

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

const credential = new AzureKeyCredential(accountKey);

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

Autenticazione con un segreto client AAD

Utilizzare l'oggetto ClientSecretCredential per eseguire l'autenticazione 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 DeviceCodeCredential per eseguire l'autenticazione del 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 DefaultAzureCredential con includeInteractiveCredentials: true per usare il flusso di autenticazione interattivo 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 alla realtà mista come AccessToken recuperato in precedenza dal servizio sts di realtà mista da usare con una libreria client di 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

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

Esempi

Convertire un asset semplice

Si presuppone che 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 in corrispondenza dell'URI specificato, venga 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 BLOB in inputStorageUrl contenga molti file, tra cui "Bicycle/bicycle.gltf", "Bicycle/bicycle.bin" e "Bicycle/saddleTexture.jpg". Quindi il prefisso "Bicicletta" agisce molto come una cartella. Si vuole convertire il 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, si vuole anche che i file di output vengano scritti in un contenitore di archiviazione diverso e con un prefisso comune: "ConvertBicycle". Il codice è il seguente:

  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 della conversione di un asset

La conversione di un asset può richiedere da qualche secondo a ora. Questo codice usa conversionPoller restituito da beginConversion per eseguire regolarmente il polling fino al termine o all'esito negativo della conversione. Il periodo di polling predefinito è 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ò successivamente essere passato a beginConversion come valore resumeFrom, per costruire un nuovo poller che porta da dove è stato interrotto quello precedente:

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

Elencare le conversioni

È possibile ottenere informazioni sulle conversioni usando il metodo getConversions. 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 presuppone che 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 Oggetto RenderingSessionPollerLike può essere serializzato chiamando toString(). Tale valore può essere passato in un secondo momento in beginSession come valore resumeFrom, per costruire un nuovo poller che porta da dove è stato interrotto quello precedente:

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

Estendere il tempo di lease di una sessione

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

NOTA: gli SDK di runtime offrono anche questa funzionalità e, in molti scenari tipici, è possibile 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 metodo getSessions. Questo metodo può restituire sessioni che devono ancora essere avviate e sessioni pronte.

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

Arrestare una sessione

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

client.endSession(sessionId);

Risoluzione dei problemi

Registrazione

L'abilitazione della registrazione può aiutare a 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 nel @azure/logger:

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

setLogLevel("info");

Risoluzione dei problemi di Rendering remoto di Azure

Per consigli generali sulla risoluzione dei problemi relativi a Rendering remoto di Azure, vedere pagina Risoluzione dei problemi per il rendering remoto in docs.microsoft.com.

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

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

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

Passaggi successivi

Contribuire

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

impressioni