Python için Azure Remote Rendering istemci kitaplığı - sürüm 1.0.0b2

Azure Remote Rendering (ARR), bulutta yüksek kaliteli, etkileşimli 3B içerik işlemenizi ve HoloLens 2 gibi cihazlara gerçek zamanlı olarak akışla aktarmanızı sağlayan bir hizmettir.

Bu SDK, varlıkları çalışma zamanı tarafından beklenen biçime dönüştürme ve ayrıca uzaktan işleme oturumlarının kullanım ömrünü yönetme işlevselliği sunar.

Bu SDK, Remote Rendering REST API'sinin "2021-01-01" sürümünü destekler.

NOT: Oturum çalıştırıldıktan sonra istemci uygulaması "çalışma zamanı SDK'larından" birini kullanarak oturuma bağlanır. Bu SDK'lar, etkileşimli bir uygulamanın 3b işleme gereksinimlerini en iyi şekilde destekleyecek şekilde tasarlanmıştır. Bunlar (.net veya (C++) içinde kullanılabilir.

Ürün belgeleri

Bildirim

Python 2.7 için Azure SDK Python paketleri desteği 01 Ocak 2022'de sona erdi. Daha fazla bilgi ve soru için bkz. https://github.com/Azure/azure-sdk-for-python/issues/20691

Başlarken

Önkoşullar

Bu paketi kullanmak için bir Azure aboneliğine ve bir Azure Remote Rendering hesabına ihtiyacınız olacaktır.

Bu öğreticiyi takip etmek için depolama hesabınızı ARR hesabınıza bağlamanız kesinlikle önerilir.

Paketi yükleme

Pip ile Python için Azure Remote Rendering istemci kitaplığını yükleyin:

pip install --pre azure-mixedreality-remoterendering

İstemciyi oluşturma ve kimlik doğrulaması

Uzaktan işleme istemcisi oluşturmak için kimliği doğrulanmış bir hesap ve bir uzak işleme uç noktası gerekir. Eastus bölgesinde oluşturulan bir hesap için hesap etki alanı "eastus.mixedreality.azure.com" biçiminde olacaktır. Birkaç farklı kimlik doğrulaması biçimi vardır:

• Hesap Anahtarı kimlik doğrulaması
  • Hesap anahtarları, Azure Remote Rendering kullanmaya hızlı bir şekilde başlamanızı sağlar. Ancak uygulamanızı üretim ortamına dağıtmadan önce uygulamanızı Azure AD kimlik doğrulamasını kullanacak şekilde güncelleştirmenizi öneririz.
• Azure Active Directory (AD) belirteci kimlik doğrulaması
  • Kurumsal bir uygulama oluşturuyorsanız ve şirketiniz kimlik sistemi olarak Azure AD kullanıyorsa, uygulamanızda kullanıcı tabanlı Azure AD kimlik doğrulamasını kullanabilirsiniz. Ardından mevcut Azure AD güvenlik gruplarınızı kullanarak Azure Remote Rendering hesaplarınıza erişim izni verirsiniz. Kuruluşunuzdaki kullanıcılara doğrudan erişim de vekleyebilirsiniz.
  • Aksi takdirde, uygulamanızı destekleyen bir web hizmetinden Azure AD belirteçleri edinmenizi öneririz. İstemci uygulamanıza erişim için kimlik bilgilerini eklemekten kaçınmanıza olanak sağladığından, üretim uygulamaları için bu yöntemi öneririz.

Ayrıntılı yönergeler ve bilgiler için buraya bakın.

Aşağıdaki tüm örneklerde, istemci bir endpoint parametre ile oluşturulur. Kullanılabilir uç noktalar bölgelere karşılık gelir ve uç nokta seçimi, hizmetin çalışmasını gerçekleştireceği bölgeyi belirler. https://remoterendering.eastus2.mixedreality.azure.com bunun bir örneğidir.

Desteklenen bölgelerdeki uç noktaların tam listesi Azure Remote Rendering bölgesi listesinde bulunabilir.

NOT: Varlıkları dönüştürmek için, varlıkları içeren depolama alanına yakın bir bölge seçmek tercih edilir.

NOT: İşleme için, hizmeti kullanan cihazlara en yakın bölgeyi seçmeniz kesinlikle önerilir. Sunucuyla iletişim kurmak için geçen süre, deneyimin kalitesini etkiler.

Hesap anahtarı kimlik doğrulaması ile kimlik doğrulama

AzureKeyCredential Kimlik doğrulaması için bir hesap tanımlayıcısı ve hesap anahtarı kullanmak için nesnesini kullanın:

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
)

Statik erişim belirteci ile kimlik doğrulaması

Karma Gerçeklik erişim belirtecini daha önce Karma Gerçeklik istemci kitaplığıyla kullanılacak Karma Gerçeklik STS hizmetinden alınan bir belirteç olarak AccessToken geçirebilirsiniz:

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

Azure Active Directory Kimlik Bilgileri ile kimlik doğrulaması

Hesap anahtarı kimlik doğrulaması örneklerin çoğunda kullanılır, ancak Azure Kimlik kitaplığını kullanarak Azure Active Directory ile kimlik doğrulaması da yapabilirsiniz. Bu, üretim uygulamaları için önerilen yöntemdir. Aşağıda gösterilen [DefaultAzureCredential][defaultazurecredential] sağlayıcısını veya Azure SDK ile sağlanan diğer kimlik bilgisi sağlayıcılarını kullanmak için lütfen paketi yükleyin @azure/identity :

Ayrıca [yeni bir AAD uygulaması kaydetme][register_aad_app] ve hizmet sorumlunuza Karma Gerçeklik hizmetiniz için uygun rolü atayarak Karma Gerçeklik kaynağınıza erişim vermeniz gerekir.

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
)

Önemli kavramlar

RemoteRenderingClient

RemoteRenderingClient, RemoteRenderingService'e erişmek için kullanılan istemci kitaplığıdır. Varlık dönüştürmeleri ve işleme oturumları oluşturmak ve yönetmek için yöntemler sağlar.

Long-Running İşlemleri

Uzun süre çalışan işlemler, bir işlemi başlatmak için hizmete gönderilen ilk isteklerden oluşan ve ardından işlemin tamamlanıp tamamlanmadığını ve başarılı olup olmadığını belirlemek için hizmeti aralıklarla yoklayarak sonucu almak için gerçekleştirilen işlemlerdir.

Varlıkları dönüştüren veya işleme oturumlarını oluşturan yöntemler, uzun süre çalışan işlemler olarak modellenir. İstemci, LROPoller veya AsyncLROPoller döndüren bir yöntemi kullanıma sunar begin_<method-name> . Çağıranlar, yönteminden begin_<method-name> döndürülen poller nesnesinde result() çağrısı yaparak işlemin tamamlanmasını beklemelidir. Örnek kod parçacıkları, aşağıda uzun süre çalışan işlemlerin kullanılmasını göstermek için

Örnekler

• Varlığı dönüştürme
• Liste dönüştürmeleri
• Oturum oluşturma
• Oturumun kira süresini uzatma
• Oturumları listeleme
• Oturumu durdurma

Varlığı dönüştürme

İstemcinin Kimliğini Doğrulama bölümünde açıklandığı gibi bir RemoteRenderingClient'ın yapılandırıldığını varsayıyoruz. Aşağıdaki kod parçacığı, verilen depolama kapsayıcısı URI'sinde blob kapsayıcısının "/input/box/box.fbx" yolunda bulunan "box.fbx" dosyasının nasıl dönüştürülmesinin istendiğini açıklar.

Bir varlığın dönüştürülmesi saniyelerden saatlere kadar sürebilir. Bu kod mevcut bir dönüştürme poller kullanır ve dönüştürme tamamlanana veya başarısız olana kadar düzenli olarak yoklar. Varsayılan yoklama süresi 5 saniyedir. Bir dönüştürme poller var olan bir dönüştürme ve istemci kimliği kullanılarak client.get_asset_conversion_poller kullanılarak alınabilir unutmayın.

Dönüştürme işlemi tamamlandıktan sonra çıkış belirtilen çıkış kapsayıcısına "/output/conversion_id>/<box.arrAsset" yolunda yazılır. Yol, başarılı bir dönüştürmenin output.asset_uri alınabilir.

    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)

Liste dönüştürmeleri

yöntemini kullanarak list_asset_conversions dönüşümleriniz hakkında bilgi alabilirsiniz. Bu yöntem henüz başlatılmamış dönüştürmeleri, çalışmakta olan dönüştürmeleri ve tamamlanmış dönüştürmeleri döndürebilir. Bu örnekte tüm dönüşümleri, print id ve creation reklamını ve başarılı dönüşümlerin çıkış varlığı URI'lerini listeleyeceğiz.

    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)

Oturum oluşturma

İstemcinin Kimliğini Doğrulama bölümünde açıklandığı gibi bir RemoteRenderingClient'ın yapılandırıldığını varsayıyoruz. Aşağıdaki kod parçacığında yeni bir işleme oturumunun başlatılmasının nasıl istendiği açıklanır.

    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)

Oturumun kira süresini uzatma

Bir oturum kira süresi üst sınırına yaklaşıyorsa ancak onu canlı tutmak istiyorsanız, maksimum kira süresini artırmak için bir çağrı yapmanız gerekir. Bu örnekte, geçerli özelliklerin nasıl sorgulanacağı ve yakında süresi dolacaksa kiranın nasıl uzatılacağı gösterilmektedir.

NOT: Çalışma zamanı SDK'ları da bu işlevselliği sunar ve birçok tipik senaryoda bunları kullanarak oturum kirasını uzatabilirsiniz.

    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
        )

Oturumları listeleme

İstemcinin yöntemini kullanarak list_rendering_sessions oturumlarınız hakkında bilgi alabilirsiniz. Bu yöntem henüz başlatılmamış oturumları ve hazır olan oturumları döndürebilir.

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

Oturumu Durdurma

Aşağıdaki kod, verilen kimlikle çalışan bir oturumu durdurur. Çalışan oturumlar devam eden maliyetler doğurduğu için artık gerekmeyen oturumların durdurulması önerilir.

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

Sorun giderme

Azure Remote Rendering ile ilgili genel sorun giderme önerileri için docs.microsoft.com'da uzaktan işleme sorunlarını giderme sayfasına bakın.

İstek başarısız olursa istemci yöntemleri ve poller sonuçları beklenirse özel durumlar oluşturulur.

Dönüştürmedeki varlık geçersizse, dönüştürme poller ayrıntıları içeren bir hata ile bir özel durum oluşturur. Dönüştürme hizmeti dosyayı işleyebildiğinden, çıktı kapsayıcısına bir <assetName.result.json> dosyası yazılır. Giriş varlığı geçersizse, bu dosya sorunun daha ayrıntılı bir açıklamasını içerir.

Benzer şekilde, bazen bir oturum istendiğinde oturum bir hata durumunda sonuçlanır. Poller, bu durumda hatanın ayrıntılarını içeren bir özel durum oluşturur. Oturum hataları genellikle geçicidir ve yeni bir oturum istenmesi başarılı olmalıdır.

Günlüğe Kaydetme

Bu kitaplık günlük kaydı için standart [logging][python_logging] kitaplığını kullanır.

HTTP oturumlarıyla ilgili temel bilgiler (URL'ler, üst bilgiler vb.) düzeyinde günlüğe kaydedilir INFO .

İstek/yanıt gövdeleri ve işlenmemiş üst bilgiler de dahil olmak üzere ayrıntılı DEBUG düzey günlük kaydı, istemcide veya anahtar sözcük bağımsız değişkeniyle logging_enable işlem başına etkinleştirilebilir.

Burada örneklerin bulunduğu tam SDK günlük belgelerine bakın.

İsteğe Bağlı Yapılandırma

İsteğe bağlı anahtar sözcük bağımsız değişkenleri istemcide ve işlem düzeyinde geçirilebilir. Azure-core başvuru belgelerinde yeniden denemeler, günlüğe kaydetme, aktarım protokolleri ve daha fazlası için kullanılabilir yapılandırmalar açıklanmaktadır.

Özel durumlar

Remote Rendering istemci kitaplığı, Azure Core'da tanımlanan özel durumları tetikler.

Zaman Uyumsuz API'ler

Bu kitaplık ayrıca Python 3.7+ üzerinde desteklenen tam bir zaman uyumsuz API içerir. Bunu kullanmak için önce aiohttp gibi bir zaman uyumsuz aktarım yüklemeniz gerekir. Zaman uyumsuz istemciler ad alanının azure.mixedreality.remoterendering.aio altında bulunur.

Sonraki adımlar

• Ürün belgelerini okuyun
• Çalışma zamanı SDK'ları hakkında bilgi edinin:
  • .NET: /dotnet/api/microsoft.azure.remoterendering
  • C++: /cpp/api/remote-rendering/

Katkıda bulunma

Bu proje, katkı ve önerilere açıktır. Çoğu durumda, sağladığınız katkıyı kullanmamız için bize hak tanıma hakkına sahip olduğunuzu ve bu hakkı bize tanıdığınızı bildiren bir Katkıda Bulunan Lisans Sözleşmesi’ni (CLA) kabul etmeniz gerekir. Ayrıntılar için bkz. https://cla.microsoft.com.

Bir çekme isteği gönderdiğinizde, CLA robotu bir CLA sağlamanız gerekip gerekmediğini otomatik olarak belirler ve çekme isteğini uygun şekilde donatır (örn. etiket, açıklama). Robot tarafından sağlanan yönergeleri izlemeniz yeterlidir. Bu işlemi, CLA’mızı kullanarak tüm depolarda yalnızca bir kere yapmanız gerekir.

Bu proje Microsoft Open Source Code of Conduct (Microsoft Açık Kaynak Kullanım Kuralları) belgesinde listelenen kurallara uygundur. Daha fazla bilgi için Kullanım Kuralları SSS bölümüne bakın veya ek sorular veya yorumlarla iletişime geçin opencode@microsoft.com .

Bu kitaplığa katkıda bulunmak isterseniz, kodu derleme ve test etme hakkında daha fazla bilgi edinmek için lütfen katkıda bulunma kılavuzunu okuyun.