Biblioteka klienta usługi Azure Remote Rendering dla języka Python — wersja 1.0.0b2

Azure Remote Rendering (ARR) to usługa, która umożliwia renderowanie wysokiej jakości, interaktywnej zawartości 3D w chmurze i przesyłanie strumieniowe jej w czasie rzeczywistym do urządzeń, takich jak HoloLens 2.

Ten zestaw SDK oferuje funkcje umożliwiające konwertowanie zasobów na format oczekiwany przez środowisko uruchomieniowe, a także zarządzanie okresem istnienia sesji renderowania zdalnego.

Ten zestaw SDK obsługuje wersję "2021-01-01" interfejsu API REST Remote Rendering.

UWAGA: Po uruchomieniu sesji aplikacja kliencka połączy się z nią przy użyciu jednego z "zestawów SDK środowiska uruchomieniowego". Te zestawy SDK są zaprojektowane tak, aby najlepiej obsługiwały potrzeby interaktywnej aplikacji wykonującej renderowanie 3d. Są one dostępne w programie (.net lub (C++).

Dokumentacja produktu

Zrzeczenie odpowiedzialności

Obsługa pakietów języka Python zestawu Azure SDK dla języka Python 2.7 została zakończona 01 stycznia 2022 r. Aby uzyskać więcej informacji i pytań, zapoznaj się z artykułem https://github.com/Azure/azure-sdk-for-python/issues/20691

Wprowadzenie

Wymagania wstępne

Do korzystania z tego pakietu będzie potrzebna subskrypcja platformy Azure i konto usługi Azure Remote Rendering.

Aby wykonać czynności opisane w tym samouczku, zdecydowanie zaleca się połączenie konta magazynu z kontem usługi ARR.

Instalowanie pakietu

Zainstaluj bibliotekę klienta usługi Azure Remote Rendering dla języka Python przy użyciu narzędzia pip:

pip install --pre azure-mixedreality-remoterendering

Tworzenie i uwierzytelnianie klienta

Konstruowanie klienta renderowania zdalnego wymaga uwierzytelnionego konta i zdalnego punktu końcowego renderowania. W przypadku konta utworzonego w regionie eastus domena konta będzie mieć formularz "eastus.mixedreality.azure.com". Istnieje kilka różnych form uwierzytelniania:

• Uwierzytelnianie klucza konta
  • Klucze kont umożliwiają szybkie rozpoczęcie pracy z użyciem usługi Azure Remote Rendering. Jednak przed wdrożeniem aplikacji w środowisku produkcyjnym zalecamy zaktualizowanie aplikacji do korzystania z uwierzytelniania Azure AD.
• Uwierzytelnianie tokenu usługi Azure Active Directory (AD)
  • Jeśli tworzysz aplikację dla przedsiębiorstw, a firma używa Azure AD jako systemu tożsamości, możesz użyć uwierzytelniania Azure AD opartego na użytkownikach w aplikacji. Następnie udzielasz dostępu do kont usługi Azure Remote Rendering przy użyciu istniejących grup zabezpieczeń Azure AD. Możesz również udzielić dostępu bezpośrednio użytkownikom w organizacji.
  • W przeciwnym razie zalecamy uzyskanie Azure AD tokenów z usługi internetowej obsługującej aplikację. Zalecamy tę metodę dla aplikacji produkcyjnych, ponieważ pozwala uniknąć osadzania poświadczeń w celu uzyskania dostępu do aplikacji klienckiej.

Zobacz tutaj , aby uzyskać szczegółowe instrukcje i informacje.

We wszystkich poniższych przykładach klient jest skonstruowany z parametrem endpoint . Dostępne punkty końcowe odpowiadają regionom, a wybór punktu końcowego określa region, w którym usługa wykonuje swoją pracę. Może to być na przykład https://remoterendering.eastus2.mixedreality.azure.com.

Pełną listę punktów końcowych w obsługiwanych regionach można znaleźć na liście regionów usługi Azure Remote Rendering.

UWAGA: W przypadku konwertowania zasobów zaleca się wybranie regionu w pobliżu magazynu zawierającego zasoby.

UWAGA: W przypadku renderowania zdecydowanie zaleca się wybranie najbliższego regionu do urządzeń przy użyciu usługi. Czas potrzebny na komunikację z serwerem ma wpływ na jakość środowiska.

Uwierzytelnianie przy użyciu uwierzytelniania klucza konta

Użyj obiektu, AzureKeyCredential aby użyć identyfikatora konta i klucza konta do uwierzytelnienia:

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
)

Uwierzytelnianie przy użyciu statycznego tokenu dostępu

Token dostępu Mixed Reality można przekazać jako AccessToken wcześniej pobrany z usługi Mixed Reality STS do użycia z biblioteką klienta 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,
)

Uwierzytelnianie przy użyciu poświadczeń usługi Azure Active Directory

Uwierzytelnianie klucza konta jest używane w większości przykładów, ale można również uwierzytelnić się w usłudze Azure Active Directory przy użyciu biblioteki tożsamości platformy Azure. Jest to zalecana metoda dla aplikacji produkcyjnych. Aby użyć dostawcy [DefaultAzureCredential][defaultazurecredential] pokazanego poniżej lub innych dostawców poświadczeń dostarczonych z zestawem Azure SDK, zainstaluj @azure/identity pakiet:

Musisz również zarejestrować nową aplikację usługi AAD[register_aad_app] i udzielić dostępu do zasobu Mixed Reality, przypisując odpowiednią rolę dla usługi Mixed Reality do jednostki usługi.

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
)

Kluczowe pojęcia

RemoteRenderingClient

Jest RemoteRenderingClient to biblioteka klienta używana do uzyskiwania dostępu do usługi RemoteRenderingService. Udostępnia metody tworzenia konwersji zasobów i sesji renderowania oraz zarządzania nimi.

operacje Long-Running

Długotrwałe operacje to operacje, które składają się z początkowego żądania wysłanego do usługi w celu uruchomienia operacji, a następnie sondowania usługi w odstępach czasu w celu ustalenia, czy operacja została ukończona, czy nie powiodła się, a jeśli zakończyła się pomyślnie, aby uzyskać wynik.

Metody konwertujące zasoby lub uruchamiające sesje renderowania są modelowane jako długotrwałe operacje. Klient uwidacznia metodę zwracającą begin_<method-name> LROPoller lub AsyncLROPoller. Obiekt wywołujący powinien czekać na ukończenie operacji przez wywołanie elementu result() w obiekcie poller zwróconym begin_<method-name> z metody . Przykładowe fragmenty kodu są udostępniane w celu zilustrowania użycia długotrwałych operacji poniżej.

Przykłady

• Konwertowanie elementu zawartości
• Konwersje listy
• Tworzenie sesji
• Rozszerzanie czasu dzierżawy sesji
• Wyświetlanie listy sesji
• Zatrzymywanie sesji

Konwertowanie elementu zawartości

Przyjęto założenie, że obiekt RemoteRenderingClient został skonstruowany zgodnie z opisem w sekcji Uwierzytelnianie klienta . Poniższy fragment kodu opisuje sposób żądania, że "box.fbx" znajduje się w ścieżce "/input/box/box/box.fbx" kontenera obiektów blob na danym identyfikatorze URI kontenera magazynu, jest konwertowany.

Konwertowanie zasobu może potrwać od kilku sekund do godzin. Ten kod regularnie używa istniejącego elementu poller konwersji i sonduje do momentu zakończenia lub niepowodzenia konwersji. Domyślny okres sondowania to 5 sekund. Należy pamiętać, że można pobrać poller konwersji przy użyciu client.get_asset_conversion_poller przy użyciu identyfikatora istniejącej konwersji i klienta.

Po zakończeniu procesu konwersji dane wyjściowe zostaną zapisane w określonym kontenerze wyjściowym w ścieżce "/output/<conversion_id>/box.arrAsset". Ścieżkę można pobrać z output.asset_uri pomyślnej konwersji.

    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)

Konwersje listy

Informacje na temat konwersji można uzyskać przy użyciu list_asset_conversions metody . Ta metoda może zwracać konwersje, które nie zostały jeszcze uruchomione, konwersje, które są uruchomione i konwersje, które zostały zakończone. W tym przykładzie wymieniono wszystkie konwersje i identyfikator wydruku oraz reklamy tworzenia, a także identyfikatory URI elementów zawartości wyjściowej pomyślnych konwersji.

    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)

Tworzenie sesji

Przyjęto założenie, że obiekt RemoteRenderingClient został skonstruowany zgodnie z opisem w sekcji Uwierzytelnianie klienta . W poniższym fragmencie kodu opisano sposób żądania uruchomienia nowej sesji renderowania.

    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)

Rozszerzanie czasu dzierżawy sesji

Jeśli sesja zbliża się do maksymalnego czasu dzierżawy, ale chcesz zachować jej życie, musisz wykonać wywołanie, aby zwiększyć maksymalny czas dzierżawy. W tym przykładzie pokazano, jak wykonać zapytanie dotyczące bieżących właściwości, a następnie rozszerzyć dzierżawę, jeśli wkrótce wygaśnie.

UWAGA: Zestawy SDK środowiska uruchomieniowego oferują również tę funkcję, a w wielu typowych scenariuszach można ich używać do rozszerzania dzierżawy sesji.

    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
        )

Wyświetlanie listy sesji

Informacje o sesjach można uzyskać przy użyciu list_rendering_sessions metody klienta. Ta metoda może zwracać sesje, które nie zostały jeszcze uruchomione, i sesje, które są gotowe.

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

Zatrzymywanie sesji

Poniższy kod zatrzyma uruchomioną sesję z danym identyfikatorem. Ponieważ sesje uruchomione generują bieżące koszty, zaleca się zatrzymanie sesji, które nie są już potrzebne.

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

Rozwiązywanie problemów

Aby uzyskać ogólne porady dotyczące rozwiązywania problemów dotyczące usługi Azure Remote Rendering, zobacz stronę Rozwiązywanie problemów z renderowaniem zdalnym w docs.microsoft.com.

Metody klienta i oczekiwanie na wyniki poller będą zgłaszać wyjątki, jeśli żądanie nie powiodło się.

Jeśli zasób w konwersji jest nieprawidłowy, narzędzie poller konwersji zgłosi wyjątek z błędem zawierającym szczegóły. Gdy usługa konwersji będzie mogła przetworzyć plik, <plik assetName.result.json> zostanie zapisany w kontenerze wyjściowym. Jeśli zasób wejściowy jest nieprawidłowy, ten plik będzie zawierać bardziej szczegółowy opis problemu.

Podobnie, czasami w przypadku żądania sesji sesja kończy się w stanie błędu. W tym przypadku poller zgłosi wyjątek zawierający szczegóły błędu. Błędy sesji są zwykle przejściowe i żądanie nowej sesji powinno zakończyć się pomyślnie.

Rejestrowanie

Ta biblioteka używa standardowej biblioteki [logging][python_logging] do rejestrowania.

Podstawowe informacje o sesjach HTTP (adresach URL, nagłówkach itp.) są rejestrowane na INFO poziomie.

Szczegółowe DEBUG rejestrowanie na poziomie, w tym treści żądań/odpowiedzi i nieredagowanych nagłówków, można włączyć na kliencie lub na operację z argumentem słowa kluczowego logging_enable .

Zobacz pełną dokumentację rejestrowania zestawu SDK z przykładami tutaj.

Konfiguracja opcjonalna

Opcjonalne argumenty słów kluczowych można przekazać na poziomie klienta i na poziomie operacji. W dokumentacji referencyjnej platformy Azure opisano dostępne konfiguracje dotyczące ponownych prób, rejestrowania, protokołów transportowych i nie tylko.

Wyjątki

Biblioteka klienta Remote Rendering zgłosi wyjątki zdefiniowane w usłudze Azure Core.

Asynchroniczne interfejsy API

Ta biblioteka zawiera również kompletny interfejs API asynchroniczny obsługiwany w języku Python w wersji 3.7 lub nowszej. Aby go używać, należy najpierw zainstalować transport asynchroniczny, taki jak aiohttp. Klienci asynchroniczny znajdują się w azure.mixedreality.remoterendering.aio przestrzeni nazw.

Następne kroki

• Przeczytaj dokumentację produktu
• Dowiedz się więcej o zestawach SDK środowiska uruchomieniowego:
  • .NET: /dotnet/api/microsoft.azure.remoterendering
  • C++: /cpp/api/remote-rendering/

Współtworzenie

W tym projekcie zachęcamy do współtworzenia i zgłaszania sugestii. Współtworzenie w większości przypadków wymaga zgody na umowę licencyjną dotyczącą współautorów (CLA, Contributor License Agreement), zgodnie z którą współautor ma prawo udzielić i faktycznie udziela nam praw do używania wytworzonej przez siebie zawartości. Aby uzyskać szczegółowe informacje, odwiedź stronę https://cla.microsoft.com.

Po przesłaniu żądania ściągnięcia robot CLA automatycznie określi, czy musisz przekazać umowę CLA, i doda odpowiednie informacje do tego żądania (na przykład etykietę czy komentarz). Po prostu postępuj zgodnie z instrukcjami robota. Wystarczy zrobić to raz dla wszystkich repozytoriów, w przypadku których jest używana nasza umowa CLA.

W tym projekcie przyjęto Kodeks postępowania oprogramowania Open Source firmy Microsoft. Aby uzyskać więcej informacji, zobacz Często zadawane pytania dotyczące kodeksu postępowania lub skontaktuj się z opencode@microsoft.com dodatkowymi pytaniami lub komentarzami.

Jeśli chcesz współtworzyć tę bibliotekę, przeczytaj przewodnik współtworzenia , aby dowiedzieć się więcej na temat tworzenia i testowania kodu.