Compartir a través de

Biblioteca cliente de Azure Remote Rendering para JavaScript: versión 1.0.0-beta.1

  • Artículo

Azure Remote Rendering (ARR) es un servicio que permite representar contenido 3D interactivo de alta calidad en la nube y transmitirlo en tiempo real a los dispositivos, como HoloLens 2.

Este SDK ofrece funcionalidad para convertir recursos al formato esperado por el tiempo de ejecución y también para administrar la duración de las sesiones de representación remota.

NOTA: Una vez que se ejecuta una sesión, una aplicación cliente se conectará a ella mediante uno de los "SDK en tiempo de ejecución". Estos SDK están diseñados para admitir mejor las necesidades de una aplicación interactiva que realiza la representación 3d. Están disponibles en (.net o (C++).

Documentación del producto

Introducción

Entornos admitidos actualmente

Prerrequisitos

Necesitará una suscripción de Azure y una cuenta de Azure Remote Rendering para usar este paquete.

Instalar el paquete @azure/mixed-reality-remote-rendering

Instale la biblioteca cliente de plantilla para JavaScript con npm:

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

Compatibilidad con exploradores

Paquete de JavaScript

Para usar esta biblioteca cliente en el explorador, primero debe usar un empaquetador. Para más información sobre cómo hacerlo, consulte nuestra documentación de agrupación.

CORS

Esta biblioteca no se puede usar para realizar llamadas directas al servicio azure Remote Rendering desde un explorador. Consulte este documento para obtener instrucciones.

Autenticar el cliente

La construcción de un cliente de representación remota requiere una cuenta autenticada y un punto de conexión de representación remota. Para una cuenta creada en la región eastus, el dominio de cuenta tendrá el formato "eastus.mixedreality.azure.com". Hay varias formas diferentes de autenticación:

  • Autenticación de clave de cuenta
    • Las claves de cuenta le permiten empezar a trabajar rápidamente con Azure Remote Rendering. Sin embargo, antes de implementar la aplicación en la producción, es recomendable actualizarla para que pueda usar la autenticación de Azure AD.
  • Autenticación de tokens de Azure Active Directory (AD)
    • Si va a compilar una aplicación empresarial y su empresa usa Azure AD como sistema de identidades, puede usar en la aplicación la autenticación de Azure AD basada en el usuario. Después, conceda acceso a las cuentas de Azure Remote Rendering mediante los grupos de seguridad de Azure AD existentes. Igualmente, también puede conceder acceso directamente a los usuarios de la organización.
    • En caso contrario, es recomendable que obtenga los tokens de Azure AD de un servicio web que sea compatible con la aplicación. Se recomienda que use este método en las aplicaciones de producción, ya que le permite evitar la inserción de credenciales para obtener acceso a Azure Spatial Anchors en la aplicación cliente.

Consulte aquí para obtener instrucciones detalladas e información.

En todos los ejemplos siguientes, el cliente se construye con un .remoteRenderingEndpoint Los puntos de conexión disponibles corresponden a las regiones y la elección del punto de conexión determina la región en la que el servicio realiza su trabajo. Un ejemplo es https://remoterendering.eastus2.mixedreality.azure.com.

NOTA: Para convertir recursos, es preferible elegir una región cercana al almacenamiento que contiene los recursos.

NOTA: Para la representación, se recomienda encarecidamente elegir la región más cercana a los dispositivos mediante el servicio. El tiempo necesario para comunicarse con el servidor afecta a la calidad de la experiencia.

Autenticación con autenticación de clave de cuenta

Use el AccountKeyCredential objeto para usar un identificador de cuenta y una clave de cuenta para autenticarse:

const credential = new AzureKeyCredential(accountKey);

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

Autenticación con un secreto de cliente de AAD

Use el objeto para realizar la ClientSecretCredential autenticación de secretos de cliente.

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

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

Autenticación de un usuario mediante la autenticación de código de dispositivo

Use el objeto para realizar la DeviceCodeCredential autenticación de código de dispositivo.

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

Consulte aquí para obtener más información sobre el uso del flujo de autenticación de código de dispositivo.

Autenticación interactiva con DefaultAzureCredential

Use el objeto con includeInteractiveCredentials: true para usar el DefaultAzureCredential flujo de autenticación interactiva predeterminado:

let credential = new DefaultAzureCredential();

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

Autenticación con un token de acceso estático

Puede pasar un token de acceso de Mixed Reality como un AccessToken objeto recuperado previamente del servicio STS de Mixed Reality que se usará con una biblioteca cliente de 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);

Conceptos clave

RemoteRenderingClient

RemoteRenderingClient es la biblioteca cliente que se usa para tener acceso a RemoteRenderingService. Proporciona métodos para crear y administrar conversiones de recursos y sesiones de representación.

Ejemplos

Conversión de un recurso simple

Se supone que remoteRenderingClient se ha construido como se describe en la sección Autenticar el cliente . En el fragmento de código siguiente se describe cómo solicitar que "box.fbx", que se encuentra en la raíz del contenedor de blobs en el URI especificado, se convierte.

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

Los archivos de salida se colocarán junto al recurso de entrada.

Conversión de un recurso más complejo

Los recursos pueden hacer referencia a otros archivos y los contenedores de blobs pueden contener archivos que pertenecen a muchos recursos diferentes. En este ejemplo, se muestra cómo se pueden usar los prefijos para organizar los blobs y cómo convertir un recurso para tener en cuenta esa organización. Suponga que el contenedor de blobs de inputStorageUrl contiene muchos archivos, incluidos "Bicycle/bicycle.gltf", "Bicycle/bicycle.bin" y "Bicycle/saddleTexture.jpg". (Por lo tanto, el prefijo "Bicycle" actúa muy como una carpeta). Queremos convertir el glTF para que tenga acceso a los demás archivos que comparten el prefijo, sin necesidad de que el servicio de conversión tenga acceso a ningún otro archivo. Para mantener las cosas ordenadas, también queremos que los archivos de salida se escriban en un contenedor de almacenamiento diferente y se le dé un prefijo común: "ConvertedBicycle". El código es el siguiente:

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

NOTA: cuando se da un prefijo en las opciones de entrada, se supone que el parámetro de archivo de entrada es relativo a ese prefijo. Lo mismo se aplica al parámetro de archivo de salida en las opciones de salida.

Obtención de la salida cuando finaliza una conversión de recursos

La conversión de un recurso puede tardar entre segundos y horas. Este código usa el conversionPoller devuelto por beginConversion para sondear regularmente hasta que la conversión haya finalizado o fallado. El período de sondeo predeterminado es de 10 segundos.

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

Tenga en cuenta que el estado de assetConversionPollerLike se puede serializar llamando a conversionPoller.toString(). Ese valor se puede pasar más adelante a beginConversion como un resumeFrom valor, para construir un nuevo sondeo que se lleva a cabo desde donde se dejó el anterior:

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

Conversiones de lista

Puede obtener información sobre las conversiones mediante el getConversions método . Este método puede devolver conversiones que todavía tienen que iniciarse, conversiones que se ejecutan y conversiones que han finalizado. En este ejemplo, solo se enumeran los URI de salida de las conversiones correctas iniciadas en el último día.

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

Creación de una sesión

Se supone que remoteRenderingClient se ha construido como se describe en la sección Autenticar el cliente . En el fragmento de código siguiente se describe cómo solicitar que se inicie una nueva sesión de representació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
);

Tenga en cuenta que el estado de renderingSessionPollerLike se puede serializar llamando a toString(). Ese valor se puede pasar posteriormente a beginSession como un resumeFrom valor, para construir un nuevo sondeo que lleva a partir de donde se dejó el anterior:

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

Extender el tiempo de concesión de una sesión

Si una sesión se acerca a su tiempo máximo de concesión, pero quiere mantenerla activa, deberá realizar una llamada para aumentar su tiempo máximo de concesión. En este ejemplo se muestra cómo consultar las propiedades actuales y, a continuación, ampliar la concesión si expirará pronto.

NOTA: Los SDK en tiempo de ejecución también ofrecen esta funcionalidad y, en muchos escenarios típicos, los usaría para ampliar la concesión de sesión.

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

Enumerar sesiones

Puede obtener información sobre las sesiones mediante el getSessions método . Este método puede devolver sesiones que aún no se han iniciado y las sesiones que están listas.

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

detención de una sesión

El código siguiente detendrá una sesión en ejecución con un identificador determinado.

client.endSession(sessionId);

Solución de problemas

Registro

La habilitación del registro puede ayudar a descubrir información útil sobre los errores. Para ver un registro de solicitudes y respuestas HTTP, establezca la variable de entorno AZURE_LOG_LEVEL en info. Como alternativa, el registro se puede habilitar en tiempo de ejecución llamando a setLogLevel en @azure/logger:

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

setLogLevel("info");

Solución de problemas de Azure Remote Rendering

Para obtener consejos generales de solución de problemas relacionados con Azure Remote Rendering, consulte la página Solución de problemas para la representación remota en docs.microsoft.com.

Los métodos de cliente producirán excepciones si no se puede realizar la solicitud. Sin embargo, en el caso de las conversiones y sesiones, las solicitudes pueden realizarse correctamente, pero es posible que la operación solicitada no se realice correctamente. En este caso, no se producirá ninguna excepción, pero se pueden inspeccionar los objetos devueltos para comprender lo que ha ocurrido.

Si el recurso de una conversión no es válido, la operación de conversión devolverá un objeto AssetConversion con un estado Failed y llevará un RemoteRenderingServiceError con detalles. Una vez que el servicio de conversión puede procesar el archivo, se escribirá un <archivo assetName.result.json> en el contenedor de salida. Si el recurso de entrada no es válido, ese archivo contendrá una descripción más detallada del problema.

De forma similar, a veces cuando se solicita una sesión, la sesión termina en un estado de error. El método startSessionOperation devolverá un objeto RenderingSession, pero ese objeto tendrá un estado Error y llevará un RemoteRenderingServiceError con detalles.

Pasos siguientes

Contribuciones

Si desea contribuir a esta biblioteca, lea la guía de contribución para obtener más información sobre cómo compilar y probar el código.

Impresiones