Azure远程渲染Python客户端库

Azure远程渲染（ARR）是一种服务，它允许您在云中渲染高质量、交互式的3D内容，并将其实时流式传输到设备，例如HoloLens 2。

此SDK提供了将资产转换为运行时期望的格式的功能，并管理远程渲染会话的生命周期。

此SDK支持远程渲染REST API的"2021-01-01"版本。

注意：一旦会话运行，客户端应用程序将使用以下“运行时SDK”之一连接到它。这些SDK旨在最好地支持交互式应用程序进行3D渲染的需求。它们以(.net或C++)的形式提供。

产品文档

免责声明

从2022年1月1日起，Azure SDK Python包对Python 2.7的支持已结束。有关更多信息及问题，请参阅https://github.com/Azure/azure-sdk-for-python/issues/20691

入门

先决条件

使用此包，您需要Azure订阅和Azure远程渲染账户。

为了遵循本教程，强烈建议您将存储账户与您的ARR账户关联。

安装包

使用pip安装Azure远程渲染Python客户端库

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
)

使用静态访问令牌认证

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

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 Identity库使用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 是用于访问远程渲染服务的客户端库。它提供了创建和管理资产转换和渲染会话的方法。

长时间运行的操作

长时间运行的操作是指包括向服务发送初始请求以启动操作、间隔轮询服务以确定操作是否完成或失败，以及如果成功，获取结果的操作。

将转换资产或启动渲染会话的方法建模为长时间运行的操作。客户端公开一个返回 LROPoller 或 AsyncLROPoller 的 begin_<method-name> 方法。调用者应通过在 begin_<method-name> 方法返回的轮询对象上调用 result() 来等待操作完成。以下提供了使用长时间运行操作的示例代码片段 如下。

示例

• 转换资产
• 列出转换
• 创建会话
• 延长会话的租期
• 列出会话
• 停止会话

转换资产

我们假设远程渲染客户端已按照客户端认证部分所述构建。以下代码片段描述了如何请求将位于给定存储容器 URI 的 blob 容器中的路径“/input/box/box.fbx”的“box.fbx”进行转换。

转换资产可能需要几秒到几小时不等。此代码使用现有的转换轮询器并定期轮询，直到转换完成或失败。默认轮询周期为 5 秒。注意，可以使用客户端.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)

创建会话

我们假设远程渲染客户端已按照客户端认证部分所述构建。以下代码片段描述了如何请求启动新的渲染会话。

    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 上的远程渲染故障排除页面。

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

如果转换中的资产无效，转换轮询器将抛出一个异常，包含错误详情。一旦转换服务能够处理文件，将向输出容器写入一个.result.json文件。如果输入资产无效，则该文件将包含更详细的问题描述。

类似地，有时在请求会话时，会话最终处于错误状态。在这种情况下，轮询器将抛出一个包含错误详情的异常。会话错误通常是短暂的，请求新会话应该会成功。

日志记录

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

HTTP会话（URL、头部等）的基本信息将在INFO级别进行记录。

详细的DEBUG级别日志，包括请求/响应体和未编辑的头部，可以通过客户端或操作级别的logging_enable关键字参数启用。

有关完整SDK日志记录文档和示例，请参阅此处。

可选配置

可以在客户端和操作级别传递可选的关键字参数。azure-core 参考文档描述了可用的配置，包括重试、日志记录、传输协议等。

异常

远程渲染客户端库将引发在Azure Core中定义的异常。

异步API

此库还包括一个完全的异步API，支持Python 3.7+。要使用它，您必须首先安装一个异步传输，例如aiohttp。异步客户端位于azure.mixedreality.remoterendering.aio命名空间下。

下一步

• 阅读产品文档
• 了解运行时SDK
  • .NET: https://docs.microsoft.com/dotnet/api/microsoft.azure.remoterendering
  • C++: https://docs.microsoft.com/cpp/api/remote-rendering/

贡献

此项目欢迎贡献和建议。大多数贡献都需要您同意一份贡献者许可协议（CLA），声明您有权，并且实际上确实授予我们使用您贡献的权利。有关详细信息，请访问https://cla.microsoft.com。

当您提交一个pull request时，一个CLA-bot将自动确定您是否需要提供CLA，并适当地装饰PR（例如，标签、注释）。只需遵循bot提供的说明。您只需要在整个使用我们的CLA的repo中这样做一次。

此项目已采用Microsoft开源行为准则。有关更多信息，请参阅行为准则FAQ或通过opencode@microsoft.com联系以获取任何额外的疑问或评论。

如果您想为此库做出贡献，请阅读贡献指南以了解有关如何构建和测试代码的更多信息。

版本历史

1.0.0b2 (2023-07-03)

其他更改

• 为枚举添加了不区分大小写的支持。
• 不再支持Python 2.7。请使用Python版本3.7或更高版本。

1.0.0b1 (2021-11-15)

• 首次发布。