Delen via

Azure Remote Rendering-clientbibliotheek voor JavaScript - versie 1.0.0-beta.1

  • Artikel

Azure Remote Rendering (ARR) is een service waarmee u kwalitatief hoogwaardige, interactieve 3D-inhoud in de cloud kunt weergeven en deze in realtime kunt streamen naar apparaten, zoals HoloLens 2.

Deze SDK biedt functionaliteit voor het converteren van assets naar de indeling die door de runtime wordt verwacht en voor het beheren van de levensduur van externe renderingsessies.

OPMERKING: zodra een sessie wordt uitgevoerd, maakt een clienttoepassing er verbinding mee met behulp van een van de 'runtime-SDK's'. Deze SDK's zijn ontworpen om de behoeften van een interactieve toepassing die 3D-rendering uitvoert, optimaal te ondersteunen. Ze zijn beschikbaar in (.net of (C++).

Productdocumentatie

Aan de slag

Momenteel ondersteunde omgevingen

Vereisten

U hebt een Azure-abonnement en een Azure Remote Rendering-account nodig om dit pakket te kunnen gebruiken.

Installeer het pakket @azure/mixed-reality-remote-rendering

Installeer de sjabloonclientbibliotheek voor JavaScript met npm:

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

Browserondersteuning

JavaScript-bundel

Als u deze clientbibliotheek in de browser wilt gebruiken, moet u eerst een bundelaar gebruiken. Raadpleeg onze documentatie voor bundeling voor meer informatie over hoe u dit doet.

CORS

Deze bibliotheek kan niet worden gebruikt om de Azure Remote Rendering-service rechtstreeks aan te roepen vanuit een browser. Raadpleeg dit document voor hulp.

De client verifiëren

Voor het maken van een Remote Rendering-client is een geverifieerd account en een remote rendering-eindpunt vereist. Voor een account dat is gemaakt in de regio eastus, heeft het accountdomein de notatie 'eastus.mixedreality.azure.com'. Er zijn verschillende vormen van verificatie:

  • Verificatie met accountsleutel
    • Met accountsleutels kunt u snel aan de slag met het gebruik van Azure Remote Rendering. Maar voordat u uw toepassing in productie implementeert, raden we u aan uw app bij te werken voor het gebruik van Azure AD-verificatie.
  • Azure Active Directory-tokenverificatie (AD)
    • Als u een bedrijfstoepassing bouwt en uw bedrijf Azure AD als identiteitssysteem gebruikt, kunt u gebruikersgebaseerde Azure AD-verificatie in uw app gebruiken. Vervolgens verleent u toegang tot uw Azure Remote Rendering-accounts met behulp van uw bestaande Azure AD beveiligingsgroepen. U kunt ook rechtstreeks toegang verlenen aan gebruikers in uw organisatie.
    • Anders raden we u aan Azure AD-tokens te verkrijgen van een webservice die ondersteuning biedt voor uw app. We raden deze methode aan voor productietoepassingen, omdat u hiermee kunt voorkomen dat de referenties voor toegang tot Azure Spatial Anchors in uw clienttoepassing worden ingesloten.

Kijk hier voor gedetailleerde instructies en informatie.

In alle volgende voorbeelden wordt de client gemaakt met een remoteRenderingEndpoint. De beschikbare eindpunten komen overeen met regio's en de keuze van het eindpunt bepaalt de regio waarin de service het werk uitvoert. Een voorbeeld is https://remoterendering.eastus2.mixedreality.azure.com.

OPMERKING: Voor het converteren van assets verdient het de voorkeur om een regio te kiezen dicht bij de opslag die de assets bevat.

OPMERKING: Voor het weergeven wordt het ten zeerste aanbevolen dat u de regio kiest die het dichtst bij de apparaten ligt met behulp van de service. De tijd die nodig is om met de server te communiceren, is van invloed op de kwaliteit van de ervaring.

Verificatie met accountsleutelverificatie

Gebruik het AccountKeyCredential -object om een account-id en accountsleutel te gebruiken om te verifiëren:

const credential = new AzureKeyCredential(accountKey);

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

Verifiëren met een AAD-clientgeheim

Gebruik het ClientSecretCredential -object om verificatie van clientgeheimen uit te voeren.

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

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

Een gebruiker verifiëren met behulp van apparaatcodeverificatie

Gebruik het DeviceCodeCredential -object om verificatie van apparaatcode uit te voeren.

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

Zie hier voor meer informatie over het gebruik van de verificatiestroom voor apparaatcode.

Interactieve verificatie met DefaultAzureCredential

Gebruik het object met includeInteractiveCredentials: true om de DefaultAzureCredential standaard interactieve verificatiestroom te gebruiken:

let credential = new DefaultAzureCredential();

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

Verifiëren met een statisch toegangstoken

U kunt een Mixed Reality toegangstoken doorgeven als een AccessToken eerder opgehaald uit de Mixed Reality STS-service voor gebruik met een Mixed Reality-clientbibliotheek:

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

Belangrijkste concepten

RemoteRenderingClient

De RemoteRenderingClient is de clientbibliotheek die wordt gebruikt voor toegang tot de RemoteRenderingService. Het biedt methoden voor het maken en beheren van assetconversies en renderingsessies.

Voorbeelden

Een eenvoudige asset converteren

We gaan ervan uit dat een RemoteRenderingClient is gemaakt zoals beschreven in de sectie De client verifiëren . In het volgende codefragment wordt beschreven hoe u kunt aanvragen dat 'box.fbx', te vinden in de hoofdmap van de blobcontainer op de opgegeven URI, wordt geconverteerd.

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

De uitvoerbestanden worden naast de invoerasset geplaatst.

Een complexere asset converteren

Assets kunnen verwijzen naar andere bestanden en blobcontainers kunnen bestanden bevatten die tot veel verschillende assets behoren. In dit voorbeeld laten we zien hoe voorvoegsels kunnen worden gebruikt om uw blobs te ordenen en hoe u een asset kunt converteren om rekening te houden met die organisatie. Stel dat de blobcontainer op inputStorageUrl veel bestanden bevat, waaronder 'Bicycle/bicycle.gltf', 'Bicycle/bicycle.bin' en 'Bicycle/saddleTexture.jpg'. (Het voorvoegsel 'Fiets' werkt dus als een map.) We willen de glTF converteren zodat deze toegang heeft tot de andere bestanden die het voorvoegsel delen, zonder dat de conversieservice toegang heeft tot andere bestanden. Om alles netjes te houden, willen we ook dat de uitvoerbestanden naar een andere opslagcontainer worden geschreven en een gemeenschappelijk voorvoegsel krijgen: "ConvertedBicycle". De code is als volgt:

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

OPMERKING: wanneer een voorvoegsel wordt opgegeven in de invoeropties, wordt ervan uitgegaan dat de parameter voor het invoerbestand relatief is ten opzichte van dat voorvoegsel. Hetzelfde geldt voor de uitvoerbestandsparameter in uitvoeropties.

De uitvoer ophalen wanneer een assetconversie is voltooid

Het converteren van een asset kan seconden tot uren duren. Deze code maakt gebruik van de conversionPoller die wordt geretourneerd door beginConversion om regelmatig te peilen totdat de conversie is voltooid of mislukt. De standaard pollingperiode is 10 seconden.

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

Houd er rekening mee dat de status van een AssetConversionPollerLike kan worden geserialiseerd door conversionPoller.toString() aan te roepen. Deze waarde kan later worden doorgegeven aan beginConversion als een resumeFrom waarde, om een nieuwe poller te maken die verdergaat waar de eerdere is gebleven:

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

Lijstconversies

U kunt informatie over uw conversies ophalen met behulp van de getConversions -methode. Deze methode kan conversies retourneren die nog niet zijn gestart, conversies die worden uitgevoerd en conversies die zijn voltooid. In dit voorbeeld vermelden we alleen de uitvoer-URI's van geslaagde conversies die de afgelopen dag zijn gestart.

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

Een sessie maken

We gaan ervan uit dat een RemoteRenderingClient is gemaakt zoals beschreven in de sectie De client verifiëren . In het volgende codefragment wordt beschreven hoe u aanvraagt om een nieuwe renderingsessie te starten.

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

Houd er rekening mee dat de status van een RenderingSessionPollerLike kan worden geserialiseerd door toString() aan te roepen. Deze waarde kan later worden doorgegeven aan beginSession als een resumeFrom waarde, om een nieuwe poller te maken die verdergaat waar de eerdere is gebleven:

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

De leasetijd van een sessie verlengen

Als een sessie de maximale leasetijd nadert, maar u deze actief wilt houden, moet u een aanroep doen om de maximale leasetijd te verhogen. In dit voorbeeld ziet u hoe u een query uitvoert op de huidige eigenschappen en vervolgens de lease verlengt als deze binnenkort verloopt.

OPMERKING: De runtime-SDK's bieden deze functionaliteit ook en in veel typische scenario's gebruikt u deze om de sessielease te verlengen.

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

Sessies weergeven

U kunt informatie over uw sessies ophalen met behulp van de getSessions -methode. Deze methode kan sessies retourneren die nog niet zijn gestart en sessies die klaar zijn.

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

Een sessie stoppen

Met de volgende code wordt een actieve sessie met de opgegeven id gestopt.

client.endSession(sessionId);

Problemen oplossen

Logboekregistratie

Het inschakelen van logboekregistratie kan helpen bij het ontdekken van nuttige informatie over fouten. Als u een logboek met HTTP-aanvragen en -antwoorden wilt zien, stelt u de AZURE_LOG_LEVEL omgevingsvariabele in op info. Logboekregistratie kan ook worden ingeschakeld tijdens runtime door aan te roepen setLogLevel in de @azure/logger:

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

setLogLevel("info");

Problemen met Azure Remote Rendering oplossen

Zie de pagina Problemen oplossen voor externe rendering op docs.microsoft.com voor algemeen advies over het oplossen van problemen met betrekking tot Azure Remote Rendering.

De clientmethoden genereren uitzonderingen als de aanvraag niet kan worden gedaan. In het geval van zowel conversies als sessies kunnen de aanvragen echter slagen, maar is de aangevraagde bewerking mogelijk niet geslaagd. In dit geval wordt er geen uitzondering gegenereerd, maar kunnen de geretourneerde objecten worden geïnspecteerd om te begrijpen wat er is gebeurd.

Als de asset in een conversie ongeldig is, retourneert de conversiebewerking een AssetConversion-object met de status Mislukt en met een RemoteRenderingServiceError met details. Zodra de conversieservice het bestand kan verwerken, wordt het <bestand assetName.result.json> naar de uitvoercontainer geschreven. Als de invoerasset ongeldig is, bevat dat bestand een gedetailleerde beschrijving van het probleem.

En soms, wanneer een sessie wordt aangevraagd, eindigt de sessie in een foutstatus. De methode startSessionOperation retourneert een RenderingSession-object, maar dat object heeft de status Error en bevat een RemoteRenderingServiceError met details.

Volgende stappen

Bijdragen

Als u een bijdrage wilt leveren aan deze bibliotheek, leest u de handleiding voor bijdragen voor meer informatie over het bouwen en testen van de code.

Weergaven