JavaScript용 Azure Remote Rendering 클라이언트 라이브러리 - 버전 1.0.0-beta.1

  • 아티클

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

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

참고: 세션이 실행되면 클라이언트 애플리케이션은 "런타임 SDK" 중 하나를 사용하여 연결합니다. 이러한 SDK는 3D 렌더링을 수행하는 대화형 애플리케이션의 요구 사항을 가장 잘 지원하도록 설계되었습니다. (.net 또는 (C++)에서 사용할 수 있습니다.

제품 설명서

시작

현재 지원되는 환경

사전 요구 사항

이 패키지를 사용하려면 Azure 구독 및 Azure Remote Rendering 계정이 필요합니다.

@azure/mixed-reality-remote-rendering 패키지를 설치합니다.

를 사용하여 JavaScript용 템플릿 클라이언트 라이브러리를 npm설치합니다.

npm install @azure/mixed-reality-remote-rendering

브라우저 지원

JavaScript 번들

브라우저에서 이 클라이언트 라이브러리를 사용하려면 먼저 번들러를 사용해야 합니다. 이 작업을 수행하는 방법에 대한 자세한 내용은 번들링 설명서를 참조하세요.

CORS

이 라이브러리는 브라우저에서 Azure Remote Rendering 서비스를 직접 호출하는 데 사용할 수 없습니다. 지침은 이 문서를 참조하세요.

클라이언트 인증

원격 렌더링 클라이언트를 생성하려면 인증된 계정과 원격 렌더링 엔드포인트가 필요합니다. 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 토큰을 가져오는 것이 좋습니다. 클라이언트 애플리케이션에 Azure Spatial Anchors에 액세스하기 위한 자격 증명을 포함하지 않도록 할 수 있으므로 프로덕션 애플리케이션에 이 방법을 사용하는 것이 좋습니다.

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

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

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

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

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

개체를 AccountKeyCredential 사용하여 계정 식별자 및 계정 키를 사용하여 인증합니다.

const credential = new AzureKeyCredential(accountKey);

const client = new RemoteRenderingClient(serviceEndpoint, accountId, accountDomain, credential);

AAD 클라이언트 암호를 사용하여 인증

개체를 ClientSecretCredential 사용하여 클라이언트 비밀 인증을 수행합니다.

let credential = new ClientSecretCredential(tenantId, clientId, clientSecret, {
  authorityHost: "https://login.microsoftonline.com/" + tenantId
});

const client = new RemoteRenderingClient(serviceEndpoint, accountId, accountDomain, credential);

디바이스 코드 인증을 사용하여 사용자 인증

개체를 DeviceCodeCredential 사용하여 디바이스 코드 인증을 수행합니다.

let deviceCodeCallback = (deviceCodeInfo: DeviceCodeInfo) => {
  console.debug(deviceCodeInfo.message);
  console.log(deviceCodeInfo.message);
};

let credential = new DeviceCodeCredential(tenantId, clientId, deviceCodeCallback, {
  authorityHost: "https://login.microsoftonline.com/" + tenantId
});

const client = new RemoteRenderingClient(serviceEndpoint, accountId, accountDomain, credential);

디바이스 코드 인증 흐름 사용에 대한 자세한 내용은 여기 를 참조하세요.

DefaultAzureCredential을 사용한 대화형 인증

와 함께 includeInteractiveCredentials: true 개체를 DefaultAzureCredential 사용하여 기본 대화형 인증 흐름을 사용합니다.

let credential = new DefaultAzureCredential();

return new RemoteRenderingClient(serviceEndpoint, accountId, accountDomain, credential, {
  authenticationEndpointUrl: "https://sts.mixedreality.azure.com"
});

정적 액세스 토큰으로 인증

Mixed Reality 액세스 토큰을 이전에 Mixed Reality STS 서비스에서 검색한 것으로 AccessToken 전달하여 Mixed Reality 클라이언트 라이브러리와 함께 사용할 수 있습니다.

// GetMixedRealityAccessTokenFromWebService is a hypothetical method that retrieves
// a Mixed Reality access token from a web service. The web service would use the
// MixedRealityStsClient and credentials to obtain an access token to be returned
// to the client.
const accessToken = GetMixedRealityAccessTokenFromWebService();

RemoteRenderingClient client = new RemoteRenderingClient(remoteRenderingEndpoint, accountId, accessToken);

주요 개념

RemoteRenderingClient

는 RemoteRenderingClient RemoteRenderingService에 액세스하는 데 사용되는 클라이언트 라이브러리입니다. 자산 변환 및 렌더링 세션을 만들고 관리하는 메서드를 제공합니다.

예제

단순 자산 변환

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

const inputSettings: AssetConversionInputSettings = {
  storageContainerUrl,
  relativeInputAssetPath: "box.fbx"
};
const outputSettings: AssetConversionOutputSettings = {
  storageContainerUrl
};
const conversionSettings: AssetConversionSettings = { inputSettings, outputSettings };

// A randomly generated UUID is a good choice for a conversionId.
const conversionId = uuid();

const conversionPoller: AssetConversionPollerLike = await client.beginConversion(
  conversionId,
  conversionSettings
);

출력 파일은 입력 자산 옆에 배치됩니다.

더 복잡한 자산 변환

자산은 다른 파일을 참조할 수 있으며 Blob 컨테이너에는 다양한 자산에 속하는 파일이 포함될 수 있습니다. 이 예제에서는 접두사를 사용하여 Blob을 구성하는 방법과 해당 조직을 고려하여 자산을 변환하는 방법을 보여 줍니다. 의 inputStorageUrl Blob 컨테이너에 "Bike/bike.gltf", "Bike/bike.bin" 및 "Bike/saddleTexture.jpg"을 비롯한 많은 파일이 포함되어 있다고 가정합니다. (따라서 접두사 "Bike"는 폴더처럼 작동합니다.) 변환 서비스에서 다른 파일에 액세스할 필요 없이 접두사를 공유하는 다른 파일에 액세스할 수 있도록 glTF를 변환하려고 합니다. 작업을 깔끔하게 유지하기 위해 출력 파일을 다른 스토리지 컨테이너에 쓰고 일반적인 접두사인 "ConvertedBicycle"을 지정하려고 합니다. 코드는 다음과 같습니다.

  const inputSettings: AssetConversionInputSettings = {
    storageContainerUrl: inputStorageUrl,
    blobPrefix: "Bicycle"
    relativeInputAssetPath: "bicycle.gltf"
  };
  const outputSettings: AssetConversionOutputSettings = {
    storageContainerUrl: outputStorageUrl,
    blobPrefix: "ConvertedBicycle"
  };
  const conversionSettings: AssetConversionSettings = { inputSettings, outputSettings };

  const conversionId = uuid();

  const conversionPoller: AssetConversionPollerLike = await client.beginConversion(
    conversionId,
    conversionSettings
  );

참고: 입력 옵션에 접두사를 지정하면 입력 파일 매개 변수가 해당 접두사를 기준으로 하는 것으로 간주됩니다. 출력 옵션의 출력 파일 매개 변수도 마찬가지입니다.

자산 변환이 완료되면 출력 가져오기

자산을 변환하는 데 몇 초에서 몇 시간 정도 걸릴 수 있습니다. 이 코드는 beginConversion에서 반환된 conversionPoller를 사용하여 변환이 완료되거나 실패할 때까지 정기적으로 폴링합니다. 기본 폴링 기간은 10초입니다.

const conversion = await conversionPoller.pollUntilDone();

console.log("== Check results ==");

if (conversion.status === "Succeeded") {
  console.log("Conversion succeeded: Output written to " + conversion.output?.outputAssetUrl);
} else if (conversion.status === "Failed") {
  console.log("Conversion failed: " + conversion.error.code + " " + conversion.error.message);
}

AssetConversionPollerLike의 상태는 conversionPoller.toString()을 호출하여 serialize할 수 있습니다. 이 값은 나중에 beginConversion에 값으로 resumeFrom 전달되어 이전 폴러가 중단된 위치에서 수행되는 새 폴러를 생성할 수 있습니다.

const serializedPollerString = conversionPoller.toString();
// ...
const resumedPoller = client.beginConversion({ resumeFrom: serializedPollerString });

변환 나열

메서드를 사용하여 getConversions 변환에 대한 정보를 가져올 수 있습니다. 이 메서드는 아직 시작되지 않은 변환, 실행 중인 변환 및 완료된 변환을 반환할 수 있습니다. 이 예제에서는 마지막 날에 시작된 성공적인 변환의 출력 URI만 나열합니다.

for await (const conversion of client.listConversions()) {
  if (conversion.status === "Succeeded") {
    console.log(
      `Conversion ${conversion.conversionId} succeeded: Output written to ${conversion.output?.outputAssetUrl}`
    );
  } else if (conversion.status === "Failed") {
    console.log(
      `Conversion ${conversion.conversionId} failed: ${conversion.error.code} ${conversion.error.message}`
    );
  }
}

세션 만들기

RemoteRenderingClient가 클라이언트 인증 섹션에 설명된 대로 생성되었다고 가정합니다. 다음 코드 조각에서는 새 렌더링 세션을 시작하도록 요청하는 방법을 설명합니다.

const sessionSettings: RenderingSessionSettings = {
  maxLeaseTimeInMinutes: 4,
  size: "Standard"
};

// A randomly generated UUID is a good choice for a conversionId.
const sessionId = uuid();

const sessionPoller: RenderingSessionPollerLike = await client.beginSession(
  sessionId,
  sessionSettings
);

RenderingSessionPollerLike의 상태는 toString()을 호출하여 serialize할 수 있습니다. 이 값은 나중에 beginSession에 값으로 resumeFrom 전달되어 이전 폴러가 중단된 위치에서 수행되는 새 폴러를 생성할 수 있습니다.

const serializedPollerString = sessionPoller.toString();
// ...
const resumedPoller = client.beginSession({ resumeFrom: serializedPollerString });

세션의 임대 시간 연장

세션이 최대 임대 시간에 가까워지고 있지만 활성 상태로 유지하려는 경우 최대 임대 시간을 늘리기 위해 호출해야 합니다. 이 예제에서는 현재 속성을 쿼리한 다음 곧 만료될 경우 임대를 확장하는 방법을 보여 있습니다.

참고: 런타임 SDK는 이 기능도 제공하며, 일반적인 많은 시나리오에서는 이를 사용하여 세션 임대를 확장합니다.

/// When the lease is within 2 minutes of expiring, extend it by 15 minutes.
let currentSession = await client.getSession(sessionId);
if (currentSession.status == "Ready") {
  if (
    currentSession.maxLeaseTimeInMinutes -
      (Date.now() - currentSession.properties.createdOn.valueOf()) / 60000 <
    2
  ) {
    let newLeaseTime = currentSession.maxLeaseTimeInMinutes + 15;

    await client.updateSession(sessionId, { maxLeaseTimeInMinutes: newLeaseTime });
  }
}

세션 나열

메서드를 사용하여 getSessions 세션에 대한 정보를 가져올 수 있습니다. 이 메서드는 아직 시작되지 않은 세션과 준비된 세션을 반환할 수 있습니다.

for await (const session of client.listSessions()) {
  console.log(`Session ${session.sessionId} is ${session.status}`);
}

세션 중지

다음 코드는 지정된 ID를 사용하여 실행 중인 세션을 중지합니다.

client.endSession(sessionId);

문제 해결

로깅

로깅을 사용하도록 설정하면 실패에 대한 유용한 정보를 파악하는 데 도움이 될 수 있습니다. HTTP 요청 및 응답 로그를 보려면 AZURE_LOG_LEVEL 환경 변수를 info로 설정합니다. 또는 @azure/logger에서 setLogLevel을 호출하여 런타임에 로깅을 사용하도록 설정할 수 있습니다.

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Azure Remote Rendering 문제 해결

Azure Remote Rendering 관련된 일반적인 문제 해결 조언은 docs.microsoft.com 원격 렌더링 문제 해결 페이지를 참조하세요.

요청을 수행할 수 없는 경우 클라이언트 메서드는 예외를 throw합니다. 그러나 변환 및 세션의 경우 요청이 성공할 수 있지만 요청된 작업이 성공하지 못할 수 있습니다. 이 경우 예외는 throw되지 않지만 반환된 개체를 검사하여 발생한 작업을 파악할 수 있습니다.

변환의 자산이 유효하지 않으면 변환 작업은 Failed 상태의 AssetConversion 개체를 반환하고 세부 정보가 포함된 RemoteRenderingServiceError를 전달합니다. 변환 서비스가 파일을 <처리할 수 있게 되면 assetName.result.json> 파일이 출력 컨테이너에 기록됩니다. 입력 자산이 유효하지 않으면 해당 파일에 문제에 대한 자세한 설명이 포함됩니다.

마찬가지로 세션이 요청될 때 세션이 오류 상태로 끝나는 경우도 있습니다. startSessionOperation 메서드는 RenderingSession 개체를 반환하지만 해당 개체는 Error 상태를 가지며 세부 정보가 포함된 RemoteRenderingServiceError를 수행합니다.

다음 단계

참여

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

Impressions