Dela via

Azure Remote Rendering-klientbibliotek för JavaScript – version 1.0.0-beta.1

  • Artikel

Azure Remote Rendering (ARR) är en tjänst som gör att du kan återge interaktivt 3D-innehåll av hög kvalitet i molnet och strömma det i realtid till enheter, till exempel HoloLens 2.

Denna SDK erbjuder funktioner för att konvertera tillgångar till det format som förväntas av körningen, och även för att hantera livslängden för fjärrrenderingssessioner.

Obs! När en session körs ansluter ett klientprogram till den med någon av "runtime SDK:erna". Dessa SDK:er är utformade för att på bästa sätt stödja behoven hos ett interaktivt program som gör 3d-återgivning. De finns i (.net eller (C++).

Produktdokumentation

Komma igång

Miljöer som stöds för närvarande

Förutsättningar

Du behöver en Azure-prenumeration och ett Azure Remote Rendering-konto för att kunna använda det här paketet.

Installera @azure/mixed-reality-remote-rendering-paketet

Installera mallklientbiblioteket för JavaScript med npm:

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

Stöd för webbläsare

JavaScript-paket

Om du vill använda det här klientbiblioteket i webbläsaren måste du först använda en bundler. Mer information om hur du gör detta finns i vår paketeringsdokumentation.

CORS

Det här biblioteket kan inte användas för att göra direkta anrop till Azure Remote Rendering-tjänsten från en webbläsare. Mer information finns i det här dokumentet.

Autentisera klienten

För att skapa en fjärrrenderingsklient krävs ett autentiserat konto och en fjärråtergivningsslutpunkt. För ett konto som skapats i regionen eastus har kontodomänen formuläret "eastus.mixedreality.azure.com". Det finns flera olika former av autentisering:

  • Kontonyckelautentisering
    • Med kontonycklar kan du komma igång snabbt med azure remote rendering. Men innan du distribuerar programmet till produktion rekommenderar vi att du uppdaterar appen så att den använder Azure AD-autentisering.
  • Azure Active Directory-tokenautentisering (AD)
    • Om du skapar ett företagsprogram och ditt företag använder Azure AD som sitt identitetssystem kan du använda användarbaserad Azure AD-autentisering i din app. Sedan beviljar du åtkomst till dina Azure Remote Rendering-konton med hjälp av dina befintliga Azure AD-säkerhetsgrupper. Du kan också bevilja åtkomst direkt till användare i din organisation.
    • Annars rekommenderar vi att du hämtar Azure AD-token från en webbtjänst som stöder din app. Vi rekommenderar den här metoden för produktionsprogram eftersom du kan undvika att bädda in autentiseringsuppgifterna i klientprogrammet.

Mer information finns i här.

I alla följande exempel konstrueras klienten med en remoteRenderingEndpoint. De tillgängliga slutpunkterna motsvarar regioner, och valet av slutpunkt avgör i vilken region tjänsten utför sitt arbete. Ett exempel är https://remoterendering.eastus2.mixedreality.azure.com.

Obs! För konvertering av tillgångar är det bättre att välja en region nära lagringen som innehåller tillgångarna.

Obs! För återgivning rekommenderar vi starkt att du väljer den region som är närmast enheterna som använder tjänsten. Den tid det tar att kommunicera med servern påverkar upplevelsens kvalitet.

Autentisera med kontonyckelautentisering

Använd AccountKeyCredential-objektet för att använda en kontoidentifierare och kontonyckel för att autentisera:

const credential = new AzureKeyCredential(accountKey);

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

Autentisera med en AAD-klienthemlighet

Använd ClientSecretCredential-objektet för att utföra klienthemlighetsautentisering.

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

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

Autentisera en användare med enhetskodautentisering

Använd DeviceCodeCredential-objektet för att utföra enhetskodautentisering.

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

Mer information om hur du använder autentiseringsflödet för enhetskod finns i här.

Interaktiv autentisering med DefaultAzureCredential

Använd DefaultAzureCredential-objektet med includeInteractiveCredentials: true för att använda standardflödet för interaktiv autentisering:

let credential = new DefaultAzureCredential();

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

Autentisera med en statisk åtkomsttoken

Du kan skicka en Mixed Reality-åtkomsttoken som en AccessToken som tidigare hämtats från Mixed Reality STS-tjänsten som ska användas med ett Mixed Reality-klientbibliotek:

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

Viktiga begrepp

RemoteRenderingClient

RemoteRenderingClient är det klientbibliotek som används för att komma åt RemoteRenderingService. Den innehåller metoder för att skapa och hantera tillgångskonverteringar och renderingssessioner.

Exempel

Konvertera en enkel tillgång

Vi antar att en RemoteRenderingClient har konstruerats enligt beskrivningen i avsnittet Autentisera klienten. Följande kodfragment beskriver hur du begär att "box.fbx", som finns i blobcontainerns rot vid den angivna URI:n, konverteras.

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

Utdatafilerna placeras bredvid indatatillgången.

Konvertera en mer komplex tillgång

Tillgångar kan referera till andra filer och blobcontainrar kan innehålla filer som tillhör många olika tillgångar. I det här exemplet visar vi hur prefix kan användas för att organisera dina blobar och hur du konverterar en tillgång för att ta hänsyn till den organisationen. Anta att blobcontainern på inputStorageUrl innehåller många filer, inklusive "Bicycle/bicycle.gltf", "Bicycle/bicycle.bin" och "Bicycle/saddleTexture.jpg". (Prefixet "Bicycle" fungerar alltså mycket som en mapp.) Vi vill konvertera glTF så att den har åtkomst till de andra filerna som delar prefixet, utan att konverteringstjänsten behöver komma åt andra filer. För att hålla saker och ting snygga vill vi också att utdatafilerna ska skrivas till en annan lagringscontainer och få ett vanligt prefix: "ConvertedBicycle". Koden är följande:

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

Obs! När ett prefix anges i indataalternativen antas indatafilparametern vara relativ till prefixet. Samma sak gäller för utdatafilparametern i utdataalternativ.

Hämta utdata när en tillgångskonvertering har slutförts

Konvertering av en tillgång kan ta allt från sekunder till timmar. Den här koden använder conversionPoller som returneras av beginConversion för att avsöka regelbundet tills konverteringen har slutförts eller misslyckats. Standard avsökningsperioden är 10 sekunder.

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

Observera att tillståndet för en AssetConversionPollerLike kan serialiseras genom att anropa conversionPoller.toString(). Det värdet kan senare skickas till beginConversion som ett resumeFrom värde för att skapa en ny poller som fortsätter från där den tidigare slutade:

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

Lista konverteringar

Du kan få information om dina konverteringar med hjälp av metoden getConversions. Den här metoden kan returnera konverteringar som ännu inte har startats, konverteringar som körs och konverteringar som har slutförts. I det här exemplet visar vi bara utdata-URI:er för lyckade konverteringar som startades under den senaste dagen.

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

Skapa en session

Vi antar att en RemoteRenderingClient har konstruerats enligt beskrivningen i avsnittet Autentisera klienten. Följande kodfragment beskriver hur du begär att en ny återgivningssession startas.

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

Observera att tillståndet för en RenderingSessionPollerLike kan serialiseras genom att anropa toString(). Det värdet kan senare skickas till beginSession som ett resumeFrom värde, för att konstruera en ny poller som fortsätter från där den tidigare slutade:

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

Förlänga lånetiden för en session

Om en session närmar sig sin maximala lånetid, men du vill hålla den vid liv, måste du göra ett anrop för att öka den maximala lånetiden. Det här exemplet visar hur du frågar efter de aktuella egenskaperna och sedan förlänger lånet om det snart upphör att gälla.

Obs! Runtime-SDK:erna erbjuder också den här funktionen, och i många typiska scenarier använder du dem för att utöka sessionslånet.

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

Lista sessioner

Du kan få information om dina sessioner med hjälp av metoden getSessions. Den här metoden kan returnera sessioner som ännu inte har startats och sessioner som är klara.

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

Stoppa en session

Följande kod stoppar en session som körs med angivet ID.

client.endSession(sessionId);

Felsökning

Skogsavverkning

Aktivering av loggning kan hjälpa dig att hitta användbar information om fel. Om du vill se en logg med HTTP-begäranden och svar anger du AZURE_LOG_LEVEL miljövariabeln till info. Du kan också aktivera loggning vid körning genom att anropa setLogLevel i @azure/logger:

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

setLogLevel("info");

Felsökning av Fjärrrendering i Azure

Allmänna felsökningsråd om Azure Remote Rendering finns i sidan Felsökning för fjärrrendering på docs.microsoft.com.

Klientmetoderna utlöser undantag om begäran inte kan göras. När det gäller både konverteringar och sessioner kan begärandena dock lyckas, men den begärda åtgärden kanske inte lyckas. I det här fallet utlöses inget undantag, men de returnerade objekten kan inspekteras för att förstå vad som hände.

Om tillgången i en konvertering är ogiltig returnerar konverteringsåtgärden ett AssetConversion-objekt med statusen Misslyckad och med en RemoteRenderingServiceError med information. När konverteringstjänsten kan bearbeta filen skrivs en <assetName->.result.json fil till utdatacontainern. Om indatatillgången är ogiltig innehåller den filen en mer detaljerad beskrivning av problemet.

På samma sätt, ibland när en session begärs, hamnar sessionen i ett feltillstånd. Metoden startSessionOperation returnerar ett RenderingSession-objekt, men objektet har statusen Fel och har en RemoteRenderingServiceError med information.

Nästa steg

Bidragande

Om du vill bidra till det här biblioteket kan du läsa bidragsguide för att lära dig mer om hur du skapar och testar koden.

visningar