Klientská knihovna Azure Remote Rendering pro JavaScript – verze 1.0.0-beta.1

  • Článek

Azure Remote Rendering (ARR) je služba, která umožňuje vykreslovat vysoce kvalitní interaktivní 3D obsah v cloudu a streamovat ho v reálném čase do zařízení, jako je HoloLens 2.

Tato sada SDK nabízí funkce pro převod prostředků do formátu očekávaného modulem runtime a také pro správu životnosti relací vzdáleného vykreslování.

POZNÁMKA: Po spuštění relace se k ní klientská aplikace připojí pomocí jedné ze sad SDK modulu runtime. Tyto sady SDK jsou navržené tak, aby co nejlépe podporovaly potřeby interaktivní aplikace provádějící 3D vykreslování. Jsou k dispozici v (.net nebo (C++).

Produktová dokumentace

Začínáme

Aktuálně podporovaná prostředí

  • LtS verze Node.js
  • Nejnovější verze prohlížečů Safari, Chrome, Edge a Firefox.

Požadavky

K použití tohoto balíčku budete potřebovat předplatné Azure a účet Azure Remote Rendering.

Nainstalujte balíček @azure/mixed-reality-remote-rendering.

Nainstalujte klientskou knihovnu šablon pro JavaScript pomocí npm:

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

Podpora prohlížečů

JavaScript Bundle

Pokud chcete tuto klientskou knihovnu používat v prohlížeči, musíte nejprve použít nástroj bundler. Podrobnosti o tom, jak to udělat, najdete v naší dokumentaci k sdružování.

CORS

Tuto knihovnu nelze použít k přímému volání služby Azure Remote Rendering z prohlížeče. Pokyny najdete v tomto dokumentu .

Ověření klienta

Sestavení vzdáleného klienta vykreslování vyžaduje ověřený účet a koncový bod vzdáleného vykreslování. Pro účet vytvořený v oblasti eastus bude mít doména účtu tvar "eastus.mixedreality.azure.com". Existuje několik různých forem ověřování:

  • Ověřování pomocí klíče účtu
    • Klíče účtu umožňují rychle začít používat Azure Remote Rendering. Než ale aplikaci nasadíte do produkčního prostředí, doporučujeme aktualizovat ji tak, aby používala ověřování Azure AD.
  • Ověřování pomocí tokenu Azure Active Directory (AD)
    • Pokud vytváříte podnikovou aplikaci a vaše společnost používá jako systém identit Azure AD, můžete v aplikaci použít ověřování založené na uživatelích Azure AD. Přístup k účtům Azure Remote Rendering pak udělíte pomocí stávajících skupin zabezpečení Azure AD. Můžete také udělit přístup přímo uživatelům ve vaší organizaci.
    • V opačném případě doporučujeme získat tokeny Azure AD z webové služby, která podporuje vaši aplikaci. Tuto metodu doporučujeme pro produkční aplikace, protože umožňuje vyhnout se vkládání přihlašovacích údajů pro přístup k Azure Spatial Anchors do klientské aplikace.

Podrobné pokyny a informace najdete tady .

Ve všech následujících příkladech je klient vytvořen pomocí remoteRenderingEndpoint. Dostupné koncové body odpovídají oblastem a volba koncového bodu určuje oblast, ve které služba provádí svoji práci. Příklad: https://remoterendering.eastus2.mixedreality.azure.com.

POZNÁMKA: Pro převod prostředků je vhodnější vybrat oblast blízko úložiště obsahujícího prostředky.

POZNÁMKA: Pro vykreslování se důrazně doporučuje vybrat oblast, která je k zařízením pomocí služby nejblíže. Doba potřebná ke komunikaci se serverem má vliv na kvalitu prostředí.

Ověřování pomocí klíče účtu

Pomocí objektu AccountKeyCredential použijte identifikátor účtu a klíč účtu k ověření:

const credential = new AzureKeyCredential(accountKey);

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

Ověřování pomocí tajného klíče klienta AAD

Pomocí objektu ClientSecretCredential proveďte ověřování pomocí tajného klíče klienta.

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

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

Ověřování uživatele pomocí ověřování kódu zařízení

Pomocí objektu DeviceCodeCredential proveďte ověření kódu zařízení.

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

Další informace o použití toku ověřování kódu zařízení najdete tady .

Interaktivní ověřování s využitím DefaultAzureCredential

Pomocí objektu DefaultAzureCredential s includeInteractiveCredentials: true použijte výchozí tok interaktivního ověřování:

let credential = new DefaultAzureCredential();

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

Ověřování pomocí statického přístupového tokenu

Přístupový token Mixed Reality můžete předat jako AccessToken dříve načtený ze služby Mixed Reality STS, který se má použít s klientskou knihovnou 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);

Klíčové koncepty

RemoteRenderingClient

Je RemoteRenderingClient klientská knihovna používaná pro přístup ke službě RemoteRenderingService. Poskytuje metody pro vytváření a správu převodů prostředků a relací vykreslování.

Příklady

Převod jednoduchého prostředku

Předpokládáme, že remoteRenderingClient byl vytvořen podle popisu v části Ověření klienta . Následující fragment kódu popisuje, jak požádat o převod souboru "box.fbx", který se nachází v kořenovém adresáři kontejneru objektů blob v daném identifikátoru URI.

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

Výstupní soubory budou umístěny vedle vstupního prostředku.

Převod složitějšího prostředku

Prostředky můžou odkazovat na jiné soubory a kontejnery objektů blob můžou obsahovat soubory patřící mnoha různým prostředkům. V tomto příkladu si ukážeme, jak se předpony dají použít k uspořádání objektů blob a jak převést prostředek tak, aby se zohlednila tato organizace. Předpokládejme, že kontejner objektů blob na adrese inputStorageUrl obsahuje mnoho souborů, včetně souborů "Bicycle/bicycle.gltf", "Bicycle/bicycle.bin" a "Bicycle/saddleTexture.jpg". (Předpona "Bicycle" se chová velmi jako složka.) Chceme převést glTF tak, aby měly přístup k ostatním souborům, které sdílejí předponu, aniž by převodní služba vyžadovala přístup k jiným souborům. Aby bylo vše přehledné, chceme také, aby se výstupní soubory zapisovaly do jiného kontejneru úložiště a dostaly společnou předponu ConvertedBicycle. Kód je následující:

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

POZNÁMKA: Pokud je předpona uvedena ve vstupních možnostech, předpokládá se, že parametr vstupního souboru je relativní k této předponě. Totéž platí pro parametr výstupního souboru v možnostech výstupu.

Získání výstupu po dokončení převodu prostředku

Převod prostředku může trvat od sekund až po hodiny. Tento kód používá conversionPoller vrácený metodou beginConversion k pravidelnému dotazování, dokud se převod nedokončí nebo se nezdaří. Výchozí doba dotazování je 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);
}

Všimněte si, že stav AssetConversionPollerLike lze serializovat voláním conversionPoller.toString(). Tato hodnota může být později předána do beginConversion jako resumeFrom hodnota, aby se vytvořil nový poller, který pokračuje od místa, kde předchozí hodnota skončila:

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

Převody seznamů

Informace o převodech můžete získat pomocí getConversions metody . Tato metoda může vrátit převody, které ještě nebyly zahájeny, převody, které jsou spuštěny, a převody, které byly dokončeny. V tomto příkladu uvádíme jenom výstupní identifikátory URI úspěšných převodů zahájených za poslední den.

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

Vytvoření relace

Předpokládáme, že remoteRenderingClient byl vytvořen podle popisu v části Ověření klienta . Následující fragment kódu popisuje, jak požádat o spuštění nové relace vykreslování.

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

Všimněte si, že stav RenderingSessionPollerLike lze serializovat voláním metody toString(). Tato hodnota může být později předána do beginSession jako resumeFrom hodnota, aby se vytvořil nový poller, který pokračuje od místa, kde předchozí poller skončil:

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

Prodloužení doby zapůjčení relace

Pokud se relace blíží maximální době zapůjčení, ale vy ji chcete zachovat, budete muset zavolat a prodloužit maximální dobu zapůjčení. Tento příklad ukazuje, jak dotazovat aktuální vlastnosti a pak prodloužit zapůjčení, pokud brzy vyprší jeho platnost.

POZNÁMKA: Tuto funkci nabízejí také sady SDK modulu runtime a v mnoha typických scénářích byste je použili k prodloužení zapůjčení relace.

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

Výpis relací

Informace o relacích můžete získat pomocí getSessions metody . Tato metoda může vrátit relace, které ještě nebyly zahájeny, a relace, které jsou připravené.

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

Zastavení relace

Následující kód zastaví spuštěnou relaci se zadaným ID.

client.endSession(sessionId);

Řešení potíží

protokolování

Povolení protokolování může pomoct odhalit užitečné informace o selháních. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou AZURE_LOG_LEVEL prostředí na info. Případně je možné protokolování povolit za běhu voláním setLogLevel v :@azure/logger

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

setLogLevel("info");

Řešení potíží se službou Azure Remote Rendering

Obecné rady k řešení potíží se službou Azure Remote Rendering najdete na stránce Řešení potíží se vzdáleným vykreslováním na docs.microsoft.com.

Klientské metody vyvolají výjimky, pokud požadavek nelze vytvořit. V případě převodů i relací však mohou být požadavky úspěšné, ale požadovaná operace nemusí být úspěšná. V takovém případě se nevyvolá žádná výjimka, ale vrácené objekty je možné zkontrolovat, abyste pochopili, co se stalo.

Pokud je prostředek v převodu neplatný, operace převodu vrátí objekt AssetConversion se stavem Failed a nese RemoteRenderingServiceError s podrobnostmi. Jakmile bude převodní služba schopna soubor zpracovat, zapíše se do výstupního kontejneru <soubor assetName.result.json>. Pokud je vstupní prostředek neplatný, bude tento soubor obsahovat podrobnější popis problému.

Podobně někdy, když je relace požadována, skončí relace v chybovém stavu. Metoda startSessionOperation vrátí objekt RenderingSession, ale tento objekt bude mít stav Error a bude obsahovat RemoteRenderingServiceError s podrobnostmi.

Další kroky

Přispívání

Pokud chcete přispívat do této knihovny, přečtěte si příručku pro přispívání , kde najdete další informace o tom, jak sestavit a otestovat kód.

Imprese