發行項
07/12/2023

適用于 Python 的 Azure 遠端轉譯用戶端程式庫 - 1.0.0b2 版

Azure 遠端轉譯 (ARR) 是一項服務，可讓您在雲端轉譯高品質、互動式3D 內容，並將其即時串流至裝置，例如 HoloLens 2。

此 SDK 提供的功能可將資產轉換成執行時間預期的格式，以及管理遠端轉譯會話的存留期。

此 SDK 支援遠端轉譯 REST API版本「2021-01-01」。

注意：會話執行之後，用戶端應用程式會使用其中一個「執行時間 SDK」來連線到它。這些 SDK 的設計目的是為了支援執行 3D 轉譯的互動式應用程式需求。它們可在 .net (或 (C++) 中使用。

免責聲明

Python 2.7 的 Azure SDK Python 套件支援已于 2022 年 1 月 1 日結束。如需詳細資訊和問題，請參閱 https://github.com/Azure/azure-sdk-for-python/issues/20691

開始使用

Prerequisites

您將需要Azure 訂用帳戶和Azure 遠端轉譯帳戶才能使用此套件。

若要遵循本教學課程，強烈建議您將儲存體帳戶與 ARR 帳戶連結。

安裝套件

使用pip安裝適用于 Python 的 Azure 遠端轉譯用戶端程式庫：

pip install --pre azure-mixedreality-remoterendering

建立和驗證用戶端

建構遠端轉譯用戶端需要已驗證的帳戶和遠端轉譯端點。針對在 eastus 區域中建立的帳戶，帳戶網域會具有「eastus.mixedreality.azure.com」。驗證有幾種不同形式：

帳戶金鑰驗證
- 帳戶金鑰可讓您快速開始使用 Azure 遠端轉譯。但在您將應用程式部署至生產環境之前，建議您先更新應用程式，以使用 Azure AD 驗證。
Azure Active Directory (AD) 權杖驗證
- 如果您要建置企業應用程式，且貴公司使用 Azure AD 做為其身分識別系統，則您可在應用程式中使用使用者型的 Azure AD 驗證。然後，您可以使用現有的 Azure AD 安全性群組來授與 Azure 遠端轉譯帳戶的存取權。您也可以直接將存取權授與貴組織中的使用者。
- 否則，建議您從支援應用程式的 Web 服務中取得 Azure AD 權杖。建議您針對生產應用程式使用這個方法，因為它可讓您避免在用戶端應用程式中內嵌認證以進行存取。

如需詳細指示和資訊，請參閱這裡。

在下列所有範例中，會使用 endpoint 參數建構用戶端。可用的端點會對應至區域，而端點的選擇會決定服務執行其工作的區域。例如 https://remoterendering.eastus2.mixedreality.azure.com。

您可以在Azure 遠端轉譯區域清單中找到支援區域中的完整端點清單。

注意：若要轉換資產，最好選擇接近包含資產之儲存體的區域。

注意：若要轉譯，強烈建議您使用服務挑選最接近裝置的區域。與伺服器通訊所花費的時間會影響體驗的品質。

使用帳戶金鑰驗證進行驗證

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
)

使用靜態存取權杖進行驗證

您可以傳遞Mixed Reality存取權杖，做為 AccessToken 先前從Mixed Reality STS 服務擷取，以便與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,
)

使用 Azure Active Directory 認證進行驗證

帳戶金鑰驗證用於大部分的範例中，但您也可以使用 Azure 身分識別程式庫向 Azure Active Directory 進行驗證。這是生產應用程式的建議方法。若要使用如下所示的 [DefaultAzureCredential][defaultazurecredential] 提供者，或隨附于 Azure SDK 的其他認證提供者，請安裝 @azure/identity 套件：

您也需要 [註冊新的 AAD 應用程式][register_aad_app]，並將Mixed Reality服務的適當角色指派給服務主體，以授與Mixed Reality資源的存取權。

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
)

重要概念

RemoteRenderingClient

RemoteRenderingClient是用來存取 RemoteRenderingService 的用戶端程式庫。它提供方法來建立和管理資產轉換和轉譯會話。

Long-Running作業

長時間執行的作業是由傳送至服務以啟動作業的初始要求所組成，接著依間隔輪詢服務，以判斷作業是否已完成或失敗，以及是否成功，以取得結果。

轉換資產或加速轉譯會話的方法會模型化為長時間執行的作業。用戶端會公開傳 begin_<method-name> 回 LROPoller 或 AsyncLROPoller 的方法。呼叫端應該等候作業完成，方法是在從 begin_<method-name> 方法傳回的 Poller 物件上呼叫 result () 。提供範例程式碼片段來說明如何使用長時間執行的作業。

轉換資產

我們假設已建構 RemoteRenderingClient，如驗證用戶端一節中所述。下列程式碼片段描述如何要求在指定儲存體容器 URI 上 Blob 容器的「/input/box/box.fbx」路徑中找到「box.fbx」的「box.fbx」。

將資產轉換可能需要數秒到數小時的時間。此程式碼會使用現有的轉換輪詢器，並定期輪詢，直到轉換完成或失敗為止。預設輪詢期間為 5 秒。請注意，您可以使用現有轉換和用戶端的識別碼，使用client.get_asset_conversion_poller擷取轉換輪詢器。

轉換程式完成之後，輸出會寫入指定的輸出容器，其路徑為「/output/ < conversion_id > /box.arrAsset」。您可以從成功轉換output.asset_uri擷取路徑。

    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)

清單轉換

您可以使用方法來取得轉換 list_asset_conversions 的相關資訊。這個方法可能會傳回尚未啟動的轉換、正在執行的轉換，以及已完成的轉換。在此範例中，我們會列出所有轉換和列印識別碼和建立廣告，以及成功轉換的輸出資產 URI。

    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)

建立工作階段

我們假設已建構 RemoteRenderingClient，如驗證用戶端一節中所述。下列程式碼片段描述如何要求啟動新的轉譯會話。

    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)

延長會話的租用時間

如果會話接近其租用時間上限，但您想要讓它保持運作，您必須進行呼叫，以增加其租用時間上限。此範例示範如何查詢目前的屬性，然後在租用即將到期時延長租用。

注意：執行時間 SDK 也提供這項功能，而且在許多情況下，您會使用它們來擴充會話租用。

    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
        )

列出會話

您可以使用用戶端的方法來取得會話 list_rendering_sessions 的相關資訊。這個方法可能會傳回尚未啟動的會話，以及已就緒的會話。

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

停止會話

下列程式碼將會停止具有指定識別碼的執行中會話。由於執行會話會產生持續成本，因此建議停止不再需要的會話。

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

疑難排解

如需有關 Azure 遠端轉譯的一般疑難排解建議，請參閱 docs.microsoft.com 遠端轉譯的疑難排解頁面。

如果要求失敗，用戶端方法和等候輪詢器結果將會擲回例外狀況。

如果轉換中的資產無效，轉換輪詢器會擲回例外狀況，其中包含詳細資料的錯誤。一旦轉換服務能夠處理檔案， < assetName.result.json > 檔案就會寫入輸出容器。如果輸入資產無效，則該檔案將包含問題的詳細描述。

同樣地，有時候當要求會話時，會話最終會處於錯誤狀態。在此案例中，輪詢器會擲回包含錯誤詳細資料的例外狀況。會話錯誤通常是暫時性的，而且要求新的會話應該會成功。

記錄

此程式庫會使用標準 [logging][python_logging] 程式庫進行記錄。

HTTP 會話的基本資訊 (URL、標頭等。) 會在層級記錄 INFO 。

詳細的 DEBUG 層級記錄，包括要求/回應主體和 未回應 標頭，可以在用戶端或每個作業 logging_enable 上使用關鍵字引數來啟用。

如需完整的 SDK 記錄檔，請參閱這裡的範例。

選用組態

選擇性關鍵字引數可以在用戶端和每個作業層級傳入。 azure 核心參考檔說明重試、記錄、傳輸通訊協定等可用的組態。

例外狀況

遠端轉譯用戶端程式庫將會引發Azure Core中定義的例外狀況。

非同步 API

此程式庫也包含 Python 3.7+ 上支援的完整非同步 API。若要使用它，您必須先安裝非同步傳輸，例如 aioHTTP。非同步用戶端可在命名空間下 azure.mixedreality.remoterendering.aio 找到。

下一步

閱讀產品檔
瞭解執行時間 SDK：
- .NET：/dotnet/api/microsoft.azure.remoterendering
- C++： /cpp/api/remote-rendering/

參與

此專案歡迎參與和提供建議。大部分的參與都要求您同意「參與者授權合約 (CLA)」，宣告您有權且確實授與我們使用投稿的權利。如需詳細資料，請前往 https://cla.microsoft.com 。

當您提交提取要求時，CLA Bot 會自動判斷您是否需要提供 CLA，並適當地裝飾 PR (例如標籤、註解)。請遵循 bot 提供的指示。您只需要使用我們的 CLA 在所有存放庫上執行此動作一次。

此專案採用 Microsoft Open Source Code of Conduct (Microsoft 開放原始碼管理辦法)。如需詳細資訊，請參閱管理辦法常見問題集，如有任何其他問題或意見請連絡 opencode@microsoft.com。

如果您希望向此程式庫投稿，請參閱投稿指南，深入瞭解如何組建與測試程式碼。

曝光數

共用方式為

適用于 Python 的 Azure 遠端轉譯用戶端程式庫 - 1.0.0b2 版

免責聲明

開始使用

Prerequisites

安裝套件

建立和驗證用戶端

使用帳戶金鑰驗證進行驗證

使用靜態存取權杖進行驗證

使用 Azure Active Directory 認證進行驗證

重要概念

RemoteRenderingClient

Long-Running作業

範例

轉換資產

清單轉換

建立工作階段

延長會話的租用時間

列出會話

停止會話

疑難排解

記錄

選用組態

例外狀況

非同步 API

下一步

參與

意見反應

其他資源

共用方式為

適用于 Python 的 Azure 遠端轉譯 用戶端程式庫 - 1.0.0b2 版

免責聲明

開始使用

Prerequisites

安裝套件

建立和驗證用戶端

使用帳戶金鑰驗證進行驗證

使用靜態存取權杖進行驗證

使用 Azure Active Directory 認證進行驗證

重要概念

RemoteRenderingClient

Long-Running作業

範例

轉換資產

清單轉換

建立工作階段

延長會話的租用時間

列出會話

停止會話

疑難排解

記錄

選用組態

例外狀況

非同步 API

下一步

參與

意見反應

其他資源

適用于 Python 的 Azure 遠端轉譯用戶端程式庫 - 1.0.0b2 版