Статья
07/07/2023

Клиентская библиотека Azure Удаленная отрисовка для Python версии 1.0.0b2

Удаленная отрисовка Azure (ARR) — это служба, которая позволяет визуализировать высококачественное интерактивное трехмерное содержимое в облаке и передавать его в режиме реального времени на устройства, такие как HoloLens 2.

Этот пакет SDK предоставляет функции для преобразования ресурсов в формат, ожидаемый средой выполнения, а также для управления временем существования сеансов удаленной отрисовки.

Этот пакет SDK поддерживает версию "2021-01-01" Удаленная отрисовка REST API.

ПРИМЕЧАНИЕ. После запуска сеанса клиентское приложение подключается к нему с помощью одного из "пакетов SDK среды выполнения". Эти пакеты SDK предназначены для оптимальной поддержки потребностей интерактивного приложения, выполняющего трехмерную отрисовку. Они доступны в (.net или (C++).

Документация по продукту

Заявление об отказе

Поддержка пакетов Python для Пакета Sdk Azure для Python 2.7 закончилась 1 января 2022 г. Дополнительные сведения и вопросы см. на https://github.com/Azure/azure-sdk-for-python/issues/20691

Начало работы

Предварительные требования

Для использования этого пакета потребуется подписка Azure и учетная запись Удаленная отрисовка Azure.

Чтобы выполнить инструкции из этого руководства, настоятельно рекомендуется связать учетную запись хранения с учетной записью ARR.

Установка пакета

Установите клиентную библиотеку Azure Удаленная отрисовка для Python с помощью pip:

pip install --pre azure-mixedreality-remoterendering

Создание и проверка подлинности клиента

Для создания клиента удаленной отрисовки требуется учетная запись с проверкой подлинности и конечная точка удаленной отрисовки. Для учетной записи, созданной в регионе eastus, домен учетной записи будет иметь форму "eastus.mixedreality.azure.com". Существует несколько разных форм проверки подлинности:

Проверка подлинности с помощью ключа учетной записи
- Ключи учетной записи позволяют быстро приступить к работе с azure Удаленная отрисовка. Но перед развертыванием приложения в рабочей среде рекомендуется обновить приложение и включить в нем использование проверки подлинности Azure AD.
Проверка подлинности на основе маркера Azure Active Directory (AD)
- Если вы создаете корпоративное приложение и в вашей компании в качестве системы идентификации используется Azure AD, вы можете применить в своем приложении проверку подлинности Azure AD на основе пользователей. Затем вы предоставляете доступ к учетным записям Azure Удаленная отрисовка с помощью существующих групп безопасности Azure AD. Вы также можете предоставлять доступ пользователям в вашей организации напрямую.
- В противном случае рекомендуется получать маркеры 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 Active Directory с помощью библиотеки удостоверений Azure. Это рекомендуемый метод для рабочих приложений. Чтобы использовать поставщик [DefaultAzureCredential][defaultazurecredential], показанный ниже, или другие поставщики учетных данных, предоставляемые пакетом SDK для Azure, установите @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. Вызывающие объекты должны дождаться завершения операции, вызвав метод result() для объекта опроса, возвращаемого begin_<method-name> из метода . Примеры фрагментов кода приведены для демонстрации с помощью длительных операций ниже.

Преобразование ресурса

Предполагается, что remoteRenderingClient был создан, как описано в разделе Проверка подлинности клиента . В следующем фрагменте кода описывается, как запросить преобразование "box.fbx", который находится по пути /input/box/box.fbx контейнера BLOB-объектов по заданному универсальному коду ресурса (URI) контейнера хранилища.

Преобразование ресурса может занять от нескольких секунд до нескольких часов. Этот код использует существующий опрос преобразования и регулярно опрашивает, пока преобразование не завершится или не завершится сбоем. Период опроса по умолчанию составляет 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>. Если входной ресурс недопустим, этот файл будет содержать более подробное описание проблемы.

Аналогичным образом, иногда при запросе сеанса сеанс оказывается в состоянии ошибки. В этом случае средство опроса вызовет исключение, содержащее сведения об ошибке. Ошибки сеанса обычно являются временными, и запрос нового сеанса должен завершиться успешно.

Ведение журнала

Эта библиотека использует стандартную библиотеку [ведение журнала][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: /dotnet/api/microsoft.azure.remoterendering
- C++: /cpp/api/remote-rendering/

Участие

На этом проекте приветствуются публикации и предложения. Для участия в большинстве процессов по разработке документации необходимо принять лицензионное соглашение участника (CLA), в котором указывается, что вы предоставляете нам права на использование ваших публикаций. Для получения подробных сведений посетите веб-страницу https://cla.microsoft.com.

При отправке запроса на включение внесенных изменений CLA-бот автоматически определит необходимость предоставления соглашения CLA и соответствующего оформления запроса на включение внесенных изменений (например, добавление метки, комментария). Просто следуйте инструкциям бота. Будет достаточно выполнить их один раз для всех репозиториев, поддерживающих соглашение CLA.

В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения см. в разделе часто задаваемых вопросов о правилах поведения или обратитесь к opencode@microsoft.com с любыми дополнительными вопросами или комментариями.

Если вы хотите вносить изменения в эту библиотеку, ознакомьтесь с руководством по внесению изменений, в котором содержатся сведения о создании и тестировании кода.

Просмотры

Поделиться через