Bagikan melalui

  • Artikel

Status Build

Pustaka klien Azure Remote Rendering untuk Python - versi 1.0.0b2

Azure Remote Rendering (ARR) adalah layanan yang memungkinkan Anda merender konten 3D interaktif berkualitas tinggi di cloud dan melakukan streaming secara real-time ke perangkat, seperti HoloLens 2.

SDK ini menawarkan fungsionalitas untuk mengonversi aset ke format yang diharapkan oleh runtime, dan juga untuk mengelola masa pakai sesi penyajian jarak jauh.

SDK ini mendukung versi "2021-01-01" dari Remote Rendering REST API.

CATATAN: Setelah sesi berjalan, aplikasi klien akan terhubung ke sesi tersebut menggunakan salah satu "SDK runtime". SDK ini dirancang untuk paling mendukung kebutuhan aplikasi interaktif yang melakukan penyajian 3d. Mereka tersedia di (.net atau (C++).

Dokumentasi produk

Pengelakan

Dukungan paket Azure SDK Python untuk Python 2.7 telah berakhir 01 Januari 2022. Untuk informasi dan pertanyaan lebih lanjut, silakan merujuk ke https://github.com/Azure/azure-sdk-for-python/issues/20691

Memulai

Prasyarat

Anda akan memerlukan langganan Azure dan akun Azure Remote Rendering untuk menggunakan paket ini.

Untuk mengikuti tutorial ini, sangat disarankan agar Anda menautkan akun penyimpanan Anda dengan akun ARR Anda.

Instal paketnya

Instal pustaka klien Azure Remote Rendering untuk Python dengan pip:

pip install --pre azure-mixedreality-remoterendering

Membuat dan mengautentikasi klien

Membuat klien penyajian jarak jauh memerlukan akun yang diautentikasi, dan titik akhir penyajian jarak jauh. Untuk akun yang dibuat di wilayah eastus, domain akun akan memiliki formulir "eastus.mixedreality.azure.com". Ada beberapa bentuk autentikasi yang berbeda:

  • Autentikasi Kunci Akun
    • Kunci akun memungkinkan Anda memulai dengan cepat menggunakan Azure Remote Rendering. Namun sebelum menyebarkan aplikasi ke produksi, kami menyarankan Anda memperbarui aplikasi untuk menggunakan autentikasi Azure Active Directory.
  • Autentikasi token Azure Active Directory (AD)
    • Jika sedang membangun aplikasi perusahaan dan perusahaan menggunakan Azure Active Directory sebagai sistem identitasnya, Anda dapat menggunakan autentikasi Azure Active Directory berbasis pengguna di aplikasi. Anda kemudian memberikan akses ke akun Azure Remote Rendering Anda dengan menggunakan grup keamanan Azure AD yang sudah ada. Anda juga dapat memberikan akses langsung ke pengguna di organisasi Anda.
    • Jika tidak, kami menyarankan Anda mendapatkan token Azure Active Directory dari layanan web yang mendukung aplikasi. Kami merekomendasikan metode ini untuk aplikasi produksi karena memungkinkan Anda menghindari penyematan kredensial untuk akses di aplikasi klien Anda.

Lihat di sini untuk petunjuk dan informasi terperinci.

Dalam semua contoh berikut, klien dibangun dengan endpoint parameter . Titik akhir yang tersedia sesuai dengan wilayah, dan pilihan titik akhir menentukan wilayah tempat layanan melakukan pekerjaannya. Contohnya https://remoterendering.eastus2.mixedreality.azure.com.

Daftar lengkap titik akhir di wilayah yang didukung dapat ditemukan di daftar wilayah Azure Remote Rendering.

CATATAN: Untuk mengonversi aset, lebih baik memilih wilayah yang dekat dengan penyimpanan yang berisi aset.

CATATAN: Untuk penyajian, sangat disarankan agar Anda memilih wilayah terdekat dengan perangkat yang menggunakan layanan. Waktu yang dibutuhkan untuk berkomunikasi dengan server berdampak pada kualitas pengalaman.

Mengautentikasi dengan autentikasi kunci akun

AzureKeyCredential Gunakan objek untuk menggunakan pengidentifikasi akun dan kunci akun untuk mengautentikasi:

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
)

Mengautentikasi dengan token akses statis

Anda dapat meneruskan token akses Mixed Reality sebagai AccessToken yang sebelumnya diambil dari layanan STS Mixed Reality untuk digunakan dengan pustaka klien 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,
)

Mengautentikasi dengan Kredensial Azure Active Directory

Autentikasi kunci akun digunakan di sebagian besar contoh, tetapi Anda juga dapat mengautentikasi dengan Azure Active Directory menggunakan pustaka Azure Identity. Ini adalah metode yang direkomendasikan untuk aplikasi produksi. Untuk menggunakan penyedia [DefaultAzureCredential][defaultazurecredential] yang ditunjukkan di bawah ini, atau penyedia kredensial lain yang disediakan dengan Azure SDK, instal @azure/identity paket:

Anda juga harus [mendaftarkan aplikasi AAD baru][register_aad_app] dan memberikan akses ke sumber daya Mixed Reality Anda dengan menetapkan peran yang sesuai untuk layanan Mixed Reality Anda ke perwakilan layanan Anda.

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
)

Konsep utama

RemoteRenderingClient

RemoteRenderingClient adalah pustaka klien yang digunakan untuk mengakses RemoteRenderingService. Ini menyediakan metode untuk membuat dan mengelola konversi aset dan sesi penyajian.

Operasi Long-Running

Operasi jangka panjang adalah operasi yang terdiri dari permintaan awal yang dikirim ke layanan untuk memulai operasi, diikuti dengan polling layanan pada interval untuk menentukan apakah operasi telah selesai atau gagal, dan jika telah berhasil, untuk mendapatkan hasilnya.

Metode yang mengonversi aset, atau sesi rendering spin up dimodelkan sebagai operasi yang berjalan lama. Klien mengekspos begin_<method-name> metode yang mengembalikan LROPoller atau AsyncLROPoller. Penelepon harus menunggu operasi selesai dengan memanggil result() pada objek poller yang dikembalikan dari begin_<method-name> metode . Cuplikan kode sampel disediakan untuk mengilustrasikan menggunakan Contoh operasi yang berjalan lama below.

Contoh

Mengonversi aset

Kami berasumsi bahwa RemoteRenderingClient telah dibangun seperti yang dijelaskan di bagian Autentikasi Klien . Cuplikan berikut menjelaskan cara meminta "box.fbx", yang ditemukan di jalur "/input/box/box.fbx" dari kontainer blob di URI kontainer penyimpanan yang diberikan, akan dikonversi.

Mengonversi aset dapat memakan waktu dari detik ke jam. Kode ini menggunakan poller konversi dan polling yang ada secara teratur sampai konversi selesai atau gagal. Periode polling default adalah 5 detik. Perhatikan bahwa poller konversi dapat diambil menggunakan client.get_asset_conversion_poller menggunakan id konversi yang ada dan klien.

Setelah proses konversi selesai, output ditulis ke kontainer output yang ditentukan di bawah jalur "/output/<conversion_id>/box.arrAsset". Jalur dapat diambil dari output.asset_uri konversi yang berhasil.

    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)

Konversi daftar

Anda bisa mendapatkan informasi tentang konversi Anda menggunakan metode .list_asset_conversions Metode ini dapat mengembalikan konversi yang belum dimulai, konversi yang sedang berjalan dan konversi yang telah selesai. Dalam contoh ini, kami mencantumkan semua konversi dan mencetak id dan iklan pembuatan serta URI aset output dari konversi yang berhasil.

    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)

Membuat sesi

Kami berasumsi bahwa RemoteRenderingClient telah dibangun seperti yang dijelaskan di bagian Autentikasi Klien . Cuplikan berikut menjelaskan cara meminta agar sesi penyajian baru dimulai.

    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)

Memperpanjang waktu sewa sesi

Jika sesi mendekati waktu sewa maksimumnya, tetapi Anda ingin tetap hidup, Anda harus melakukan panggilan untuk meningkatkan waktu sewa maksimumnya. Contoh ini memperlihatkan cara mengkueri properti saat ini lalu memperpanjang sewa jika akan segera kedaluwarsa.

CATATAN: SDK runtime juga menawarkan fungsionalitas ini, dan dalam banyak skenario umum, Anda akan menggunakannya untuk memperpanjang sewa sesi.

    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
        )

Mencantumkan sesi

Anda bisa mendapatkan informasi tentang sesi Anda menggunakan list_rendering_sessions metode klien. Metode ini dapat mengembalikan sesi yang belum dimulai dan sesi yang siap.

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

Menghentikan Sesi

Kode berikut akan menghentikan sesi yang sedang berjalan dengan id yang diberikan. Karena menjalankan sesi dikenakan biaya berkelanjutan, disarankan untuk menghentikan sesi yang tidak diperlukan lagi.

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

Pemecahan Masalah

Untuk saran pemecahan masalah umum mengenai Azure Remote Rendering, lihat halaman Pemecahan masalah untuk penyajian jarak jauh di docs.microsoft.com.

Metode klien dan menunggu hasil poller akan melemparkan pengecualian jika permintaan gagal.

Jika aset dalam konversi tidak valid, poller konversi akan memberikan pengecualian dengan kesalahan yang berisi detail. Setelah layanan konversi dapat memproses file, <file assetName.result.json> akan ditulis ke kontainer output. Jika aset input tidak valid, maka file tersebut akan berisi deskripsi masalah yang lebih rinci.

Demikian pula, terkadang ketika sesi diminta, sesi berakhir dalam status kesalahan. Poller akan melemparkan pengecualian yang berisi detail kesalahan dalam kasus ini. Kesalahan sesi biasanya bersifat sementara dan meminta sesi baru akan berhasil.

Pembuatan Log

Pustaka ini menggunakan pustaka [logging][python_logging] standar untuk pengelogan.

Informasi dasar tentang sesi HTTP (URL, header, dll.) dicatat pada INFO tingkat.

Pengelogan tingkat terperinci DEBUG , termasuk isi permintaan/respons dan header yang tidak diredaktifkan , dapat diaktifkan pada klien atau per operasi dengan logging_enable argumen kata kunci.

Lihat dokumentasi pengelogan SDK lengkap dengan contoh di sini.

Konfigurasi Opsional

Argumen kata kunci opsional dapat diteruskan di tingkat klien dan per operasi. Dokumentasi referensi azure-core menjelaskan konfigurasi yang tersedia untuk percobaan ulang, pengelogan, protokol transportasi, dan banyak lagi.

Pengecualian

Pustaka klien Remote Rendering akan memunculkan pengecualian yang ditentukan dalam Azure Core.

API asinkron

Pustaka ini juga menyertakan API asinkron lengkap yang didukung pada Python 3.7+. Untuk menggunakannya, Anda harus menginstal transportasi asinkron terlebih dahulu, seperti aiohttp. Klien asinkron ditemukan di azure.mixedreality.remoterendering.aio bawah namespace layanan.

Langkah berikutnya

  • Membaca dokumentasi Produk
  • Pelajari tentang SDK runtime:
    • .NET: /dotnet/api/microsoft.azure.remoterendering
    • C++: /cpp/api/remote-rendering/

Berkontribusi

Proyek ini menyambut baik kontribusi dan saran. Sebagian besar kontribusi mengharuskan Anda menyetujui Perjanjian Lisensi Kontributor (CLA) yang menyatakan bahwa Anda memiliki hak untuk, dan benar-benar melakukannya, memberi kami hak untuk menggunakan kontribusi Anda. Untuk detailnya, kunjungi https://cla.microsoft.com.

Ketika Anda mengirimkan permintaan tarik, CLA-bot akan secara otomatis menentukan apakah Anda perlu memberikan CLA dan menghias PR dengan tepat (misalnya, label, komentar). Cukup ikuti instruksi yang diberikan oleh bot. Anda hanya perlu melakukan ini sekali di semua repos menggunakan CLA kami.

Proyek ini telah mengadopsi Kode Etik Sumber Terbuka Microsoft. Untuk informasi selengkapnya, lihat Tanya Jawab Umum Tata Tertib atau hubungi opencode@microsoft.com untuk pertanyaan atau komentar lainnya.

Jika Anda ingin berkontribusi pada pustaka ini, baca panduan berkontribusi untuk mempelajari selengkapnya tentang cara membuat dan menguji kode.

Tayangan