Freigeben über

Azure Remote Rendering-Clientbibliothek für JavaScript– Version 1.0.0-beta.1

  • Artikel

Azure Remote Rendering (ARR) ist ein Dienst, mit dem Sie interaktive 3D-Inhalte in der Cloud in hoher Qualität rendern und in Echtzeit an Geräte streamen können, z. B. HoloLens 2.

Dieses SDK bietet Funktionen zum Konvertieren von Ressourcen in das von der Runtime erwartete Format und zum Verwalten der Lebensdauer von Remoterenderingsitzungen.

HINWEIS: Sobald eine Sitzung ausgeführt wird, stellt eine Clientanwendung mithilfe eines der "Laufzeit-SDKs" eine Verbindung mit ihr her. Diese SDKs sind so konzipiert, dass sie die Anforderungen einer interaktiven Anwendung mit 3D-Rendering optimal unterstützen. Sie sind in (.net oder (C++) verfügbar.

Produktdokumentation

Erste Schritte

Die derzeitig unterstützten Umgebungen

Voraussetzungen

Sie benötigen ein Azure-Abonnement und ein Azure Remote Rendering-Konto, um dieses Paket verwenden zu können.

Installieren Sie das Paket @azure/mixed-reality-remote-rendering.

Installieren Sie die Vorlagenclientbibliothek für JavaScript mit npm:

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

Browserunterstützung

JavaScript-Paket

Um diese Clientbibliothek im Browser verwenden zu können, müssen Sie zunächst einen Bundler verwenden. Ausführliche Informationen dazu finden Sie in unserer Bündelungsdokumentation.

CORS

Diese Bibliothek kann nicht für direkte Aufrufe des Azure Remote Rendering-Diensts über einen Browser verwendet werden. Weitere Informationen finden Sie in diesem Dokument .

Authentifizieren des Clients

Das Erstellen eines Remoterenderingclients erfordert ein authentifiziertes Konto und einen Remoterenderingendpunkt. Für ein Konto, das in der Region eastus erstellt wurde, weist die Kontodomäne das Format "eastus.mixedreality.azure.com" auf. Es gibt verschiedene Arten der Authentifizierung:

  • Kontoschlüsselauthentifizierung
    • Kontoschlüssel ermöglichen Ihnen den schnellen Einstieg in die Verwendung von Azure Remote Rendering. Aber bevor Sie Ihre Anwendung in der Produktionsumgebung bereitstellen, empfiehlt es sich, dass Sie Ihre App für die Verwendung von Azure AD-Authentifizierung aktualisieren.
  • Azure Active Directory-Tokenauthentifizierung (AD)
    • Wenn Sie eine Unternehmensanwendung entwickeln und Ihr Unternehmen Azure AD als Identitätssystem verwendet, können Sie die benutzerbasierte Azure AD-Authentifizierung in Ihrer App verwenden. Anschließend gewähren Sie Mithilfe Ihrer vorhandenen Azure AD-Sicherheitsgruppen Zugriff auf Ihre Azure Remote Rendering-Konten. Sie können Benutzern in Ihrer Organisation Zugriff auch direkt gewähren.
    • Andernfalls empfiehlt es sich, Azure AD-Token von einem Webdienst abzurufen, der Ihre App unterstützt. Wir empfehlen diese Methode für Produktionsanwendungen, weil diese es Ihnen ermöglicht, die Einbettung der Anmeldeinformationen für den Zugriff auf Azure Spatial Anchors in Ihre Clientanwendung zu vermeiden.

Ausführliche Anweisungen und Informationen finden Sie hier .

In allen folgenden Beispielen wird der Client mit einem remoteRenderingEndpointerstellt. Die verfügbaren Endpunkte entsprechen regionen, und die Auswahl des Endpunkts bestimmt die Region, in der der Dienst seine Arbeit ausführt. z. B. https://remoterendering.eastus2.mixedreality.azure.com.

HINWEIS: Für die Konvertierung von Ressourcen empfiehlt es sich, eine Region in der Nähe des Speichers zu wählen, der die Ressourcen enthält.

HINWEIS: Für das Rendern wird dringend empfohlen, dass Sie die Region auswählen, die den Geräten, die den Dienst verwenden, am nächsten liegt. Die Für die Kommunikation mit dem Server benötigte Zeit wirkt sich auf die Qualität der Benutzeroberfläche aus.

Authentifizieren mit Kontoschlüsselauthentifizierung

Verwenden Sie das AccountKeyCredential -Objekt, um einen Kontobezeichner und einen Kontoschlüssel für die Authentifizierung zu verwenden:

const credential = new AzureKeyCredential(accountKey);

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

Authentifizieren mit einem geheimen AAD-Clientschlüssel

Verwenden Sie das -Objekt, um die ClientSecretCredential geheime Clientauthentifizierung durchzuführen.

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

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

Authentifizieren eines Benutzers mithilfe der Gerätecodeauthentifizierung

Verwenden Sie das DeviceCodeCredential -Objekt, um die Gerätecodeauthentifizierung durchzuführen.

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

Weitere Informationen zum Verwenden des Authentifizierungsablaufs für Gerätecode finden Sie hier .

Interaktive Authentifizierung mit DefaultAzureCredential

Verwenden Sie das -Objekt mitincludeInteractiveCredentials: true, um den DefaultAzureCredential standardmäßigen interaktiven Authentifizierungsfluss zu verwenden:

let credential = new DefaultAzureCredential();

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

Authentifizieren mit einem statischen Zugriffstoken

Sie können ein Mixed Reality-Zugriffstoken als zuvor AccessToken aus dem Mixed Reality STS-Dienst abgerufenen übergeben, um mit einer Mixed Reality Clientbibliothek verwendet zu werden:

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

Wichtige Begriffe

RemoteRenderingClient

ist RemoteRenderingClient die Clientbibliothek, die für den Zugriff auf den RemoteRenderingService verwendet wird. Es bietet Methoden zum Erstellen und Verwalten von Ressourcenkonvertierungen und Renderingsitzungen.

Beispiele

Konvertieren eines einfachen Medienobjekts

Es wird davon ausgegangen, dass ein RemoteRenderingClient wie im Abschnitt Authentifizieren des Clients beschrieben erstellt wurde. Der folgende Codeausschnitt beschreibt, wie Sie anfordern, dass "box.fbx", das sich am Stamm des Blobcontainers am angegebenen URI befindet, konvertiert wird.

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

Die Ausgabedateien werden neben dem Eingabeobjekt platziert.

Konvertieren eines komplexeren Medienobjekts

Ressourcen können auf andere Dateien verweisen, und Blobcontainer können Dateien enthalten, die zu vielen verschiedenen Ressourcen gehören. In diesem Beispiel wird gezeigt, wie Präfixe verwendet werden können, um Ihre Blobs zu organisieren und wie Sie ein Medienobjekt konvertieren, um diese Organisation zu berücksichtigen. Angenommen, der Blobcontainer bei inputStorageUrl enthält viele Dateien, einschließlich "Bicycle/bicycle.gltf", "Bicycle/bicycle.bin" und "Bicycle/saddleTexture.jpg". (Das Präfix "Bicycle" verhält sich also sehr wie ein Ordner.) Wir möchten den glTF konvertieren, sodass er Zugriff auf die anderen Dateien hat, die das Präfix gemeinsam nutzen, ohne dass der Konvertierungsdienst auf andere Dateien zugreifen muss. Zur Übersichtlichkeit möchten wir auch, dass die Ausgabedateien in einen anderen Speichercontainer geschrieben werden und ein gemeinsames Präfix erhalten: "ConvertedBicycle". Der Code lautet wie folgt:

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

HINWEIS: Wenn in den Eingabeoptionen ein Präfix angegeben wird, wird angenommen, dass der Parameter der Eingabedatei relativ zu diesem Präfix ist. Gleiches gilt für den Ausgabedateiparameter in den Ausgabeoptionen.

Abrufen der Ausgabe, wenn eine Medienobjektkonvertierung abgeschlossen ist

Das Konvertieren eines Medienobjekts kann zwischen Sekunden und Stunden dauern. Dieser Code verwendet den von beginConversion zurückgegebenen conversionPoller, um regelmäßig abzufragen, bis die Konvertierung abgeschlossen oder fehlgeschlagen ist. Der Standardabrufzeitraum beträgt 10 Sekunden.

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

Beachten Sie, dass der Status eines AssetConversionPollerLike durch Aufrufen von conversionPoller.toString() serialisiert werden kann. Dieser Wert kann später als Wert an beginConversion übergeben werden, um einen resumeFrom neuen Poller zu erstellen, der dort weiter ausgeführt wird, wo der vorherige aufgehört hat:

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

Auflisten von Konvertierungen

Mit der getConversions -Methode können Sie Informationen zu Ihren Konvertierungen abrufen. Diese Methode kann Konvertierungen zurückgeben, die noch gestartet werden müssen, Konvertierungen, die ausgeführt werden, und Konvertierungen, die abgeschlossen sind. In diesem Beispiel werden nur die Ausgabe-URIs der erfolgreichen Konvertierungen aufgelistet, die am letzten Tag gestartet wurden.

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

Erstellen einer Sitzung

Es wird davon ausgegangen, dass ein RemoteRenderingClient wie im Abschnitt Authentifizieren des Clients beschrieben erstellt wurde. Der folgende Codeausschnitt beschreibt, wie Sie anfordern, dass eine neue Renderingsitzung gestartet wird.

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

Beachten Sie, dass der Zustand einer RenderingSessionPollerLike durch Aufrufen von toString() serialisiert werden kann. Dieser Wert kann später als Wert an beginSession übergeben werden, um einen resumeFrom neuen Poller zu erstellen, der dort weiter ausgeführt wird, wo der vorherige aufgehört hat:

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

Verlängern der Leasezeit einer Sitzung

Wenn sich eine Sitzung ihrer maximalen Leasezeit nähert, sie aber am Leben erhalten soll, müssen Sie einen Aufruf tätigen, um die maximale Leasezeit zu erhöhen. In diesem Beispiel wird gezeigt, wie Sie die aktuellen Eigenschaften abfragen und dann die Lease erweitern, wenn sie bald abläuft.

HINWEIS: Die Laufzeit-SDKs bieten diese Funktionalität ebenfalls, und in vielen typischen Szenarien würden Sie sie verwenden, um die Sitzungsleases zu erweitern.

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

Listensitzungen

Mit der getSessions -Methode können Sie Informationen zu Ihren Sitzungen abrufen. Diese Methode gibt möglicherweise Sitzungen zurück, die noch gestartet werden müssen, und Sitzungen, die bereit sind.

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

Beenden einer Sitzung

Der folgende Code beendet eine ausgeführte Sitzung mit der angegebenen ID.

client.endSession(sessionId);

Problembehandlung

Protokollierung

Die Aktivierung der Protokollierung kann hilfreiche Informationen über Fehler aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die Umgebungsvariable AZURE_LOG_LEVEL auf info fest. Alternativ kann die Protokollierung zur Laufzeit aktiviert werden, indem Sie setLogLevel in @azure/logger aufrufen:

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

setLogLevel("info");

Problembehandlung in Azure Remote Rendering

Allgemeine Hinweise zur Problembehandlung in Bezug auf Azure Remote Rendering finden Sie auf der Seite Problembehandlung für Remoterendering auf docs.microsoft.com.

Die Clientmethoden lösen Ausnahmen aus, wenn die Anforderung nicht gestellt werden kann. Bei Konvertierungen und Sitzungen können die Anforderungen jedoch erfolgreich sein, aber der angeforderte Vorgang ist möglicherweise nicht erfolgreich. In diesem Fall wird keine Ausnahme ausgelöst, aber die zurückgegebenen Objekte können überprüft werden, um zu verstehen, was passiert ist.

Wenn das Objekt in einer Konvertierung ungültig ist, gibt der Konvertierungsvorgang ein AssetConversion-Objekt mit dem Status Failed zurück und enthält einen RemoteRenderingServiceError mit Details. Sobald der Konvertierungsdienst die Datei verarbeiten kann, wird eine <datei assetName.result.json> in den Ausgabecontainer geschrieben. Wenn das Eingabeobjekt ungültig ist, enthält diese Datei eine ausführlichere Beschreibung des Problems.

Auf ähnliche Weise endet die Sitzung manchmal in einem Fehlerzustand, wenn eine Sitzung angefordert wird. Die startSessionOperation-Methode gibt ein RenderingSession-Objekt zurück, aber dieses Objekt verfügt über den Fehlerstatus und enthält einen RemoteRenderingServiceError mit Details.

Nächste Schritte

Mitwirken

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie die Anleitung für Mitwirkende, um mehr darüber zu erfahren, wie Sie den Code erstellen und testen können.

Aufrufe