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

Клиентская библиотека 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 из веб-службы, поддерживающей ваше приложение. Этот метод рекомендуется использовать для рабочих приложений, так как он позволяет избежать внедрения учетных данных для доступа к Пространственным привязкам 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"
});

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

Вы можете передать маркер доступа Смешанная реальность как 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 содержит множество файлов, включая "Велосипед/велосипед.gltf", "Велосипед/велосипед.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
  );

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

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

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

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

Участие

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

Просмотры