Share via

  • Artikel

Buildstatus

Azure Remote Rendering-Clientbibliothek für Python– Version 1.0.0b2

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.

Dieses SDK unterstützt Version "2021-01-01" der Remote Rendering REST-API.

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 oder (C++) verfügbar.

Produktdokumentation

Haftungsausschluss

Die Unterstützung von Azure SDK-Python-Paketen für Python 2.7 endet am 01. Januar 2022. Weitere Informationen und Antworten finden Sie unter https://github.com/Azure/azure-sdk-for-python/issues/20691.

Erste Schritte

Voraussetzungen

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

Um dieses Tutorial zu befolgen, wird dringend empfohlen, Ihr Speicherkonto mit Ihrem ARR-Konto zu verknüpfen.

Installieren des Pakets

Installieren Sie die Azure Remote Rendering-Clientbibliothek für Python mit pip:

pip install --pre azure-mixedreality-remoterendering

Erstellen und Authentifizieren des Clients

Zum Erstellen eines Remoterenderingclients sind ein authentifiziertes Konto und ein Remoterenderingendpunkt erforderlich. 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, da Sie damit das Einbetten der Anmeldeinformationen für den Zugriff in Ihre Clientanwendung vermeiden können.

Ausführliche Anweisungen und Informationen finden Sie hier .

In allen folgenden Beispielen wird der Client mit einem endpoint -Parameter erstellt. 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.

Eine vollständige Liste der Endpunkte in unterstützten Regionen finden Sie in der Liste azure Remote Rendering Region.

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:

from azure.core.credentials import AzureKeyCredential
from azure.mixedreality.remoterendering import RemoteRenderingClient

account_id = "<ACCOUNT_ID>"
account_domain = "<ACCOUNT_DOMAIN>"
account_key = "<ACCOUNT_KEY>"
arr_endpoint = "<ARR_ENDPOINT>"

key_credential = AzureKeyCredential(account_key)
client = RemoteRenderingClient(
    endpoint=arr_endpoint,
    account_id=account_id,
    account_domain=account_domain,
    credential=key_credential
)

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:

from azure.mixedreality.authentication import MixedRealityStsClient
from azure.mixedreality.remoterendering import RemoteRenderingClient
account_id = "<ACCOUNT_ID>"
account_domain = "<ACCOUNT_DOMAIN>"
account_key = "<ACCOUNT_KEY>"

key_credential = AzureKeyCredential(account_key)

client = MixedRealityStsClient(account_id, account_domain, key_credential)

token = client.get_token()

client = RemoteRenderingClient(
    endpoint=arr_endpoint,
    account_id=account_id,
    account_domain=account_domain,
    credential=token,
)

Authentifizieren mit Azure Active Directory-Anmeldeinformationen

Die Kontoschlüsselauthentifizierung wird in den meisten Beispielen verwendet, aber Sie können sich auch mithilfe der Azure Identity-Bibliothek bei Azure Active Directory authentifizieren. Dies ist die empfohlene Methode für Produktionsanwendungen. Installieren Sie @azure/identity das Paket, um den unten gezeigten Anbieter [DefaultAzureCredential][defaultazurecredential] oder andere Anmeldeinformationsanbieter zu verwenden, die mit dem Azure SDK bereitgestellt werden:

Außerdem müssen Sie [eine neue AAD-Anwendung registrieren][register_aad_app] und Zugriff auf Ihre Mixed Reality-Ressource gewähren, indem Sie Ihrem Dienstprinzipal die entsprechende Rolle für Ihren Mixed Reality-Dienst zuweisen.

from azure.identity import DefaultAzureCredential
from azure.mixedreality.remoterendering import RemoteRenderingClient

account_id = "<ACCOUNT_ID>"
account_domain = "<ACCOUNT_DOMAIN>"
default_credential = DefaultAzureCredential()

client = RemoteRenderingClient(
    endpoint=arr_endpoint,
    account_id=account_id,
    account_domain=account_domain,
    credential=default_credential
)

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.

Long-Running Vorgänge

Vorgänge mit langer Ausführungsdauer sind Vorgänge, die aus einer anfänglichen Anforderung bestehen, die an den Dienst gesendet wird, um einen Vorgang zu starten, gefolgt von der Abfrage des Diensts in Intervallen, um festzustellen, ob der Vorgang abgeschlossen oder fehlgeschlagen ist, und ob er erfolgreich war, um das Ergebnis zu erhalten.

Methoden, die Ressourcen konvertieren oder Renderingsitzungen starten, werden als Vorgänge mit langer Ausführungsdauer modelliert. Der Client macht eine begin_<method-name> Methode verfügbar, die einen LROPoller oder AsyncLROPoller zurückgibt. Aufrufer sollten warten, bis der Vorgang abgeschlossen ist, indem sie result() für das poller-Objekt aufrufen, das von der begin_<method-name> -Methode zurückgegeben wird. Beispielcodeausschnitte werden bereitgestellt, um die Verwendung von Vorgängen mit langer Ausführungszeit zu veranschaulichen unten.

Beispiele

Konvertieren eines 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 unter dem Pfad "/input/box/box.fbx" des Blobcontainers am angegebenen Speichercontainer-URI befindet, konvertiert wird.

Das Konvertieren eines Medienobjekts kann zwischen Sekunden und Stunden dauern. Dieser Code verwendet einen vorhandenen Konvertierungsabruf und ruft regelmäßig ab, bis die Konvertierung abgeschlossen oder fehlgeschlagen ist. Der Standardabrufzeitraum beträgt 5 Sekunden. Beachten Sie, dass eine Konvertierungsabfrage mithilfe des client.get_asset_conversion_poller mithilfe der ID einer vorhandenen Konvertierung und eines Clients abgerufen werden kann.

Nach Abschluss des Konvertierungsprozesses wird die Ausgabe in den angegebenen Ausgabecontainer unter dem Pfad "/output/<conversion_id>/box.arrAsset" geschrieben. Der Pfad kann aus dem output.asset_uri einer erfolgreichen Konvertierung abgerufen werden.

    conversion_id = str(uuid.uuid4()) # A randomly generated uuid is a good choice for a conversion_id.

    input_settings = AssetConversionInputSettings(
        storage_container_uri="<STORAGE CONTAINER URI>",
        relative_input_asset_path="box.fbx",
        blob_prefix="input/box"
    )
    output_settings = AssetConversionOutputSettings(
        storage_container_uri="<STORAGE CONTAINER URI>",
        blob_prefix="output/"+conversion_id,
        output_asset_filename="convertedBox.arrAsset" #if no output_asset_filename <input asset filename>.arrAsset will be the name of the resulting converted asset
    )
    try:
        conversion_poller = client.begin_asset_conversion(
            conversion_id=conversion_id,
            input_settings=input_settings,
            output_settings=output_settings
        )

        print("Conversion with id:", conversion_id, "created. Waiting for completion.")
        conversion = conversion_poller.result()
        print("conversion output:", conversion.output.asset_uri)

    except Exception as e:
        print("Conversion failed", e)

Auflisten von Konvertierungen

Mit der list_asset_conversions -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 alle Konvertierungen, die Druck-ID und die Erstellungsanzeige sowie die Ausgabeobjekt-URIs erfolgreicher Konvertierungen aufgelistet.

    print("conversions:")
    for c in client.list_asset_conversions():
        print(
            "\t conversion:  id:",
            c.id,
            "status:",
            c.status,
            "created on:",
            c.created_on.strftime("%m/%d/%Y, %H:%M:%S"),
        )
        if c.status == AssetConversionStatus.SUCCEEDED:
            print("\t\tconversion result URI:", c.output.asset_uri)

Erstellen einer Sitzung

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.

    print("starting rendering session with id:", session_id)
    try:
        session_poller = client.begin_rendering_session(
            session_id=session_id, size=RenderingSessionSize.STANDARD, lease_time_minutes=20
        )
        print(
            "rendering session with id:",
            session_id,
            "created. Waiting for session to be ready.",
        )
        session = session_poller.result()
        print(
            "session with id:",
            session.id,
            "is ready. lease_time_minutes:",
            session.lease_time_minutes,
        )
    except Exception as e:
        print("Session startup failed", e)

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.

    session = client.get_rendering_session(session_id)
    if session.lease_time_minutes - session.elapsed_time_minutes < 2:
        session = client.update_rendering_session(
            session_id=session_id, lease_time_minutes=session.lease_time_minutes + 10
        )

Auflisten von Sitzungen

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

    print("sessions:")
    rendering_sessions = client.list_rendering_sessions()
    for session in rendering_sessions:
        print(
            "\t session:  id:",
            session.id,
            "status:",
            session.status,
            "created on:",
            session.created_on.strftime("%m/%d/%Y, %H:%M:%S"),
        )

Beenden einer Sitzung

Der folgende Code beendet eine ausgeführte Sitzung mit der angegebenen ID. Da beim Ausführen von Sitzungen laufende Kosten anfallen, wird empfohlen, Sitzungen zu beenden, die nicht mehr benötigt werden.

    client.stop_rendering_session(session_id)
    print("session with id:", session_id, "stopped")

Problembehandlung

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

Die Clientmethoden und das Warten auf Pollerergebnisse lösen Ausnahmen aus, wenn die Anforderung fehlgeschlagen ist.

Wenn das Medienobjekt in einer Konvertierung ungültig ist, löst der Konvertierungs-Poller eine Ausnahme mit einem Fehler aus, der 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.

Ebenso endet die Sitzung manchmal, wenn eine Sitzung angefordert wird, in einem Fehlerzustand. Der Poller löst in diesem Fall eine Ausnahme aus, die Details des Fehlers enthält. Sitzungsfehler sind in der Regel vorübergehend, und das Anfordern einer neuen Sitzung sollte erfolgreich sein.

Protokollierung

Diese Bibliothek verwendet die Standardbibliothek [logging][python_logging] für die Protokollierung.

Grundlegende Informationen zu HTTP-Sitzungen (URLs, Header usw.) werden auf ebener Ebene INFO protokolliert.

Die Protokollierung auf detaillierter DEBUG Ebene, einschließlich Anforderungs-/Antworttexten und nicht ausgeführten Headern, kann auf dem Client oder pro Vorgang mit dem logging_enable argument Schlüsselwort (keyword) aktiviert werden.

Die vollständige SDK-Protokollierungsdokumentation mit Beispielen finden Sie hier.

Optionale Konfiguration

Optionale Schlüsselwort (keyword) Argumente können auf Client- und Vorgangsebene übergeben werden. In der Azure Core-Referenzdokumentation werden verfügbare Konfigurationen für Wiederholungen, Protokollierung, Transportprotokolle und vieles mehr beschrieben.

Ausnahmen

Die Remote Rendering Clientbibliothek löst ausnahmen aus, die in Azure Core definiert sind.

Asynchrone APIs

Diese Bibliothek enthält auch eine vollständige asynchrone API, die unter Python 3.7 und höher unterstützt wird. Um es verwenden zu können, müssen Sie zuerst einen asynchronen Transport installieren, z. B. aiohttp. Asynchrone Clients befinden sich unter dem azure.mixedreality.remoterendering.aio Namespace.

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.

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