Udostępnij za pośrednictwem

Biblioteka klienta usługi Azure Remote Rendering dla języka JavaScript — wersja 1.0.0-beta.1

  • Artykuł

Azure Remote Rendering (ARR) to usługa, która umożliwia renderowanie wysokiej jakości, interaktywnej zawartości 3D w chmurze i przesyłanie strumieniowe jej w czasie rzeczywistym do urządzeń, takich jak HoloLens 2.

Ten zestaw SDK oferuje funkcje umożliwiające konwertowanie zasobów na format oczekiwany przez środowisko uruchomieniowe, a także zarządzanie okresem istnienia sesji renderowania zdalnego.

UWAGA: Po uruchomieniu sesji aplikacja kliencka połączy się z nią przy użyciu jednego z "zestawów SDK środowiska uruchomieniowego". Te zestawy SDK są zaprojektowane tak, aby najlepiej obsługiwały potrzeby interaktywnej aplikacji wykonującej renderowanie 3d. Są one dostępne w programie (.net lub (C++).

Dokumentacja produktu

Wprowadzenie

Obecnie obsługiwane środowiska

Wymagania wstępne

Do korzystania z tego pakietu potrzebna będzie subskrypcja platformy Azure i konto usługi Azure Remote Rendering.

Instalowanie pakietu @azure/mixed-reality-remote-rendering

Zainstaluj bibliotekę klienta szablonu dla języka JavaScript za pomocą polecenia npm:

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

Obsługa przeglądarki

Pakiet JavaScript

Aby użyć tej biblioteki klienta w przeglądarce, najpierw należy użyć narzędzia bundler. Aby uzyskać szczegółowe informacje o tym, jak to zrobić, zapoznaj się z naszą dokumentacją dotyczącą tworzenia pakietów.

CORS

Tej biblioteki nie można używać do wykonywania bezpośrednich wywołań do usługi Azure Remote Rendering z przeglądarki. Aby uzyskać wskazówki, zapoznaj się z tym dokumentem .

Uwierzytelnianie klienta

Konstruowanie klienta renderowania zdalnego wymaga uwierzytelnionego konta i punktu końcowego renderowania zdalnego. W przypadku konta utworzonego w regionie eastus domena konta będzie mieć formularz "eastus.mixedreality.azure.com". Istnieje kilka różnych form uwierzytelniania:

  • Uwierzytelnianie za pomocą klucza konta
    • Klucze kont umożliwiają szybkie rozpoczęcie pracy przy użyciu usługi Azure Remote Rendering. Jednak przed wdrożeniem aplikacji w środowisku produkcyjnym zalecamy zaktualizowanie aplikacji tak, aby korzystała z uwierzytelniania Azure AD.
  • Uwierzytelnianie tokenu usługi Azure Active Directory (AD)
    • Jeśli tworzysz aplikację dla przedsiębiorstw, a twoja firma używa Azure AD jako systemu tożsamości, możesz użyć uwierzytelniania Azure AD opartego na użytkownikach w aplikacji. Następnie udzielasz dostępu do kont usługi Azure Remote Rendering przy użyciu istniejących grup zabezpieczeń Azure AD. Możesz również udzielić dostępu bezpośrednio użytkownikom w organizacji.
    • W przeciwnym razie zalecamy uzyskanie Azure AD tokenów z usługi internetowej obsługującej aplikację. Zalecamy tę metodę dla aplikacji produkcyjnych, ponieważ pozwala uniknąć osadzania poświadczeń w celu uzyskania dostępu do usługi Azure Spatial Anchors w aplikacji klienckiej.

Zobacz tutaj , aby uzyskać szczegółowe instrukcje i informacje.

We wszystkich poniższych przykładach klient jest konstruowany przy użyciu elementu remoteRenderingEndpoint. Dostępne punkty końcowe odpowiadają regionom, a wybór punktu końcowego określa region, w którym usługa wykonuje swoją pracę. Może to być na przykład https://remoterendering.eastus2.mixedreality.azure.com.

UWAGA: W przypadku konwertowania zasobów zaleca się wybranie regionu w pobliżu magazynu zawierającego zasoby.

UWAGA: W przypadku renderowania zdecydowanie zaleca się wybranie najbliższego regionu do urządzeń korzystających z usługi. Czas potrzebny na komunikację z serwerem ma wpływ na jakość środowiska.

Uwierzytelnianie przy użyciu uwierzytelniania za pomocą klucza konta

AccountKeyCredential Użyj obiektu , aby użyć identyfikatora konta i klucza konta do uwierzytelniania:

const credential = new AzureKeyCredential(accountKey);

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

Uwierzytelnianie przy użyciu klucza tajnego klienta usługi AAD

ClientSecretCredential Użyj obiektu , aby przeprowadzić uwierzytelnianie wpisów tajnych klienta.

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

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

Uwierzytelnianie użytkownika przy użyciu uwierzytelniania za pomocą kodu urządzenia

DeviceCodeCredential Użyj obiektu , aby przeprowadzić uwierzytelnianie za pomocą kodu urządzenia.

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);

Zobacz tutaj , aby uzyskać więcej informacji na temat korzystania z przepływu uwierzytelniania kodu urządzenia.

Uwierzytelnianie interakcyjne za pomocą ustawienia DefaultAzureCredential

Użyj obiektu z includeInteractiveCredentials: true , DefaultAzureCredential aby użyć domyślnego przepływu uwierzytelniania interakcyjnego:

let credential = new DefaultAzureCredential();

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

Uwierzytelnianie przy użyciu statycznego tokenu dostępu

Token dostępu Mixed Reality można przekazać jako AccessToken wcześniej pobrany z usługi Mixed Reality STS do użycia z biblioteką klienta 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);

Kluczowe pojęcia

RemoteRenderingClient

Jest RemoteRenderingClient to biblioteka klienta używana do uzyskiwania dostępu do usługi RemoteRenderingService. Udostępnia metody tworzenia konwersji zasobów i renderowania sesji oraz zarządzania nimi.

Przykłady

Konwertowanie prostego elementu zawartości

Przyjęto założenie, że obiekt RemoteRenderingClient został skonstruowany zgodnie z opisem w sekcji Uwierzytelnianie klienta . Poniższy fragment kodu opisuje sposób żądania, że element "box.fbx" znajduje się w katalogu głównym kontenera obiektów blob w danym identyfikatorze URI, jest konwertowany.

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
);

Pliki wyjściowe zostaną umieszczone obok elementu zawartości wejściowej.

Konwertowanie bardziej złożonego elementu zawartości

Zasoby mogą odwoływać się do innych plików, a kontenery obiektów blob mogą zawierać pliki należące do wielu różnych zasobów. W tym przykładzie pokazano, jak można użyć prefiksów do organizowania obiektów blob i sposobu konwertowania elementu zawartości w celu uwzględnienia tej organizacji. Załóżmy, że kontener obiektów blob w lokalizacji inputStorageUrl zawiera wiele plików, w tym "Bicycle/bicycle.gltf", "Bicycle/bicycle.bin" i "Bicycle/saddleTexture.jpg". (Więc prefiks "Rower" działa bardzo jak folder.) Chcemy przekonwertować plik glTF tak, aby miał dostęp do innych plików, które współdzielą prefiks, bez konieczności uzyskiwania dostępu do innych plików przez usługę konwersji. Aby zachować porządek, chcemy również zapisywać pliki wyjściowe w innym kontenerze magazynu i mieć wspólny prefiks: "ConvertedBicycle". Kod jest następujący:

  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
  );

UWAGA: jeśli prefiks jest podany w opcjach wejściowych, przyjmuje się, że parametr pliku wejściowego jest względny względem tego prefiksu. To samo dotyczy parametru pliku wyjściowego w opcjach wyjściowych.

Pobieranie danych wyjściowych po zakończeniu konwersji zasobów

Konwertowanie elementu zawartości może potrwać od kilku sekund do godzin. Ten kod używa elementu conversionPoller zwróconego przez element beginConversion do regularnego sondowania do momentu zakończenia lub niepowodzenia konwersji. Domyślny okres sondowania to 10 sekund.

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);
}

Należy pamiętać, że stan elementu AssetConversionPollerLike można serializować przez wywołanie metody conversionPoller.toString(). Tę wartość można później przekazać do właściwości beginConversion jako resumeFrom wartość, aby utworzyć nowy element poller, który przechodzi od miejsca, w którym wcześniejsza wartość została przerwana:

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

Konwersje listy

Informacje o konwersjach można uzyskać przy użyciu getConversions metody . Ta metoda może zwrócić konwersje, które nie zostały jeszcze uruchomione, konwersje, które są uruchomione i konwersje, które zostały zakończone. W tym przykładzie po prostu wyświetlamy wyjściowe identyfikatory URI pomyślnych konwersji rozpoczętych w ostatnim dniu.

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}`
    );
  }
}

Tworzenie sesji

Przyjęto założenie, że obiekt RemoteRenderingClient został skonstruowany zgodnie z opisem w sekcji Uwierzytelnianie klienta . Poniższy fragment kodu opisuje sposób żądania uruchomienia nowej sesji renderowania.

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
);

Należy pamiętać, że stan elementu RenderingSessionPollerLike można serializować przez wywołanie metody toString(). Tę wartość można później przekazać do elementu beginSession jako resumeFrom wartość, aby utworzyć nowy element poller, który przechodzi dalej, gdzie wcześniejsza wartość została przerwana:

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

Wydłużenie czasu dzierżawy sesji

Jeśli sesja zbliża się do maksymalnego czasu dzierżawy, ale chcesz zachować ją przy życiu, musisz wykonać wywołanie, aby zwiększyć maksymalny czas dzierżawy. W tym przykładzie pokazano, jak wykonać zapytanie dotyczące bieżących właściwości, a następnie rozszerzyć dzierżawę, jeśli wkrótce wygaśnie.

UWAGA: Zestawy SDK środowiska uruchomieniowego oferują również tę funkcję, a w wielu typowych scenariuszach można ich użyć do rozszerzenia dzierżawy sesji.

/// 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 });
  }
}

Wyświetlanie listy sesji

Informacje o sesjach można uzyskać przy użyciu getSessions metody . Ta metoda może zwracać sesje, które nie zostały jeszcze uruchomione, i sesje, które są gotowe.

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

Zatrzymywanie sesji

Poniższy kod zatrzyma uruchomioną sesję z danym identyfikatorem.

client.endSession(sessionId);

Rozwiązywanie problemów

Rejestrowanie

Włączenie rejestrowania może pomóc odkryć przydatne informacje o błędach. Aby wyświetlić dziennik żądań HTTP i odpowiedzi, ustaw zmienną AZURE_LOG_LEVEL środowiskową na info. Możesz też włączyć rejestrowanie w czasie wykonywania, wywołując polecenie w elemecie setLogLevel@azure/logger:

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

setLogLevel("info");

Rozwiązywanie problemów z usługą Azure Remote Rendering

Aby uzyskać ogólne porady dotyczące rozwiązywania problemów dotyczące usługi Azure Remote Rendering, zobacz stronę Rozwiązywanie problemów z renderowaniem zdalnym w docs.microsoft.com.

Metody klienta będą zgłaszać wyjątki, jeśli nie można wykonać żądania. Jednak w przypadku konwersji i sesji żądania mogą zakończyć się powodzeniem, ale żądana operacja może zakończyć się niepowodzeniem. W takim przypadku nie zostanie zgłoszony żaden wyjątek, ale zwrócone obiekty można sprawdzić, aby zrozumieć, co się stało.

Jeśli zasób w konwersji jest nieprawidłowy, operacja konwersji zwróci obiekt AssetConversion ze stanem Niepowodzenie i przewożąc element RemoteRenderingServiceError ze szczegółami. Gdy usługa konwersji będzie mogła przetworzyć plik, <plik assetName.result.json> zostanie zapisany w kontenerze wyjściowym. Jeśli zasób wejściowy jest nieprawidłowy, ten plik będzie zawierać bardziej szczegółowy opis problemu.

Podobnie, czasami w przypadku żądania sesji sesja kończy się w stanie błędu. Metoda startSessionOperation zwróci obiekt RenderingSession, ale ten obiekt będzie miał stan Błąd i będzie miał stan RemoteRenderingServiceError ze szczegółami.

Następne kroki

Współtworzenie

Jeśli chcesz współtworzyć tę bibliotekę, przeczytaj przewodnik współtworzenia , aby dowiedzieć się więcej na temat sposobu kompilowania i testowania kodu.

Wrażenia