Azure Remote Rendering-Clientbibliothek für Java– Version 1.1.23

Artikel
10/21/2023

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 "Runtime-SDKs" eine Verbindung mit der Sitzung her. Diese SDKs sind so konzipiert, dass sie die Anforderungen einer interaktiven Anwendung mit 3D-Rendering optimal unterstützen. Sie sind in .NET und C++ verfügbar.

Quellcode | API-Referenzdokumentation | Produktdokumentation

Erste Schritte

Voraussetzungen

Java Development Kit (JDK), Version 8 oder höher
Azure-Abonnement
Azure Remote Rendering Konto, um dieses Paket zu verwenden.

Einschließen des Pakets

BOM-Datei einfügen

Fügen Sie azure-sdk-bom in Ihr Projekt ein, um von der Allgemeinverfügbarkeitsversion der Bibliothek abhängig zu sein. Ersetzen Sie im folgenden Codeausschnitt den Platzhalter {bom_version_to_target} durch die Versionsnummer. Weitere Informationen zur BOM finden Sie in der INFODATEI FÜR AZURE SDK-STÜCKLISTEN.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

und fügen Sie dann die direkte Abhängigkeit wie unten dargestellt ohne das Versionstag in den Abschnitt abhängigkeiten ein.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-mixedreality-remoterendering</artifactId>
  </dependency>
</dependencies>

Direkte Abhängigkeiten einfügen

Hinweis: Diese Version zielt auf die Azure Remote Rendering-Dienst-API-Version v2021-01-01 ab.

Fügen Sie die folgende Maven-Abhängigkeit hinzu:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-mixedreality-remoterendering</artifactId>
    <version>1.1.23</version>
</dependency>

Authentifizieren des Clients

Zum Erstellen eines Remoterenderingclients sind ein authentifiziertes Konto und ein Remoterenderingendpunkt erforderlich. Ein Konto besteht aus seiner accountId und einer Kontodomäne. Für ein Konto, das in der Region eastus erstellt wurde, weist die Kontodomäne das Format "eastus.mixedreality.azure.com" auf. Es gibt mehrere 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 RemoteRenderingClientBuilder -Objekt erstellt. Die Parameter sind immer identisch, mit Ausnahme des Anmeldeinformationsobjekts, das in jedem Beispiel erläutert wird. Der remoteRenderingEndpoint Parameter ist eine URL, die die Region bestimmt, 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: Zum 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 AzureKeyCredential -Objekt, um einen Kontobezeichner und einen Kontoschlüssel für die Authentifizierung zu verwenden:

AzureKeyCredential credential = new AzureKeyCredential(environment.getAccountKey());

RemoteRenderingClient client = new RemoteRenderingClientBuilder()
    .accountId(environment.getAccountId())
    .accountDomain(environment.getAccountDomain())
    .endpoint(environment.getServiceEndpoint())
    .credential(credential)
    .buildClient();

Authentifizieren mit einem geheimen AAD-Clientschlüssel

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

ClientSecretCredential credential = new ClientSecretCredentialBuilder()
    .tenantId(environment.getTenantId())
    .clientId(environment.getClientId())
    .clientSecret(environment.getClientSecret())
    .authorityHost("https://login.microsoftonline.com/" + environment.getTenantId())
    .build();

RemoteRenderingClient client = new RemoteRenderingClientBuilder()
    .accountId(environment.getAccountId())
    .accountDomain(environment.getAccountDomain())
    .endpoint(environment.getServiceEndpoint())
    .credential(credential)
    .buildClient();

Authentifizieren eines Benutzers mithilfe der Gerätecodeauthentifizierung

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

DeviceCodeCredential credential = new DeviceCodeCredentialBuilder()
    .challengeConsumer((DeviceCodeInfo deviceCodeInfo) -> {
        logger.info(deviceCodeInfo.getMessage());
    })
    .clientId(environment.getClientId())
    .tenantId(environment.getTenantId())
    .authorityHost("https://login.microsoftonline.com/" + environment.getTenantId())
    .build();

RemoteRenderingClient client = new RemoteRenderingClientBuilder()
    .accountId(environment.getAccountId())
    .accountDomain(environment.getAccountDomain())
    .endpoint(environment.getServiceEndpoint())
    .credential(credential)
    .buildClient();

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

Interaktive Authentifizierung mit DefaultAzureCredential

Verwenden Sie das DefaultAzureCredential -Objekt:

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();

RemoteRenderingClient client = new RemoteRenderingClientBuilder()
    .accountId(environment.getAccountId())
    .accountDomain(environment.getAccountDomain())
    .endpoint(environment.getServiceEndpoint())
    .credential(credential)
    .buildClient();

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.
AccessToken accessToken = getMixedRealityAccessTokenFromWebService();

RemoteRenderingClient client = new RemoteRenderingClientBuilder()
    .accountId(environment.getAccountId())
    .accountDomain(environment.getAccountDomain())
    .endpoint(environment.getServiceEndpoint())
    .accessToken(accessToken)
    .buildClient();

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
Konvertieren eines komplexeren Medienobjekts
Abrufen der Ausgabe, wenn eine Medienobjektkonvertierung abgeschlossen ist
Auflisten von Konvertierungen
Erstellen einer Sitzung
Verlängern der Leasezeit einer Sitzung
Auflisten von Sitzungen
Beenden einer Sitzung

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", die sich im Stammverzeichnis des Blobcontainers unter der angegebenen URL befindet, konvertiert wird.

AssetConversionOptions conversionOptions = new AssetConversionOptions()
    .setInputStorageContainerUrl(getStorageURL())
    .setInputRelativeAssetPath("box.fbx")
    .setOutputStorageContainerUrl(getStorageURL());

// A randomly generated UUID is a good choice for a conversionId.
String conversionId = UUID.randomUUID().toString();

SyncPoller<AssetConversion, AssetConversion> conversionOperation = client.beginConversion(conversionId, conversionOptions);

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 organization 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:

AssetConversionOptions conversionOptions = new AssetConversionOptions()
    .setInputStorageContainerUrl(inputStorageURL)
    .setInputRelativeAssetPath("bicycle.gltf")
    .setInputBlobPrefix("Bicycle")
    .setOutputStorageContainerUrl(outputStorageURL)
    .setOutputBlobPrefix("ConvertedBicycle");

String conversionId = UUID.randomUUID().toString();

SyncPoller<AssetConversion, AssetConversion> conversionOperation = client.beginConversion(conversionId, conversionOptions);

HINWEIS: Wenn in den Eingabeoptionen ein Präfix angegeben wird, wird angenommen, dass der Eingabedateiparameter 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 eine vorhandene conversionOperation und ruft regelmäßig ab, bis die Konvertierung abgeschlossen oder fehlgeschlagen ist. Der Standardabrufzeitraum beträgt 10 Sekunden. Beachten Sie, dass eine conversionOperation aus der conversionId einer vorhandenen Konvertierung und eines Clients erstellt werden kann.

AssetConversion conversion = conversionOperation.getFinalResult();
if (conversion.getStatus() == AssetConversionStatus.SUCCEEDED) {
    logger.info("Conversion succeeded: Output written to {}", conversion.getOutputAssetUrl());
} else if (conversion.getStatus() == AssetConversionStatus.FAILED) {
    logger.error("Conversion failed: {} {}", conversion.getError().getCode(), conversion.getError().getMessage());
} else {
    logger.error("Unexpected conversion status: {}", conversion.getStatus());
}

Auflisten von Konvertierungen

Mit der listConversions -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-URLs der erfolgreichen Konvertierungen aufgelistet, die am letzten Tag gestartet wurden.

for (AssetConversion conversion : client.listConversions()) {
    if ((conversion.getStatus() == AssetConversionStatus.SUCCEEDED)
        && (conversion.getCreationTime().isAfter(OffsetDateTime.now().minusDays(1)))) {
        logger.info("Output Asset URL: {}", conversion.getOutputAssetUrl());
    }
}

Erstellen einer Renderingsitzung

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

BeginSessionOptions options = new BeginSessionOptions()
    .setMaxLeaseTime(Duration.ofMinutes(30))
    .setSize(RenderingSessionSize.STANDARD);

// A randomly generated GUID is a good choice for a sessionId.
String sessionId = UUID.randomUUID().toString();

SyncPoller<RenderingSession, RenderingSession> startSessionOperation = client.beginSession(sessionId, options);

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.

RenderingSession currentSession = client.getSession(sessionId);

Duration sessionTimeAlive = Duration.between(OffsetDateTime.now(), currentSession.getCreationTime()).abs();
if (currentSession.getMaxLeaseTime().minus(sessionTimeAlive).toMinutes() < 2) {
    Duration newLeaseTime = currentSession.getMaxLeaseTime().plus(Duration.ofMinutes(30));
    UpdateSessionOptions longerLeaseOptions = new UpdateSessionOptions().maxLeaseTime(newLeaseTime);
    client.updateSession(sessionId, longerLeaseOptions);
}

Auflisten von Renderingsitzungen

Mit der listSessions -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 (RenderingSession session : client.listSessions()) {
    if (session.getStatus() == RenderingSessionStatus.STARTING) {
        logger.info("Session {} is starting.");
    } else if (session.getStatus() == RenderingSessionStatus.READY) {
        logger.info("Session {} is ready at host {}", session.getId(), session.getHostname());
    } else if (session.getStatus() == RenderingSessionStatus.ERROR) {
        logger.error("Session {} encountered an error: {} {}", session.getId(), session.getError().getCode(), session.getError().getMessage());
    } else {
        logger.error("Session {} has unexpected status {}", session.getId(), session.getStatus());
    }
}

Beenden einer Sitzung

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

client.endSession(sessionId);

Problembehandlung

Allgemeine Hinweise zur Problembehandlung in Bezug auf Azure Remote Rendering finden Sie auf der Seite Problembehandlung beim 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 einem Failed status zurück, das einen RemoteRenderingServiceError mit Details enthält. 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 eine Error-status und enthält einen RemoteRenderingServiceError mit Details.

Nächste Schritte

Lesen Sie die Produktdokumentation
Erfahren Sie mehr über die Laufzeit-SDKs:
- .NET: /dotnet/api/microsoft.azure.remoterendering
- C++: /cpp/api/remote-rendering/

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Ausführliche Informationen finden Sie unter https://cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Aufrufe

Freigeben über