Delen via

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

  • Artikel

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

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

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 beste ondersteuning te bieden voor de behoeften van een interactieve toepassing die 3d-rendering uitvoert. Ze zijn beschikbaar in (.net- of (C++).

productdocumentatie

Slag

Momenteel ondersteunde omgevingen

Voorwaarden

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

Het @azure/mixed-reality-remote-rendering-pakket installeren

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 bundeldocumentatievoor meer informatie over hoe u dit doet.

CORS

Deze bibliotheek kan niet worden gebruikt om vanuit een browser directe aanroepen naar de Azure Remote Rendering-service uit te voeren. Raadpleeg dit document voor hulp.

De client verifiëren

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

  • Verificatie van 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.
  • Verificatie van Azure Active Directory-token (AD)
    • Als u een bedrijfstoepassing bouwt en uw bedrijf Azure AD als identiteitssysteem gebruikt, kunt u Azure AD-verificatie op basis van gebruikers gebruiken in uw app. 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 wordt u aangeraden 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 in uw clienttoepassing worden ingesloten.

Zie hier voor gedetailleerde instructies en informatie.

In alle volgende voorbeelden wordt de client samengesteld 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 rendering wordt het ten zeerste aanbevolen dat u de dichtstbijzijnde regio kiest voor de apparaten die gebruikmaken van de service. De tijd die nodig is om met de server te communiceren, heeft 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 clientgeheimverificatie 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 apparaatcodeverificatie 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 apparaatcodeverificatiestroom.

Interactieve verificatie met DefaultAzureCredential

Gebruik het DefaultAzureCredential-object met includeInteractiveCredentials: true om de standaardstroom voor interactieve verificatie 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 die u eerder hebt 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);

Sleutelbegrippen

RemoteRenderingClient

De RemoteRenderingClient is de clientbibliotheek die wordt gebruikt voor toegang tot 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 samengesteld zoals beschreven in de sectie De client verifiëren. In het volgende codefragment wordt beschreven hoe u 'box.fbx' aanvraagt, die is gevonden 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 organiseren en hoe u een asset converteert 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' gedraagt zich dus erg 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 nodig heeft tot andere bestanden. Om alles overzichtelijk 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 parameter voor het uitvoerbestand in uitvoeropties.

De uitvoer ophalen wanneer een assetconversie is voltooid

Het converteren van een asset kan overal van 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 wordt uitgevoerd vanaf de plaats waar de vorige was gebleven:

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

Lijstconversies

U kunt informatie over uw conversies ophalen met behulp van de methode getConversions. Deze methode kan conversies retourneren die nog moeten worden gestart, conversies die worden uitgevoerd en conversies die zijn voltooid. In dit voorbeeld vermelden we alleen de uitvoer-URI's van geslaagde conversies die in 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 samengesteld zoals beschreven in de sectie De client verifiëren. In het volgende fragment wordt beschreven hoe u een nieuwe renderingsessie kunt aanvragen.

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 wordt uitgevoerd vanaf de plaats waar de vorige was 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 query's kunt uitvoeren op de huidige eigenschappen en vervolgens de lease kunt uitbreiden als deze binnenkort verloopt.

OPMERKING: De runtime-SDK's bieden deze functionaliteit ook en in veel typische scenario's zou u ze gebruiken om de sessielease uit te breiden.

/// 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 methode getSessions. Deze methode kan sessies retourneren die nog moeten worden gestart en sessies die gereed 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 een opgegeven id gestopt.

client.endSession(sessionId);

Probleemoplossing

Logboekregistratie

Het inschakelen van logboekregistratie kan helpen nuttige informatie over fouten te ontdekken. Als u een logboek met HTTP-aanvragen en -antwoorden wilt zien, stelt u de omgevingsvariabele AZURE_LOG_LEVEL in op info. U kunt logboekregistratie ook tijdens runtime inschakelen door setLogLevel aan te roepen 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 algemene probleemoplossingsadvies over 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 de aangevraagde bewerking is mogelijk niet gelukt. 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 draagt een RemoteRenderingServiceError met details. Zodra de conversieservice het bestand kan verwerken, wordt een <assetName->.result.json-bestand naar de uitvoercontainer geschreven. Als de invoerasset ongeldig is, bevat dat bestand een gedetailleerdere beschrijving van het probleem.

Op dezelfde manier heeft de sessie soms een foutstatus wanneer een sessie wordt aangevraagd. De methode startSessionOperation retourneert een RenderingSession-object, maar dat object heeft de status Error en draagt een RemoteRenderingServiceError met details.

Volgende stappen

Bijdragen

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

indrukken