• 아티클

빌드 상태

Python용 Azure Remote Rendering 클라이언트 라이브러리 - 버전 1.0.0b2

ARR(Azure Remote Rendering) 은 클라우드에서 고품질의 대화형 3D 콘텐츠를 렌더링하고 HoloLens 2와 같은 디바이스에서 실시간으로 스트리밍할 수 있는 서비스입니다.

이 SDK는 자산을 런타임에 필요한 형식으로 변환하고 원격 렌더링 세션의 수명을 관리하는 기능을 제공합니다.

이 SDK는 Remote Rendering 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 Remote Rendering 계정이 필요합니다.

이 자습서를 따르려면 스토리지 계정을 ARR 계정과 연결하는 것이 좋습니다.

패키지 설치

pip를 사용하여 Python용 Azure Remote Rendering 클라이언트 라이브러리를 설치합니다.

pip install --pre azure-mixedreality-remoterendering

클라이언트 만들기 및 인증

원격 렌더링 클라이언트를 생성하려면 인증된 계정과 원격 렌더링 엔드포인트가 필요합니다. eastus 지역에서 만든 계정의 경우 계정 도메인에는 "eastus.mixedreality.azure.com" 형식이 있습니다. 다음과 같은 여러 가지 형태의 인증이 있습니다.

  • 계정 키 인증
    • 계정 키를 사용하면 Azure Remote Rendering 사용하여 빠르게 시작할 수 있습니다. 하지만 애플리케이션을 프로덕션 환경에 배포하기 전에 Azure AD 인증을 사용하도록 앱을 업데이트하는 것이 좋습니다.
  • Azure AD(Active Directory) 토큰 인증
    • 엔터프라이즈 애플리케이션을 빌드하고 회사가 Azure AD를 ID 시스템으로 사용하는 경우 앱에서 사용자 기반 Azure AD 인증을 사용할 수 있습니다. 그런 다음 기존 Azure AD 보안 그룹을 사용하여 Azure Remote Rendering 계정에 대한 액세스 권한을 부여합니다. 조직의 사용자에게 직접 액세스 권한을 부여할 수도 있습니다.
    • 그렇지 않은 경우에는 앱을 지원하는 웹 서비스에서 Azure AD 토큰을 가져오는 것이 좋습니다. 클라이언트 애플리케이션에 액세스하기 위해 자격 증명을 포함하지 않도록 하므로 프로덕션 애플리케이션에 이 방법을 사용하는 것이 좋습니다.

자세한 지침 및 정보는 여기 를 참조하세요.

다음 모든 예제에서 클라이언트는 매개 변수를 사용하여 endpoint 생성됩니다. 사용 가능한 엔드포인트는 지역에 해당하며 엔드포인트를 선택하면 서비스가 해당 작업을 수행하는 지역이 결정됩니다. 예제는 https://remoterendering.eastus2.mixedreality.azure.com입니다.

지원되는 지역의 전체 엔드포인트 목록은 Azure Remote Rendering 지역 목록에서 찾을 수 있습니다.

참고: 자산을 변환하는 경우 자산을 포함하는 스토리지에 가까운 지역을 선택하는 것이 좋습니다.

참고: 렌더링의 경우 서비스를 사용하여 디바이스에 가장 가까운 지역을 선택하는 것이 좋습니다. 서버와 통신하는 데 걸리는 시간은 환경의 품질에 영향을 줍니다.

계정 키 인증을 사용하여 인증

개체를 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 액세스 토큰을 이전에 Mixed Reality STS 서비스에서 검색한 것으로 AccessToken 전달하여 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 ID 라이브러리를 사용하여 Azure Active Directory로 인증할 수도 있습니다. 프로덕션 애플리케이션에 권장되는 방법입니다. 아래에 표시된 [DefaultAzureCredential][defaultazurecredential] 공급자 또는 Azure SDK와 함께 제공되는 기타 자격 증명 공급자를 사용하려면 패키지를 설치 @azure/identity 하세요.

또한 서비스 주체에 Mixed Reality 서비스에 대한 적절한 역할을 할당하여 [새 AAD 애플리케이션 등록][register_aad_app]과 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 작업

장기 실행 작업은 작업을 시작하기 위해 서비스로 전송된 초기 요청으로 구성된 작업이며, 그 다음에는 간격으로 서비스를 폴링하여 작업이 완료되었는지 또는 실패했는지, 성공했는지 여부를 확인하여 결과를 가져옵니다.

자산을 변환하거나 렌더링 세션을 스핀업하는 메서드는 장기 실행 작업으로 모델링됩니다. 클라이언트는 LROPoller 또는 AsyncLROPoller를 반환하는 메서드를 노출 begin_<method-name> 합니다. 호출자는 메서드에서 begin_<method-name> 반환된 폴러 개체에서 result()를 호출하여 작업이 완료되기를 기다려야 합니다. 샘플 코드 조각은 아래의 장기 실행 작업 를 사용하여 설명하기 위해 제공됩니다.

예제

자산 변환

RemoteRenderingClient가 클라이언트 인증 섹션에 설명된 대로 생성되었다고 가정합니다. 다음 코드 조각에서는 지정된 스토리지 컨테이너 URI에서 Blob 컨테이너의 "/input/box/box.fbx" 경로에 있는 "box.fbx"가 변환되도록 요청하는 방법을 설명합니다.

자산을 변환하는 데 몇 초에서 몇 시간까지 걸릴 수 있습니다. 이 코드는 기존 변환 폴러를 사용하고 변환이 완료되거나 실패할 때까지 정기적으로 폴링합니다. 기본 폴링 기간은 5초입니다. 변환 폴러는 기존 변환 및 클라이언트의 ID를 사용하여 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뿐만 아니라 모든 변환 및 인쇄 ID 및 생성 광고도 나열합니다.

    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 Remote Rendering 관련된 일반적인 문제 해결 조언은 docs.microsoft.com 원격 렌더링 문제 해결 페이지를 참조하세요.

클라이언트 메서드 및 폴러 결과 대기는 요청이 실패한 경우 예외를 throw합니다.

변환의 자산이 유효하지 않은 경우 변환 폴러는 세부 정보가 포함된 오류와 함께 예외를 throw합니다. 변환 서비스가 파일을 <처리할 수 있게 되면 assetName.result.json> 파일이 출력 컨테이너에 기록됩니다. 입력 자산이 유효하지 않으면 해당 파일에 문제에 대한 자세한 설명이 포함됩니다.

마찬가지로 세션이 요청될 때 세션이 오류 상태로 끝나는 경우도 있습니다. 폴러는 이 경우 오류에 대한 세부 정보가 포함된 예외를 throw합니다. 세션 오류는 일반적으로 일시적이며 새 세션 요청이 성공해야 합니다.

로깅

이 라이브러리는 로깅에 표준 [로깅][python_logging] 라이브러리를 사용합니다.

HTTP 세션(URL, 헤더 등)에 대한 기본 정보는 수준에서 기록됩니다 INFO .

DEBUG 요청/응답 본문 및 수정되지 않은 헤더를 포함한 자세한 수준 로깅은 클라이언트 또는 키워드(keyword) 인수를 logging_enable 사용하여 작업별로 사용하도록 설정할 수 있습니다.

여기에 예제가 있는 전체 SDK 로깅 설명서를 참조 하세요.

선택적 구성

선택적 키워드(keyword) 인수는 클라이언트 및 작업별 수준에서 전달할 수 있습니다. azure-core 참조 설명서 에서는 재시도, 로깅, 전송 프로토콜 등에 사용할 수 있는 구성에 대해 설명합니다.

예외

Remote Rendering 클라이언트 라이브러리는 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을 적절하게 데코레이팅해야 하는지 여부를 자동으로 결정합니다(예: 레이블, 설명). 봇에서 제공하는 지침을 따르기만 하면 됩니다. 이 작업은 CLA를 사용하여 모든 리포지토리에서 한 번만 수행하면 됩니다.

이 프로젝트에는 Microsoft Open Source Code of Conduct(Microsoft 오픈 소스 준수 사항)가 적용됩니다. 자세한 내용은 Code of Conduct FAQ(규정 FAQ)를 참조하세요. 또는 추가 질문이나 의견은 opencode@microsoft.com으로 문의하세요.

이 라이브러리에 기여하려면 기여 가이드 를 참조하여 코드를 빌드하고 테스트하는 방법에 대해 자세히 알아보세요.

Impressions