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.net lub (C++).

dokumentacja produktu

Wprowadzenie

Obecnie obsługiwane środowiska

  • wersje Node.js LTS
  • Najnowsze wersje przeglądarek Safari, Chrome, Edge i Firefox.

Warunki wstępne

Do korzystania z tego pakietu potrzebny będzie subskrypcji platformy Azure oraz konto usługi Azure Remote Rendering .

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

Zainstaluj bibliotekę klienta szablonu dla języka JavaScript przy użyciu 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ć pakietu. Aby uzyskać szczegółowe informacje o tym, jak to zrobić, zapoznaj się z naszą dokumentacją dotyczącą tworzenia pakietów .

MECHANIZM 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 konta 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 usługi Azure AD.
  • Uwierzytelnianie tokenu usługi Azure Active Directory (AD)
    • Jeśli tworzysz aplikację dla przedsiębiorstw, a twoja firma używa usługi Azure AD jako systemu tożsamości, możesz użyć uwierzytelniania usługi 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ń usługi Azure AD. Możesz również udzielić dostępu bezpośrednio użytkownikom w organizacji.
    • W przeciwnym razie zalecamy uzyskanie tokenów usługi Azure AD z usługi internetowej obsługującej aplikację. Zalecamy tę metodę dla aplikacji produkcyjnych, ponieważ pozwala uniknąć osadzania poświadczeń w aplikacji klienckiej.

Aby uzyskać szczegółowe instrukcje i informacje, zobacz tutaj.

We wszystkich poniższych przykładach klient jest konstruowany przy użyciu 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ę. Przykładem jest 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ń przy użyciu usługi. Czas potrzebny na komunikację z serwerem ma wpływ na jakość środowiska.

Uwierzytelnianie przy użyciu uwierzytelniania za pomocą klucza konta

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

const credential = new AzureKeyCredential(accountKey);

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

Uwierzytelnianie za pomocą wpisu tajnego klienta usługi AAD

Użyj obiektu ClientSecretCredential, 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 kodu urządzenia

Użyj obiektu DeviceCodeCredential, aby przeprowadzić uwierzytelnianie 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);

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

Uwierzytelnianie interakcyjne z ustawieniem DefaultAzureCredential

Użyj obiektu DefaultAzureCredential z includeInteractiveCredentials: true, 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 tokenu dostępu statycznego

Token dostępu rzeczywistości mieszanej można przekazać jako AccessToken wcześniej pobrany z usługi Mixed Reality STS do użycia z biblioteką klienta rzeczywistości mieszanej:

// 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

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 zasobu

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żywać prefiksów do organizowania obiektów blob i sposobu konwertowania elementu zawartości, aby uwzględnić tę organizację. Załóżmy, że kontener obiektów blob w inputStorageUrl zawiera wiele plików, w tym "Bicycle/bicycle.gltf", "Bicycle/bicycle.bin" i "Bicycle/saddleTexture.jpg". (Prefiks "Rower" działa bardzo jak folder). Chcemy przekonwertować plik glTF tak, aby miał dostęp do innych plików, które współużytkować 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 elementu beginConversion jako wartość resumeFrom, aby utworzyć nową etykietę, która 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 metody getConversions. Ta metoda może zwracać 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świetlimy wyjściowe identyfikatory URI pomyślnych konwersji rozpoczętych w ciągu ostatniego dnia.

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 wartości beginSession jako resumeFrom, aby utworzyć nową etykietę, która przechodzi od miejsca, w którym 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 metody getSessions. 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ę o podanym identyfikatorze.

client.endSession(sessionId);

Rozwiązywanie problemów

Wyrąb

Włączenie rejestrowania może pomóc odkryć przydatne informacje o błędach. Aby wyświetlić dziennik żądań i odpowiedzi HTTP, ustaw zmienną środowiskową AZURE_LOG_LEVEL na info. Alternatywnie rejestrowanie można włączyć w czasie wykonywania, wywołując setLogLevel w @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 na potrzeby renderowania zdalnego 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 będzie zawierać błąd 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, gdy żądana jest sesja, 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

Przyczyniając się

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

wrażenia