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 dispositivos, como HoloLens 2.

Este SDK ofrece funcionalidad para convertir recursos en el 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 de 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 (de C++).

documentación del producto de

Empezar

Entornos admitidos actualmente

Prerrequisitos

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

Instalación del 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 agrupador. Para obtener más información sobre cómo hacerlo, consulte nuestra documentación de agrupación de .

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.

Autenticación del 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. Pero antes de implementar la aplicación en producción, se recomienda actualizar la aplicación para 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 la autenticación de Azure AD basada en el usuario en la aplicación. Después, conceda acceso a las cuentas de Azure Remote Rendering mediante los grupos de seguridad de Azure AD existentes. También puede conceder acceso directamente a los usuarios de su organización.
    • De lo contrario, se recomienda obtener tokens de Azure AD de un servicio web que admita la aplicación. Se recomienda este método para aplicaciones de producción, ya que permite evitar la inserción de las credenciales en la aplicación cliente.

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

En todos los ejemplos siguientes, el cliente se construye con un remoteRenderingEndpoint. Los puntos de conexión disponibles corresponden a 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 que usan 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 objeto AccountKeyCredential 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 ClientSecretCredential para realizar la 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 DeviceCodeCredential para realizar la 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 DefaultAzureCredential con includeInteractiveCredentials: true para usar el 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 recuperado previamente del servicio STS de Mixed Reality que se va a 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

El RemoteRenderingClient es la biblioteca cliente que se usa para acceder 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 se ha construido un RemoteRenderingClient 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. Supongamos que el contenedor de blobs en inputStorageUrl contiene muchos archivos, como "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 acceda 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 periódicamente 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 valor de resumeFrom, para construir un nuevo sondeo que lleva desde dónde 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 método getConversions. Este método puede devolver conversiones que aún no se han iniciado, 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 se ha construido un RemoteRenderingClient 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 valor de resumeFrom, para construir un nuevo sondeo que lleva desde donde se dejó el anterior:

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

Ampliar 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 el 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 método getSessions. Este método puede devolver sesiones que todavía tienen que iniciarse y sesiones que están listas.

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

Detener una sesión

El código siguiente detendrá una sesión en ejecución con el identificador especificado.

client.endSession(sessionId);

Solución de problemas

Registro

Habilitar el registro puede ayudar a descubrir información útil sobre 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 el @azure/logger:

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

setLogLevel("info");

Solución de problemas de Azure Remote Rendering

Para obtener información general sobre la solución de problemas sobre Azure Remote Rendering, consulte la página Solución de problemas para la representación remota en docs.microsoft.com.

Los métodos cliente producirán excepciones si no se puede realizar la solicitud. Sin embargo, en el caso de conversiones y sesiones, las solicitudes se pueden realizar correctamente, pero es posible que la operación solicitada no se realice correctamente. En este caso, no se producirá ninguna excepción, pero los objetos devueltos se pueden inspeccionar 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á 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.

Del mismo modo, 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

Contribuyendo

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

impresiones