Azure Remote Rendering-klientbibliotek för Python – version 1.0.0b2

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.

Denna SDK stöder version "2021-01-01" av Remote Rendering REST API.

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 är tillgängliga i (.net eller (C++).

Produktdokumentation

Friskrivning

Stöd för Azure SDK Python-paket för Python 2.7 har upphört den 1 januari 2022. Mer information och frågor finns i https://github.com/Azure/azure-sdk-for-python/issues/20691

Komma igång

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.

För att kunna följa den här självstudien rekommenderar vi starkt att du länkar ditt lagringskonto till ditt ARR-konto.

Installera paketet

Installera Azure Remote Rendering-klientbiblioteket för Python med pip:

pip install --pre azure-mixedreality-remoterendering

Skapa och autentisera klienten

Konstruera en fjärrrenderingsklient kräver 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 att använda Azure Remote Rendering. Men innan du distribuerar ditt program till produktion rekommenderar vi att du uppdaterar appen så att den använder Azure AD autentisering.
• Tokenautentisering i Azure Active Directory (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 för åtkomst i klientprogrammet.

Se här för detaljerade instruktioner och information.

I alla följande exempel skapas klienten med en endpoint parameter. 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.

En fullständig lista över slutpunkter i regioner som stöds finns i listan över Azure Remote Rendering-regioner.

Obs! Vid 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 objektet för att använda en kontoidentifierare och kontonyckel för att autentisera AzureKeyCredential :

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
)

Autentisera med en statisk åtkomsttoken

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

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

Autentisera med en Azure Active Directory-autentiseringsuppgift

Kontonyckelautentisering används i de flesta exempel, men du kan också autentisera med Azure Active Directory med hjälp av Azure Identity-biblioteket. Det här är den rekommenderade metoden för produktionsprogram. Om du vill använda providern [DefaultAzureCredential][defaultazurecredential] som visas nedan eller andra autentiseringsproviders som medföljer Azure SDK installerar @azure/identity du paketet:

Du måste också [registrera ett nytt AAD-program][register_aad_app] och bevilja åtkomst till din Mixed Reality resurs genom att tilldela lämplig roll för din Mixed Reality-tjänst till tjänstens huvudnamn.

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
)

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.

Long-Running åtgärder

Långvariga åtgärder är åtgärder som består av en första begäran som skickas till tjänsten för att starta en åtgärd, följt av avsökning av tjänsten med intervall för att avgöra om åtgärden har slutförts eller misslyckats, och om den har lyckats, för att få resultatet.

Metoder som konverterar tillgångar eller spin up-renderingssessioner modelleras som långvariga åtgärder. Klienten exponerar en begin_<method-name> metod som returnerar en LROPoller eller AsyncLROPoller. Anropare bör vänta tills åtgärden har slutförts genom att anropa result() på det pollerobjekt som returneras från begin_<method-name> metoden. Exempelkodfragment tillhandahålls för att illustrera hur du använder långvariga åtgärder nedan.

Exempel

• Konvertera en tillgång
• Lista konverteringar
• Skapa en session
• Förlänga lånetiden för en session
• Lista sessioner
• Stoppa en session

Konvertera en 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 på sökvägen "/input/box/box.fbx" för blobcontainern vid den angivna lagringscontainerns URI, konverteras.

Konverteringen av en tillgång kan ta allt från sekunder till timmar. Den här koden använder en befintlig konverteringspolerare och avsöker regelbundet tills konverteringen har slutförts eller misslyckats. Standard avsökningsperioden är 5 sekunder. Observera att en konverteringsröst kan hämtas med hjälp av client.get_asset_conversion_poller med ID:t för en befintlig konvertering och en klient.

När konverteringsprocessen är klar skrivs utdata till den angivna utdatacontainern under sökvägen "/output/<conversion_id>/box.arrAsset". Sökvägen kan hämtas från output.asset_uri av en lyckad konvertering.

    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)

Lista konverteringar

Du kan få information om dina konverteringar med hjälp av list_asset_conversions metoden . 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 en lista över alla konverteringar och utskrifts-ID och skapandeannons samt utdatatillgångens URI:er för lyckade konverteringar.

    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)

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.

    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)

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 utökar lånet om det snart upphör att gälla.

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

    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
        )

Lista sessioner

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

    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"),
        )

Stoppa en session

Följande kod stoppar en session som körs med angivet ID. Eftersom pågående sessioner medför löpande kostnader rekommenderar vi att du stoppar sessioner som inte längre behövs.

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

Felsökning

Allmänna felsökningsråd om Azure Remote Rendering finns på sidan Felsöka fjärråtergivning på docs.microsoft.com.

Klientmetoderna och väntar på pollerresultat genererar undantag om begäran misslyckades.

Om tillgången i en konvertering är ogiltig utlöser konverteringsmätningen ett undantag med ett fel som innehåller information. När konverteringstjänsten kan bearbeta filen skrivs en <assetName.result.json-fil> till utdatacontainern. Om indatatillgången är ogiltig innehåller filen en mer detaljerad beskrivning av problemet.

På samma sätt, ibland när en session begärs, hamnar sessionen i ett feltillstånd. Pollern genererar ett undantag som innehåller information om felet i det här fallet. Sessionsfel är vanligtvis tillfälliga och begäran om en ny session bör lyckas.

Loggning

Det här biblioteket använder standardbiblioteket [loggning][python_logging] för loggning.

Grundläggande information om HTTP-sessioner (URL:er, rubriker osv.) loggas på INFO nivå.

Detaljerad DEBUG nivåloggning, inklusive begärande-/svarskroppar och oredigerade huvuden, kan aktiveras på klienten eller per åtgärd med nyckelordsargumentet logging_enable .

Se fullständig dokumentation om SDK-loggning med exempel här.

Valfri konfiguration

Valfria nyckelordsargument kan skickas på klient- och åtgärdsnivå. Referensdokumentationen för azure-core beskriver tillgängliga konfigurationer för återförsök, loggning, transportprotokoll med mera.

Undantag

Det Remote Rendering klientbiblioteket genererar undantag som definierats i Azure Core.

Async-API:er

Det här biblioteket innehåller även ett fullständigt asynkront API som stöds i Python 3.7+. Om du vill använda den måste du först installera en asynkron transport, till exempel aiohttp. Async-klienter finns under azure.mixedreality.remoterendering.aio namnområdet.

Nästa steg

• Läs produktdokumentationen
• Läs mer om SDK:er för körning:
  • .NET: /dotnet/api/microsoft.azure.remoterendering
  • C++: /cpp/api/remote-rendering/

Bidra

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns på https://cla.microsoft.com.

När du skickar en pull-förfrågan avgör en CLA-robot automatiskt om du måste tillhandahålla ett licensavtal för bidrag med lämplig PR (t.ex. etikett eller kommentar). Följ bara robotens anvisningar. Du behöver bara göra detta en gång för alla repor som använder vårt licensavtal för bidrag.

Det här projektet använder sig av Microsofts uppförandekod för öppen källkod. Mer information finns i Vanliga frågor och svar om uppförandekod eller kontakt opencode@microsoft.com med ytterligare frågor eller kommentarer.

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