適用于 JavaScript 的 Azure 遠端轉譯 用戶端程式庫 - 1.0.0-Beta.1 版
Azure 遠端轉譯 (ARR) 是一項服務，可讓您在雲端轉譯高品質、互動式3D 內容，並將其即時串流至裝置，例如 HoloLens 2。
此 SDK 提供的功能可將資產轉換成執行時間預期的格式，以及管理遠端轉譯會話的存留期。
注意：會話執行之後，用戶端應用程式會使用其中一個「執行時間 SDK」來連線到它。 這些 SDK 的設計目的是為了支援執行 3d 轉譯的互動式應用程式需求。 它們可在 (.net 或 (C++) 中使用。
開始使用
目前支援的環境
- LTS 版本的 Node.js
- Safari、Chrome、Edge 和 Firefox 的最新版本。
必要條件
您將需要Azure 訂用帳戶和 Azure 遠端轉譯帳戶，才能使用此套件。
安裝 @azure/mixed-reality-remote-rendering 套件
使用 npm 安裝適用于 JavaScript 的範本用戶端程式庫：
npm install @azure/mixed-reality-remote-rendering
瀏覽器支援
JavaScript 套件組合
若要在瀏覽器中使用此用戶端程式庫，您必須先使用套件組合器。 如需如何執行這項操作的詳細資訊，請參閱我們的 統合檔。
CORS
此程式庫無法用來從瀏覽器直接呼叫 Azure 遠端轉譯服務。 如需指引，請參閱 本檔 。
驗證用戶端
建構遠端轉譯用戶端需要已驗證的帳戶和遠端轉譯端點。 針對在 eastus 區域中建立的帳戶，帳戶網域的格式為 「eastus.mixedreality.azure.com」。 有數種不同的驗證形式：
- 帳戶金鑰驗證
- 帳戶金鑰可讓您快速開始使用 Azure 遠端轉譯。 但在您將應用程式部署至生產環境之前，建議您先更新應用程式，以使用 Azure AD 驗證。
- Azure Active Directory (AD) 權杖驗證
- 如果您要建置企業應用程式，且貴公司使用 Azure AD 做為其身分識別系統，則您可在應用程式中使用使用者型的 Azure AD 驗證。 接著，您可以使用現有的 Azure AD 安全性群組，授與 Azure 遠端轉譯帳戶的存取權。 您也可以直接將存取權授與貴組織中的使用者。
- 否則，建議您從支援應用程式的 Web 服務中取得 Azure AD 權杖。 建議您將此方法用於生產環境應用程式，因為其可讓您避免在用戶端應用程式中內嵌存取 Azure 空間錨點的認證。
如需詳細指示和資訊，請參閱 這裡 。
在下列所有範例中，都會使用 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 進行互動式驗證
搭配 DefaultAzureCredential 使用 物件 includeInteractiveCredentials: true 來使用預設的互動式驗證流程：
let credential = new DefaultAzureCredential();
return new RemoteRenderingClient(serviceEndpoint, accountId, accountDomain, credential, {
authenticationEndpointUrl: "https://sts.mixedreality.azure.com"
});
使用靜態存取權杖進行驗證
您可以傳遞Mixed Reality存取權杖，作為 AccessToken 先前從Mixed Reality STS 服務擷取，以搭配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，以及如何轉換資產以考慮該組織。
假設 的 Blob 容器 inputStorageUrl 包含許多檔案，包括 「Bicycle/bicycle.gltf」、「Bicycle/bicycle.bin」 和 「Bicycle/saddleTexture.jpg」。
(因此，前置詞 「Bicycle」 非常像 folder.) 我們想要轉換 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 () 來序列化。
該值稍後可以傳遞至 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 () 來序列化。
該值稍後可以傳遞至 beginSession 做為 resumeFrom 值，以建構新的輪詢器，該輪詢器會從先前的輪詢器離開的位置開始執行：
const serializedPollerString = sessionPoller.toString();
// ...
const resumedPoller = client.beginSession({ resumeFrom: serializedPollerString });
延長會話的租用時間
如果會話接近其租用時間上限，但您想要讓它保持運作，您必須進行呼叫，以增加其最大租用時間。 此範例示範如何查詢目前的屬性，然後在租用即將到期時延長租用。
注意：執行時間 SDK 也提供這項功能，而且在許多情況下，您會使用這些 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}`);
}
停止工作階段
下列程式碼將會停止具有指定識別碼的執行中會話。
client.endSession(sessionId);
疑難排解
記錄
啟用記錄有助於找出失敗的相關實用資訊。 若要查看 HTTP 的要求和回應記錄，請將 AZURE_LOG_LEVEL 環境變數設定為 info。 或者，您可以在 @azure/logger 中呼叫 setLogLevel，以在執行階段啟用記錄：
import { setLogLevel } from "@azure/logger";
setLogLevel("info");
Azure 遠端轉譯疑難排解
如需有關 Azure 遠端轉譯的一般疑難排解建議，請參閱 docs.microsoft.com 遠端轉譯的疑難排解頁面。
如果無法提出要求，則用戶端方法會擲回例外狀況。 不過，在轉換和會話的情況下，要求可能會成功，但要求的作業可能不會成功。 在此情況下，不會擲回任何例外狀況，但可以檢查傳回的物件，以瞭解發生什麼事。
如果轉換中的資產無效，轉換作業會傳回具有失敗狀態的 AssetConversion 物件，並攜帶具有詳細資料的 RemoteRenderingServiceError。 一旦轉換服務能夠處理檔案， < assetName.result.json > 檔案就會寫入輸出容器。 如果輸入資產無效，則該檔案將包含問題的詳細描述。
同樣地，有時候當要求會話時，會話最終會處於錯誤狀態。 startSessionOperation 方法會傳回 RenderingSession 物件，但該物件會有 Error 狀態，並具有具有詳細資料的 RemoteRenderingServiceError。
下一步
- 閱讀 產品檔
- 瞭解執行時間 SDK：
參與
如果您希望向此程式庫投稿，請參閱投稿指南，深入瞭解如何組建與測試程式碼。
相關專案
