Sdílet prostřednictvím

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 vykreslit 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é správu životnosti relací vzdáleného vykreslování.

POZNÁMKA: Jakmile je relace spuštěná, klientská aplikace se k ní 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++).

dokumentace k produktu

Začínáme

Aktuálně podporovaná prostředí

Požadavky

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

Instalace balíčku @azure/mixed-reality-remote-rendering

Nainstalujte klientskou knihovnu šablon pro JavaScript s npm:

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

Podpora prohlížeče

JavaScript Bundle

Pokud chcete tuto klientskou knihovnu použít v prohlížeči, musíte nejprve použít bundler. Podrobnosti o tom, jak to udělat, najdete v naší dokumentaci 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

Vytvoření klienta vzdáleného 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 formulář "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 aplikaci aktualizovat tak, aby používala ověřování Azure AD.
  • Ověřování tokenu Azure Active Directory (AD)
    • Pokud vytváříte podnikovou aplikaci a vaše společnost používá Azure AD jako svůj systém identit, můžete ve své aplikaci použít ověřování Azure AD založené na uživatelích. Pak udělíte přístup k účtům Azure Remote Rendering 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ů 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í svou práci. Příkladem je 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í prostředky.

POZNÁMKA: Pro vykreslování důrazně doporučujeme vybrat nejbližší oblast k zařízením používajícím službu. 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 k ověření identifikátor účtu a klíč účtu:

const credential = new AzureKeyCredential(accountKey);

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

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

K ověření tajných kódů klienta použijte objekt ClientSecretCredential.

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í

K ověření kódu zařízení použijte objekt 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);

Další informace o používání 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í interaktivní tok 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 hybridní reality můžete předat jako AccessToken dříve načtený ze služby Služby zabezpečení hybridní reality, který se má použít s klientskou knihovnou hybridní 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

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

Příklady

Převod jednoduchého prostředku

Předpokládáme, že remoteRenderingClient byl vytvořen, jak je popsáno v části Ověření klienta. Následující fragment kódu popisuje, jak požádat o převod "box.fbx" 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 se umístí 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 dají předpony 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 v inputStorageUrl obsahuje mnoho souborů, včetně "Bicycle/bicycle.gltf", "Bicycle/bicycle.bin" a "Bicycle/saddleTexture.jpg". (Předpona "Kolo" funguje velmi jako složka.) Chceme převést glTF tak, aby má přístup k ostatním souborům, které sdílejí předponu, aniž by služba převodu potřebovala přístup k jiným souborům. Abychom zachovali přehled o věcech, chceme, aby se výstupní soubory zapisovaly do jiného kontejneru úložiště a daly 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 vstupní soubor parametr 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 několika sekund do hodin. Tento kód používá funkci conversionPoller vrácenou metodou beginConversion k pravidelnému dotazování, dokud převod nedokončí nebo se nezdaří. Výchozí období 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(). Tuto hodnotu lze později předat do beginConversion jako hodnotu resumeFrom, 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í metody getConversions. Tato metoda může vrátit převody, které ještě nejsou spuštěny, převody, které jsou spuštěny a převody, které byly dokončeny. V tomto příkladu pouze vypíšeme výstupní identifikátory URI úspěšných převodů zahájené v posledním dni.

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, jak je popsáno 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 toString(). Tuto hodnotu lze později předat do počátečníSession jako resumeFrom hodnotu, aby se vytvořila nová vrtule, která pokračuje od místa, kde předchozí hodnota skončila:

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

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

Pokud relace přistupuje k maximální době zapůjčení, ale chcete ji zachovat naživu, budete muset zavolat, abyste zvýšili maximální dobu zapůjčení. Tento příklad ukazuje, jak zadat dotaz na aktuální vlastnosti a potom prodloužit zapůjčení, pokud brzy vyprší jeho platnost.

POZNÁMKA: Sady SDK modulu runtime také nabízejí tuto funkci a v mnoha typických scénářích byste je použili k rozšíř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í metody getSessions. Tato metoda může vrátit relace, které ještě nejsou spuštěné, 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 s daným ID.

client.endSession(sessionId);

Řešení problémů

Protokolování

Povolení protokolování může pomoct odhalit užitečné informace o chybách. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou prostředí AZURE_LOG_LEVEL na info. Případně můžete 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íží týkajících se služby Azure Remote Rendering najdete v tématu stránce Řešení potíží pro vzdálené vykreslování na docs.microsoft.com.

Klientské metody vyvolají výjimky, pokud požadavek nelze provést. V případě převodů i relací však požadavky mohou být úspěšné, ale požadovaná operace nemusí být úspěšná. V tomto případě nebude vyvolána žá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í assetConversion objekt se stavem Selhání a bude obsahovat RemoteRenderingServiceError s podrobnostmi. Jakmile služba převodu dokáže 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, relace skončí ve stavu chyby. Metoda startSessionOperation vrátí renderingSession objekt, ale tento objekt bude mít stav Error a bude mít RemoteRenderingServiceError s podrobnostmi.

Další kroky

Přispívající

Pokud chcete přispívat do této knihovny, přečtěte si průvodce přispívání a přečtěte si další informace o vytváření a testování kódu.

imprese