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 qualitativ hochwertige, interaktive 3D-Inhalte in der Cloud rendern und in Echtzeit auf Geräte streamen können, z. B. holoLens 2.

Dieses SDK bietet Funktionen zum Konvertieren von Ressourcen in das von der Laufzeit 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 darauf ausgelegt, die Anforderungen einer interaktiven Anwendung, die 3D-Rendering ausführt, optimal zu unterstützen. Sie stehen in (.net oder (C++-) zur Verfügung.

Produktdokumentation

Erste Schritte

Derzeit unterstützte Umgebungen

Voraussetzungen

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

Installieren des @azure/mixed-reality-remote-rendering-Pakets

Installieren Sie die Vorlagenclientbibliothek für JavaScript mit npm:

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

Browserunterstützung

JavaScript-Bündel

Um diese Clientbibliothek im Browser zu verwenden, müssen Sie zuerst einen Bundler verwenden. Ausführliche Informationen dazu finden Sie in unserer Bündelungsdokumentation.

CORS

Diese Bibliothek kann nicht verwendet werden, um direkte Aufrufe an den Azure Remote Rendering-Dienst über einen Browser zu tätigen. Weitere Informationen finden Sie in diesem Dokument.

Authentifizieren des Clients

Für das Erstellen eines Remoterenderingclients ist ein authentifiziertes Konto und ein Remoterenderingendpunkt erforderlich. Für ein Konto, das in der Ostregion erstellt wurde, hat die Kontodomäne das Formular "eastus.mixedreality.azure.com". Es gibt verschiedene Authentifizierungsformen:

  • Kontoschlüsselauthentifizierung
    • Mit Kontoschlüsseln können Sie schnell mit der Verwendung von Azure Remote Rendering beginnen. Bevor Sie Ihre Anwendung jedoch in der Produktion bereitstellen, sollten Sie Ihre App so aktualisieren, dass sie die Azure AD-Authentifizierung verwendet.
  • Azure Active Directory (AD)-Tokenauthentifizierung
    • Wenn Sie eine Unternehmensanwendung erstellen 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 den Zugriff auch direkt auf Benutzer in Ihrer Organisation gewähren.
    • Andernfalls wird empfohlen, Azure AD-Token von einem Webdienst abzurufen, der Ihre App unterstützt. Wir empfehlen diese Methode für Produktionsanwendungen, da Sie das Einbetten der Anmeldeinformationen in Ihre Clientanwendung vermeiden können.

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. Ein Beispiel ist https://remoterendering.eastus2.mixedreality.azure.com.

HINWEIS: Zum Konvertieren von Ressourcen empfiehlt es sich, einen Bereich in der Nähe des Speichers zu wählen, der die Ressourcen enthält.

HINWEIS: Für das Rendern wird dringend empfohlen, den nächstgelegenen Bereich für die Geräte mit dem Dienst zu wählen. Die zeitaufwand für die Kommunikation mit dem Server wirkt sich auf die Qualität der Erfahrung aus.

Authentifizieren mit Kontoschlüsselauthentifizierung

Verwenden Sie das AccountKeyCredential-Objekt, um einen Kontobezeichner und einen Kontoschlüssel zur 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 ClientSecretCredential-Objekt, um die geheime Clientschlüsselauthentifizierung auszufü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 auszufü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 zur Verwendung des Gerätecodeauthentifizierungsflusses finden Sie hier.

Interaktive Authentifizierung mit DefaultAzureCredential

Verwenden Sie das DefaultAzureCredential-Objekt mit includeInteractiveCredentials: true, um den 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 AccessToken übergeben, die zuvor aus dem Mixed Reality-STS-Dienst abgerufen, das mit einer Mixed Reality-Clientbibliothek verwendet werden soll:

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

Schlüsselkonzepte

RemoteRenderingClient

Die RemoteRenderingClient ist die Clientbibliothek, die für den Zugriff auf remoteRenderingService verwendet wird. Es stellt Methoden zum Erstellen und Verwalten von Objektkonvertierungen und Renderingsitzungen bereit.

Beispiele

Konvertieren einer einfachen Ressource

Es wird davon ausgegangen, dass ein RemoteRenderingClient erstellt wurde, wie im Abschnitt Authentifizieren des Client- beschrieben. Der folgende Codeausschnitt beschreibt, wie "box.fbx" angefordert wird, die am Stamm des Blobcontainers am angegebenen URI gefunden 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 der Eingaberessource platziert.

Konvertieren einer komplexeren Ressource

Objekte können auf andere Dateien verweisen, und BLOB-Container können Dateien enthalten, die zu vielen verschiedenen Ressourcen gehören. In diesem Beispiel wird gezeigt, wie Präfixe zum Organisieren Ihrer Blobs und zum Konvertieren einer Ressource verwendet werden können, um diese Organisation zu berücksichtigen. Gehen Sie davon aus, dass der BLOB-Container bei inputStorageUrl viele Dateien enthält, darunter "Bicycle/bicycle.gltf", "Bicycle/bicycle.bin" und "Bicycle/saddleTexture.jpg". (Das Präfix "Fahrrad" verhält sich also sehr wie ein Ordner.) Wir möchten das glTF konvertieren, damit er Zugriff auf die anderen Dateien hat, die das Präfix gemeinsam nutzen, ohne dass der Konvertierungsdienst auf andere Dateien zugreifen muss. Um die Dinge übersichtlich zu halten, möchten wir auch, dass die Ausgabedateien in einen anderen Speichercontainer geschrieben werden und einem allgemeinen Präfix: "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 davon ausgegangen, dass der Parameter der Eingabedatei relativ zu diesem Präfix ist. Das gleiche gilt für den Ausgabedateiparameter in Ausgabeoptionen.

Abrufen der Ausgabe, wenn eine Objektkonvertierung abgeschlossen ist

Das Konvertieren einer Ressource kann von Sekunden zu Stunden dauern. Dieser Code verwendet den conversionPoller, der von beginConversion zurückgegeben wird, um regelmäßig abzufragen, bis die Konvertierung abgeschlossen oder fehlgeschlagen ist. Der Standardmäßige Abrufzeitraum 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 resumeFrom-Wert in beginConversion übergeben werden, um einen neuen Poller zu erstellen, der von dem aus das frühere abgehört hat:

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

Listenkonvertierungen

Mithilfe der getConversions-Methode können Sie Informationen zu Ihren Konvertierungen abrufen. Diese Methode kann Konvertierungen zurückgeben, die noch zu starten sind, Konvertierungen, die ausgeführt werden, und Konvertierungen, die abgeschlossen sind. In diesem Beispiel werden nur die Ausgabe-URIs der erfolgreichen Konvertierungen aufgeführt, 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 erstellt wurde, wie im Abschnitt Authentifizieren des Client- beschrieben. Im folgenden Codeausschnitt wird beschrieben, 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 resumeFrom Wert an "beginSession" übergeben werden, um einen neuen Poller zu erstellen, der an der Stelle weiter oben 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 aktiv halten möchten, müssen Sie einen Aufruf tätigen, um die maximale Leasezeit zu erhöhen. In diesem Beispiel wird gezeigt, wie die aktuellen Eigenschaften abfragt und dann die Lease verlängert wird, wenn sie bald abläuft.

HINWEIS: Die Laufzeit-SDKs bieten diese Funktionalität auch an, und in vielen typischen Szenarien würden Sie sie verwenden, um die Sitzungsleasing 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 });
  }
}

Sitzungen auflisten

Mithilfe der getSessions-Methode können Sie Informationen zu Ihren Sitzungen abrufen. Diese Methode kann Sitzungen zurückgeben, die noch nicht gestartet wurden, 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 laufende Sitzung mit einer angegebenen ID.

client.endSession(sessionId);

Fehlerbehebung

Protokollierung

Das Aktivieren der Protokollierung kann hilfreiche Informationen zu Fehlern aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die AZURE_LOG_LEVEL Umgebungsvariable auf infofest. Alternativ kann die Protokollierung zur Laufzeit durch Aufrufen von setLogLevel im @azure/loggeraktiviert werden:

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

setLogLevel("info");

Problembehandlung bei Azure Remote Rendering

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

Die Clientmethoden lösen Ausnahmen aus, wenn die Anforderung nicht erfolgen kann. Im Falle von Konvertierungen und Sitzungen können die Anforderungen jedoch erfolgreich sein, der angeforderte Vorgang ist jedoch 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 die Ressource in einer Konvertierung ungültig ist, gibt der Konvertierungsvorgang ein AssetConversion-Objekt mit einem Fehlerstatus zurück und trägt einen RemoteRenderingServiceError mit Details. Sobald der Konvertierungsdienst die Datei verarbeiten kann, wird eine <assetName->.result.json Datei in den Ausgabecontainer geschrieben. Wenn die Eingaberessource ungültig ist, enthält diese Datei eine detailliertere Beschreibung des Problems.

In ähnlicher Weise endet die Sitzung, wenn eine Sitzung angefordert wird, in einem Fehlerzustand. Die startSessionOperation-Methode gibt ein RenderingSession-Objekt zurück, dieses Objekt weist jedoch einen Fehlerstatus auf und trägt einen RemoteRenderingServiceError mit Details.

Nächste Schritte

Beitragend

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie bitte den mitwirkenden Leitfaden, um mehr über das Erstellen und Testen des Codes zu erfahren.

Aufrufe