你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

项目
07/07/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

入门

先决条件

需要一个 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
)

使用静态访问令牌进行身份验证

可以将混合现实访问令牌作为AccessToken以前从混合现实 STS 服务检索到的令牌传递，以便与混合现实客户端库一起使用：

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]，并通过将混合现实服务的相应角色分配给服务主体来授予对混合现实资源的访问权限。

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> 方法返回的轮询器对象上调用 result () 来等待操作完成。提供了示例代码片段来说明如何使用长时间运行的操作。

转换资产

我们假设已按照对客户端进行身份验证部分中所述构造 RemoteRenderingClient。以下代码片段介绍如何请求转换给定存储容器 URI 中 Blob 容器的“/input/box/box.fbx”路径处的“box.fbx”。

转换资产可能需要几秒钟到几小时的时间。此代码使用现有的转换轮询器，并定期轮询，直到转换完成或失败。默认轮询期为 5 秒。请注意，可以使用client.get_asset_conversion_poller使用现有转换和客户端的 ID 检索转换轮询器。

转换过程完成后，输出将写入“/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 的信息。此方法可能会返回尚未开始的转换、正在运行的转换和已完成的转换。在此示例中，我们列出所有转换、打印 ID 和创建广告，以及成功转换的输出资产 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"),
        )

停止会话

以下代码将停止具有给定 ID 的正在运行的会话。由于运行会话会产生持续成本，因此建议停止不再需要的会话。

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

疑难解答

有关 Azure 远程渲染的一般故障排除建议，请参阅 docs.microsoft.com 的远程渲染疑难解答页。

如果请求失败，客户端方法和等待轮询器结果将引发异常。

如果转换中的资产无效，则转换轮询器将引发异常，并显示包含详细信息的错误。转换服务能够处理该文件后， <会将 assetName.result.json> 文件写入输出容器。如果输入资产无效，则该文件将包含问题的更详细说明。

同样，有时请求会话时，会话最终会处于错误状态。在这种情况下，轮询器将引发包含错误详细信息的异常。会话错误通常是暂时性的，请求新会话应成功。

Logging

此库使用标准 [logging][python_logging] 库进行日志记录。

有关 HTTP 会话 (URL、标头等的基本信息，) 是在级别记录的 INFO 。

可以使用关键字 (keyword) 参数在客户端上或按操作logging_enable启用详细DEBUG级别日志记录，包括请求/响应正文和未实现的标头。

请参阅此处提供示例的完整 SDK 日志记录文档。

可选配置

可选关键字 (keyword) 参数可以在客户端和按操作级别传入。 azure-core 参考文档介绍了重试、日志记录、传输协议等的可用配置。

例外

远程渲染客户端库将引发 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 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。直接按机器人提供的说明操作。只需使用 CLA 对所有存储库执行一次这样的操作。

此项目采用了 Microsoft 开放源代码行为准则。有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与联系。

若要为此库做出贡献，请阅读贡献指南，详细了解如何生成和测试代码。

曝光数

Share via