Поделиться через

Клиентская библиотека удаленной отрисовки Azure для JavaScript версии 1.0.0-beta.1

  • Статья

Удаленная отрисовка Azure (ARR) — это служба, которая позволяет отображать высококачественное интерактивное трехмерное содержимое в облаке и передавать его в режиме реального времени на устройства, такие как HoloLens 2.

Этот пакет SDK предоставляет функциональные возможности для преобразования ресурсов в формат, ожидаемый средой выполнения, а также для управления временем существования удаленных сеансов отрисовки.

ПРИМЕЧАНИЕ. После запуска сеанса клиентское приложение подключается к нему с помощью одного из "пакетов SDK среды выполнения". Эти пакеты SDK предназначены для обеспечения оптимальной поддержки потребностей интерактивного приложения, выполняющего трехмерную отрисовку. Они доступны в (.net или (C++).

документации по продукту

Начало работы

Поддерживаемые в настоящее время среды

Необходимые условия

Для использования этого пакета потребуется подписка Azure и учет ная запись удаленной отрисовки Azure.

Установка пакета @azure/mixed-reality-remote-rendering

Установите клиентскую библиотеку шаблонов для JavaScript с npm:

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 с помощью существующих групп безопасности Azure AD. Вы также можете предоставить доступ непосредственно пользователям в организации.
    • В противном случае рекомендуется получить маркеры Azure AD из веб-службы, поддерживающей ваше приложение. Этот метод рекомендуется для рабочих приложений, так как он позволяет избежать внедрения учетных данных в клиентское приложение.

Подробные инструкции и сведения см. в здесь.

Во всех следующих примерах клиент создается с помощью 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"
});

Проверка подлинности с помощью статического маркера доступа

Маркер доступа смешанной реальности можно передать как AccessToken ранее полученный из службы службы STS смешанной реальности использовать с клиентской библиотекой смешанной реальности:

// 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 создан, как описано в разделе Аутентификация клиента. В следующем фрагменте кода описывается, как запросить, что box.fbx, найденный в корне контейнера BLOB-объектов в указанном 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
);

Выходные файлы будут размещены рядом с входным ресурсом.

Преобразование более сложного ресурса

Ресурсы могут ссылаться на другие файлы, а контейнеры БОЛЬШИХ двоичных объектов могут содержать файлы, принадлежащие многим другим ресурсам. В этом примере показано, как можно использовать префиксы для организации больших двоичных объектов и как преобразовать ресурс для учета этой организации. Предположим, что контейнер BLOB-объектов в inputStorageUrl содержит множество файлов, включая "Bike/bike.gltf", "Велосипед/bicycle.bin" и "Велосипед/saddleTexture.jpg". (Поэтому префикс "Велосипед" действует очень как папка.) Мы хотим преобразовать 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
  );

ПРИМЕЧАНИЕ. Если префикс указан в входных параметрах, предполагается, что входной параметр файла будет относительно этого префикса. Это же относится к параметру выходного файла в параметрах выходных данных.

Получение выходных данных после завершения преобразования активов

Преобразование ресурса может занять в любом месте от секунд до часов. Этот код использует преобразованиеPoller, возвращаемый beginConversion, для регулярного опроса до завершения или сбоя преобразования. Период опроса по умолчанию составляет 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 среды выполнения также предлагают эту функцию, и во многих типичных сценариях вы будете использовать их для расширения аренды сеанса.

/// 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. Кроме того, ведение журнала можно включить во время выполнения путем вызова setLogLevel в @azure/logger:

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

setLogLevel("info");

Устранение неполадок удаленной отрисовки Azure

Общие рекомендации по устранению неполадок, касающихся удаленной отрисовки Azure, см. странице "Устранение неполадок" для удаленной отрисовки в docs.microsoft.com.

Клиентские методы вызывают исключения, если запрос не может быть выполнен. Однако в случае преобразования и сеансов запросы могут быть успешными, но запрошенная операция может не быть успешной. В этом случае исключение не будет создано, но возвращенные объекты можно проверить, чтобы понять, что произошло.

Если ресурс в преобразовании недопустим, операция преобразования возвращает объект AssetConversion с состоянием Failed и содержит значение RemoteRenderingServiceError с подробными сведениями. После того как служба преобразования сможет обработать файл, файл <assetName>.result.json будет записан в выходной контейнер. Если входной ресурс недопустим, этот файл будет содержать более подробное описание проблемы.

Аналогичным образом, иногда при запросе сеанса сеанс завершается в состоянии ошибки. Метод startSessionOperation возвращает объект RenderingSession, но этот объект будет иметь состояние Error и носить RemoteRenderingServiceError со сведениями.

Дальнейшие действия

Способствует

Если вы хотите внести свой вклад в эту библиотеку, ознакомьтесь с руководством по вкладу, чтобы узнать больше о том, как создавать и тестировать код.

впечатлений