Compartir a través de

Biblioteca cliente de Azure Remote Rendering para .NET, versión 1.1.0

  • 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

Instalar el paquete

Instale la biblioteca cliente de ARR de Azure Mixed Reality para .NET mediante uno de los métodos siguientes.

Desde el Administrador de paquetes de Visual Studio:

Install-Package Azure.MixedReality.RemoteRendering

Desde la CLI de .NET

dotnet add package Azure.MixedReality.RemoteRendering

Agregue una referencia de paquete:

<PackageReference Include="Azure.MixedReality.RemoteRendering" Version="1.0.0" />

Prerrequisitos

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

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 objeto URI. 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:

AzureKeyCredential accountKeyCredential = new AzureKeyCredential(accountKey);

RemoteRenderingClient client = new RemoteRenderingClient(remoteRenderingEndpoint, accountId, accountDomain, accountKeyCredential);

Autenticación con un secreto de cliente de AAD

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

TokenCredential credential = new ClientSecretCredential(tenantId, clientId, clientSecret, new TokenCredentialOptions
{
    AuthorityHost = new Uri($"https://login.microsoftonline.com/{tenantId}")
});

RemoteRenderingClient client = new RemoteRenderingClient(remoteRenderingEndpoint, 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.

Task deviceCodeCallback(DeviceCodeInfo deviceCodeInfo, CancellationToken cancellationToken)
{
    Debug.WriteLine(deviceCodeInfo.Message);
    Console.WriteLine(deviceCodeInfo.Message);
    return Task.FromResult(0);
}

TokenCredential credential = new DeviceCodeCredential(deviceCodeCallback, tenantId, clientId, new TokenCredentialOptions
{
    AuthorityHost = new Uri($"https://login.microsoftonline.com/{tenantId}"),
});

RemoteRenderingClient client = new RemoteRenderingClient(remoteRenderingEndpoint, 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:

TokenCredential credential = new DefaultAzureCredential(includeInteractiveCredentials: true);

RemoteRenderingClient client = new RemoteRenderingClient(remoteRenderingEndpoint, accountId, accountDomain, credential);

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 RemoteRenderingClient(remoteRenderingEndpoint, accountId, accountDomain, 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.

    AssetConversionInputOptions inputOptions = new AssetConversionInputOptions(storageUri, "box.fbx");
    AssetConversionOutputOptions outputOptions = new AssetConversionOutputOptions(storageUri);
    AssetConversionOptions conversionOptions = new AssetConversionOptions(inputOptions, outputOptions);

    // A randomly generated GUID is a good choice for a conversionId.
    string conversionId = Guid.NewGuid().ToString();

    AssetConversionOperation conversionOperation = client.StartConversion(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 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 inputStorageUri 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:

    AssetConversionInputOptions input = new AssetConversionInputOptions(inputStorageUri, "bicycle.gltf")
    {
        BlobPrefix = "Bicycle"
    };
    AssetConversionOutputOptions output = new AssetConversionOutputOptions(outputStorageUri)
    {
        BlobPrefix = "ConvertedBicycle"
    };
    AssetConversionOptions conversionOptions = new AssetConversionOptions(inputOptions, outputOptions);

    string conversionId = Guid.NewGuid().ToString();

    AssetConversionOperation conversionOperation = client.StartConversion(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 finaliza 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 del conversionId de una conversión existente y un cliente.

    AssetConversion conversion = conversionOperation.WaitForCompletionAsync().Result;
    if (conversion.Status == AssetConversionStatus.Succeeded)
    {
        Console.WriteLine($"Conversion succeeded: Output written to {conversion.Output.OutputAssetUri}");
    }
    else if (conversion.Status == AssetConversionStatus.Failed)
    {
        Console.WriteLine($"Conversion failed: {conversion.Error.Code} {conversion.Error.Message}");
    }

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.

    foreach (var conversion in client.GetConversions())
    {
        if ((conversion.Status == AssetConversionStatus.Succeeded) && (conversion.CreatedOn > DateTimeOffset.Now.AddDays(-1)))
        {
            Console.WriteLine($"output asset URI: {conversion.Output.OutputAssetUri}");
        }
    }

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.

    RenderingSessionOptions options = new RenderingSessionOptions(TimeSpan.FromMinutes(30), RenderingServerSize.Standard);

    // A randomly generated GUID is a good choice for a sessionId.
    string sessionId = Guid.NewGuid().ToString();

    StartRenderingSessionOperation startSessionOperation = client.StartSession(sessionId, options);

    RenderingSession newSession = startSessionOperation.WaitForCompletionAsync().Result;
    if (newSession.Status == RenderingSessionStatus.Ready)
    {
        Console.WriteLine($"Session {sessionId} is ready.");
    }
    else if (newSession.Status == RenderingSessionStatus.Error)
    {
        Console.WriteLine($"Session {sessionId} encountered an error: {newSession.Error.Code} {newSession.Error.Message}");
    }

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.

    RenderingSession currentSession = client.GetSession(sessionId);

    if (currentSession.MaxLeaseTime - DateTimeOffset.Now.Subtract(currentSession.CreatedOn.Value) < TimeSpan.FromMinutes(2))
    {
        TimeSpan newLeaseTime = currentSession.MaxLeaseTime.Value.Add(TimeSpan.FromMinutes(30));

        UpdateSessionOptions longerLeaseSettings = new UpdateSessionOptions(newLeaseTime);

        client.UpdateSession(sessionId, longerLeaseSettings);
    }

Enumerar sesiones

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

    foreach (var properties in client.GetSessions())
    {
        if (properties.Status == RenderingSessionStatus.Starting)
        {
            Console.WriteLine($"Session \"{properties.SessionId}\" is starting.");
        }
        else if (properties.Status == RenderingSessionStatus.Ready)
        {
            Console.WriteLine($"Session \"{properties.SessionId}\" is ready at host {properties.Host}");
        }
    }

Detención de una sesión

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

    client.StopSession(sessionId);

Solución de problemas

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

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.