Biblioteca cliente de Azure Remote Rendering para Java: versión 1.1.23

Artículo
10/21/2023

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 en 3d. Están disponibles en .NET y C++.

Código | fuenteDocumentación | de referencia de API Documentación del producto

Introducción

Requisitos previos

Kit de desarrollo de Java (JDK), versión 8 o posterior.
Suscripción de Azure
Azure Remote Rendering cuenta para usar este paquete.

Inclusión del paquete

Inclusión del archivo BOM

Incluya azure-sdk-bom en el proyecto para depender de la versión de disponibilidad general (GA) de la biblioteca. En el fragmento de código siguiente, reemplace el marcador de posición {bom_version_to_target} por el número de versión. Para más información sobre la lista de materiales, consulte EL ARCHIVO LÉAME BOM del SDK de AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

y, a continuación, incluya la dependencia directa en la sección dependencias sin la etiqueta de versión, como se muestra a continuación.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-mixedreality-remoterendering</artifactId>
  </dependency>
</dependencies>

Inclusión de dependencias directas

Nota: Esta versión tiene como destino la versión v2021-01-01 de la API de servicio de Azure Remote Rendering.

Agregue la siguiente dependencia de Maven:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-mixedreality-remoterendering</artifactId>
    <version>1.1.23</version>
</dependency>

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. Una cuenta consta de su accountId y un dominio de cuenta. Para una cuenta creada en la región eastus, el dominio de cuenta tendrá el formato "eastus.mixedreality.azure.com". Hay varias formas 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. A continuación, 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 e información detalladas.

En todos los ejemplos siguientes, el cliente se construye con un RemoteRenderingClientBuilder objeto . Los parámetros siempre son los mismos, excepto para el objeto de credencial, que se explica en cada ejemplo. El remoteRenderingEndpoint parámetro es una dirección URL que 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 AzureKeyCredential objeto para usar un identificador de cuenta y una clave de cuenta para autenticarse:

AzureKeyCredential credential = new AzureKeyCredential(environment.getAccountKey());

RemoteRenderingClient client = new RemoteRenderingClientBuilder()
    .accountId(environment.getAccountId())
    .accountDomain(environment.getAccountDomain())
    .endpoint(environment.getServiceEndpoint())
    .credential(credential)
    .buildClient();

Autenticación con un secreto de cliente de AAD

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

ClientSecretCredential credential = new ClientSecretCredentialBuilder()
    .tenantId(environment.getTenantId())
    .clientId(environment.getClientId())
    .clientSecret(environment.getClientSecret())
    .authorityHost("https://login.microsoftonline.com/" + environment.getTenantId())
    .build();

RemoteRenderingClient client = new RemoteRenderingClientBuilder()
    .accountId(environment.getAccountId())
    .accountDomain(environment.getAccountDomain())
    .endpoint(environment.getServiceEndpoint())
    .credential(credential)
    .buildClient();

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.

DeviceCodeCredential credential = new DeviceCodeCredentialBuilder()
    .challengeConsumer((DeviceCodeInfo deviceCodeInfo) -> {
        logger.info(deviceCodeInfo.getMessage());
    })
    .clientId(environment.getClientId())
    .tenantId(environment.getTenantId())
    .authorityHost("https://login.microsoftonline.com/" + environment.getTenantId())
    .build();

RemoteRenderingClient client = new RemoteRenderingClientBuilder()
    .accountId(environment.getAccountId())
    .accountDomain(environment.getAccountDomain())
    .endpoint(environment.getServiceEndpoint())
    .credential(credential)
    .buildClient();

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 DefaultAzureCredential objeto :

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();

RemoteRenderingClient client = new RemoteRenderingClientBuilder()
    .accountId(environment.getAccountId())
    .accountDomain(environment.getAccountDomain())
    .endpoint(environment.getServiceEndpoint())
    .credential(credential)
    .buildClient();

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.
AccessToken accessToken = getMixedRealityAccessTokenFromWebService();

RemoteRenderingClient client = new RemoteRenderingClientBuilder()
    .accountId(environment.getAccountId())
    .accountDomain(environment.getAccountDomain())
    .endpoint(environment.getServiceEndpoint())
    .accessToken(accessToken)
    .buildClient();

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
Conversión de un recurso más complejo
Obtención de la salida cuando haya finalizado una conversión de recursos
Enumeración de conversiones
Creación de una sesión
Extender el tiempo de concesión de una sesión
Enumerar sesiones
Detención de una sesión

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 la dirección URL especificada, se convierte.

AssetConversionOptions conversionOptions = new AssetConversionOptions()
    .setInputStorageContainerUrl(getStorageURL())
    .setInputRelativeAssetPath("box.fbx")
    .setOutputStorageContainerUrl(getStorageURL());

// A randomly generated UUID is a good choice for a conversionId.
String conversionId = UUID.randomUUID().toString();

SyncPoller<AssetConversion, AssetConversion> conversionOperation = client.beginConversion(conversionId, conversionOptions);

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 prefijos para organizar los blobs y cómo convertir un recurso para tener en cuenta esa organización. Supongamos 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 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:

AssetConversionOptions conversionOptions = new AssetConversionOptions()
    .setInputStorageContainerUrl(inputStorageURL)
    .setInputRelativeAssetPath("bicycle.gltf")
    .setInputBlobPrefix("Bicycle")
    .setOutputStorageContainerUrl(outputStorageURL)
    .setOutputBlobPrefix("ConvertedBicycle");

String conversionId = UUID.randomUUID().toString();

SyncPoller<AssetConversion, AssetConversion> conversionOperation = client.beginConversion(conversionId, conversionOptions);

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 haya finalizado una conversión de recursos

La conversión de un recurso puede tardar entre segundos y horas. Este código usa una conversionOperation existente y sondea periódicamente hasta que la conversión haya finalizado o fallado. El período de sondeo predeterminado es de 10 segundos. Tenga en cuenta que se puede construir una conversionOperation a partir de conversionId de una conversión existente y un cliente.

AssetConversion conversion = conversionOperation.getFinalResult();
if (conversion.getStatus() == AssetConversionStatus.SUCCEEDED) {
    logger.info("Conversion succeeded: Output written to {}", conversion.getOutputAssetUrl());
} else if (conversion.getStatus() == AssetConversionStatus.FAILED) {
    logger.error("Conversion failed: {} {}", conversion.getError().getCode(), conversion.getError().getMessage());
} else {
    logger.error("Unexpected conversion status: {}", conversion.getStatus());
}

Enumeración de conversiones

Puede obtener información sobre las conversiones mediante el listConversions método . 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 las direcciones URL de salida de las conversiones correctas iniciadas en el último día.

for (AssetConversion conversion : client.listConversions()) {
    if ((conversion.getStatus() == AssetConversionStatus.SUCCEEDED)
        && (conversion.getCreationTime().isAfter(OffsetDateTime.now().minusDays(1)))) {
        logger.info("Output Asset URL: {}", conversion.getOutputAssetUrl());
    }
}

Creación de una sesión de representació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.

BeginSessionOptions options = new BeginSessionOptions()
    .setMaxLeaseTime(Duration.ofMinutes(30))
    .setSize(RenderingSessionSize.STANDARD);

// A randomly generated GUID is a good choice for a sessionId.
String sessionId = UUID.randomUUID().toString();

SyncPoller<RenderingSession, RenderingSession> startSessionOperation = client.beginSession(sessionId, options);

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, extender 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.

RenderingSession currentSession = client.getSession(sessionId);

Duration sessionTimeAlive = Duration.between(OffsetDateTime.now(), currentSession.getCreationTime()).abs();
if (currentSession.getMaxLeaseTime().minus(sessionTimeAlive).toMinutes() < 2) {
    Duration newLeaseTime = currentSession.getMaxLeaseTime().plus(Duration.ofMinutes(30));
    UpdateSessionOptions longerLeaseOptions = new UpdateSessionOptions().maxLeaseTime(newLeaseTime);
    client.updateSession(sessionId, longerLeaseOptions);
}

Enumerar sesiones de representación

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

for (RenderingSession session : client.listSessions()) {
    if (session.getStatus() == RenderingSessionStatus.STARTING) {
        logger.info("Session {} is starting.");
    } else if (session.getStatus() == RenderingSessionStatus.READY) {
        logger.info("Session {} is ready at host {}", session.getId(), session.getHostname());
    } else if (session.getStatus() == RenderingSessionStatus.ERROR) {
        logger.error("Session {} encountered an error: {} {}", session.getId(), session.getError().getCode(), session.getError().getMessage());
    } else {
        logger.error("Session {} has unexpected status {}", session.getId(), session.getStatus());
    }
}

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

Para obtener consejos generales de solución de problemas sobre Azure Remote Rendering, consulte la página Solución de problemas de 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

Lea la documentación del producto.
Obtenga información sobre los SDK en tiempo de ejecución:
- .NET: /dotnet/api/microsoft.azure.remoterendering
- C++: /cpp/api/remote-rendering/

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Impresiones

Compartir a través de