Sdílet prostřednictvím

  • Článek

Stav sestavení

Klientská knihovna Azure Remote Rendering pro Python – verze 1.0.0b2

Azure Remote Rendering (ARR) je služba, která umožňuje vykreslovat vysoce kvalitní interaktivní 3D obsah v cloudu a streamovat ho v reálném čase do zařízení, jako je HoloLens 2.

Tato sada SDK nabízí funkce pro převod prostředků do formátu očekávaného modulem runtime a také pro správu životnosti relací vzdáleného vykreslování.

Tato sada SDK podporuje verzi 2021-01-01 Remote Rendering REST API.

POZNÁMKA: Po spuštění relace se k ní klientská aplikace připojí pomocí jedné ze sad SDK modulu runtime. Tyto sady SDK jsou navržené tak, aby co nejlépe podporovaly potřeby interaktivní aplikace provádějící 3D vykreslování. Jsou k dispozici v (.net nebo (C++).

Produktová dokumentace

Právní omezení

Podpora balíčků Azure SDK Python pro Python 2.7 skončila 1. ledna 2022. Další informace a dotazy najdete na https://github.com/Azure/azure-sdk-for-python/issues/20691

Začínáme

Požadavky

K použití tohoto balíčku budete potřebovat předplatné Azure a účet Azure Remote Rendering.

Pokud chcete postupovat podle tohoto kurzu, důrazně doporučujeme propojit účet úložiště s účtem ARR.

Instalace balíčku

Nainstalujte klientskou knihovnu Azure Remote Rendering pro Python pomocí pip:

pip install --pre azure-mixedreality-remoterendering

Vytvoření a ověření klienta

Sestavení vzdáleného klienta vykreslování vyžaduje ověřený účet a koncový bod vzdáleného vykreslování. Pro účet vytvořený v oblasti eastus bude mít doména účtu formát "eastus.mixedreality.azure.com". Existuje několik různých forem ověřování:

  • Ověřování pomocí klíče účtu
    • Klíče účtu umožňují rychle začít používat Azure Remote Rendering. Než ale aplikaci nasadíte do produkčního prostředí, doporučujeme aktualizovat ji tak, aby používala ověřování Azure AD.
  • Ověřování pomocí tokenu Azure Active Directory (AD)
    • Pokud vytváříte podnikovou aplikaci a vaše společnost používá jako systém identit Azure AD, můžete v aplikaci použít ověřování založené na uživatelích Azure AD. Přístup k účtům Azure Remote Rendering pak udělíte pomocí stávajících skupin zabezpečení Azure AD. Můžete také udělit přístup přímo uživatelům ve vaší organizaci.
    • Jinak doporučujeme získat tokeny Azure AD z webové služby, která podporuje vaši aplikaci. Tuto metodu doporučujeme pro produkční aplikace, protože umožňuje vyhnout se vkládání přihlašovacích údajů pro přístup do klientské aplikace.

Podrobné pokyny a informace najdete tady .

Ve všech následujících příkladech je klient vytvořen pomocí parametru endpoint . Dostupné koncové body odpovídají oblastem a volba koncového bodu určuje oblast, ve které služba provádí svoji práci. Příklad: https://remoterendering.eastus2.mixedreality.azure.com.

Úplný seznam koncových bodů v podporovaných oblastech najdete v seznamu oblastí azure Remote Rendering.

POZNÁMKA: Pro převod prostředků je vhodnější vybrat oblast blízko úložiště obsahujícího prostředky.

POZNÁMKA: Pro vykreslování se důrazně doporučuje vybrat oblast, která je k zařízením pomocí služby nejblíže. Doba potřebná ke komunikaci se serverem má vliv na kvalitu prostředí.

Ověřování pomocí klíče účtu

Pomocí objektu AzureKeyCredential použijte identifikátor účtu a klíč účtu k ověření:

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
)

Ověřování pomocí statického přístupového tokenu

Přístupový token Mixed Reality můžete předat jako AccessToken dříve načtený ze služby Mixed Reality STS, který se má použít s klientskou knihovnou Mixed Reality:

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

Ověřování pomocí přihlašovacích údajů Azure Active Directory

Ve většině příkladů se používá ověřování pomocí klíče účtu, ale k ověření můžete použít také Azure Active Directory pomocí knihovny Azure Identity. Toto je doporučená metoda pro produkční aplikace. Pokud chcete použít níže uvedeného zprostředkovatele [DefaultAzureCredential][defaultazurecredential] nebo jiné zprostředkovatele přihlašovacích údajů poskytnuté se sadou Azure SDK, nainstalujte @azure/identity balíček:

Budete také muset [zaregistrovat novou aplikaci AAD][register_aad_app] a udělit přístup k Mixed Reality prostředku přiřazením příslušné role pro službu Mixed Reality vašemu instančnímu objektu.

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
)

Klíčové koncepty

RemoteRenderingClient

Je RemoteRenderingClient klientská knihovna používaná pro přístup ke službě RemoteRenderingService. Poskytuje metody pro vytváření a správu převodů prostředků a relací vykreslování.

operace Long-Running

Dlouhotrvající operace jsou operace, které se skládají z počátečního požadavku odeslaného službě na spuštění operace, po kterém následuje dotazování služby v intervalech, aby se zjistilo, jestli se operace dokončila nebo selhala, a jestli byla úspěšná, aby získala výsledek.

Metody, které převádějí prostředky nebo aktivují relace vykreslování, jsou modelované jako dlouhotrvající operace. Klient zveřejňuje metodu begin_<method-name> , která vrací LROPoller nebo AsyncLROPoller. Volající by měli počkat na dokončení operace voláním metody result() u objektu poller vráceného begin_<method-name> z metody . Ukázkové fragmenty kódu jsou k dispozici pro ilustraci použití dlouhotrvajících operací jsou uvedené níže.

Příklady

Převod prostředku

Předpokládáme, že remoteRenderingClient byl vytvořen podle popisu v části Ověření klienta . Následující fragment kódu popisuje, jak požádat o převod "box.fbx" v cestě "/input/box/box.fbx" kontejneru objektů blob v daném identifikátoru URI kontejneru úložiště.

Převod prostředku může trvat od sekund až po hodiny. Tento kód používá existující konverzní poller a pravidelně se dotazuje, dokud se převod nedokončí nebo se nezdaří. Výchozí doba dotazování je 5 sekund. Všimněte si, že konverzní poller lze načíst pomocí client.get_asset_conversion_poller pomocí ID existujícího převodu a klienta.

Po dokončení procesu převodu se výstup zapíše do zadaného kontejneru výstupu v cestě "/output/<conversion_id>/box.arrAsset". Cestu lze načíst z output.asset_uri úspěšného převodu.

    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)

Převody seznamů

Informace o převodech můžete získat pomocí list_asset_conversions metody . Tato metoda může vrátit převody, které ještě nebyly zahájeny, převody, které jsou spuštěny, a převody, které byly dokončeny. V tomto příkladu uvádíme seznam všech převodů, ID tisku a reklamy pro vytváření a také identifikátory URI výstupních prostředků úspěšných převodů.

    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)

Vytvoření relace

Předpokládáme, že remoteRenderingClient byl vytvořen podle popisu v části Ověření klienta . Následující fragment kódu popisuje, jak požádat o spuštění nové relace vykreslování.

    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)

Prodloužení doby zapůjčení relace

Pokud se relace blíží maximální době zapůjčení, ale vy ji chcete zachovat, budete muset volat a prodloužit její maximální dobu zapůjčení. Tento příklad ukazuje, jak dotazovat aktuální vlastnosti a pak prodloužit zapůjčení, pokud brzy vyprší jeho platnost.

POZNÁMKA: Tuto funkci nabízejí také sady SDK modulu runtime a v mnoha typických scénářích byste je použili k prodloužení zapůjčení relace.

    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
        )

Výpis relací

Informace o relacích můžete získat pomocí list_rendering_sessions metody klienta . Tato metoda může vrátit relace, které ještě nebyly zahájeny, a relace, které jsou připravené.

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

Zastavení relace

Následující kód zastaví spuštěnou relaci se zadaným ID. Vzhledem k tomu, že spuštěné relace účtují průběžné náklady, doporučujeme zastavit relace, které už nejsou potřeba.

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

Poradce při potížích

Obecné rady k řešení potíží se službou Azure Remote Rendering najdete na stránce Řešení potíží se vzdáleným vykreslováním na docs.microsoft.com.

Klientské metody a čekání na výsledky poller vyvolají výjimky, pokud požadavek selže.

Pokud je prostředek v převodu neplatný, konverzní poller vyvolá výjimku s chybou obsahující podrobnosti. Jakmile bude převodní služba schopna soubor zpracovat, zapíše se do výstupního kontejneru <soubor assetName.result.json>. Pokud je vstupní prostředek neplatný, bude tento soubor obsahovat podrobnější popis problému.

Podobně v některých případech, když je požadována relace, relace skončí v chybovém stavu. Poller vyvolá výjimku obsahující podrobnosti o chybě v tomto případě. Chyby relace jsou obvykle přechodné a žádost o novou relaci by měla být úspěšná.

protokolování

Tato knihovna používá k protokolování standardní knihovnu [protokolování][python_logging].

Základní informace o relacích HTTP (adresy URL, hlavičky atd.) se protokolují na INFO úrovni.

Podrobné DEBUG protokolování úrovně, včetně těl požadavků/odpovědí a nezopravovaných hlaviček, je možné povolit u klienta nebo pro jednotlivé operace pomocí argumentu klíčového logging_enable slova.

Kompletní dokumentaci k protokolování sady SDK s příklady najdete tady.

Volitelná konfigurace

Volitelné argumenty klíčových slov je možné předat na úrovni klienta a pro jednotlivé operace. Referenční dokumentace azure-core popisuje dostupné konfigurace pro opakování, protokolování, přenosové protokoly a další.

Výjimky

Klientská knihovna Remote Rendering vyvolá výjimky definované v Azure Core.

Asynchronní rozhraní API

Tato knihovna také obsahuje kompletní asynchronní rozhraní API podporované v Pythonu 3.7 nebo novějším. Abyste ho mohli používat, musíte nejdřív nainstalovat asynchronní přenos, například aiohttp. Asynchronní klienti se nacházejí v oboru azure.mixedreality.remoterendering.aio názvů .

Další kroky

  • Přečtěte si dokumentaci k produktu.
  • Další informace o sadách RUNTIME SDK:
    • .NET: /dotnet/api/microsoft.azure.remoterendering
    • C++: /cpp/api/remote-rendering/

Přispívání

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete tady: https://cla.microsoft.com

Při odesílání žádosti o přijetí změn robot CLA automaticky určí, jestli je potřeba poskytnout smlouvu CLA, a příslušným způsobem žádost o přijetí změn upraví (např. přidáním jmenovky nebo komentáře). Stačí postupovat podle pokynů robota. Pro všechna úložiště používající naši smlouvu CLA to stačí udělat jenom jednou.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování nebo kontaktujte s opencode@microsoft.com případnými dalšími dotazy nebo připomínkami.

Pokud chcete přispívat do této knihovny, přečtěte si příručku pro přispívání , kde najdete další informace o tom, jak sestavit a otestovat kód.

Imprese