Biblioteca cliente común de Azure Communication para .NET: versión 1.2.1

Artículo
04/19/2023

Este paquete contiene código común para las bibliotecas de Azure Communication Service.

Código | fuente Paquete (NuGet) | Documentación del producto

Introducción

Instalar el paquete

Instale la biblioteca cliente común de Azure Communication para .NET con NuGet.

dotnet add package Azure.Communication.Common

Prerrequisitos

Necesita una suscripción de Azure y un recurso de Communication Service para usar este paquete.

Para crear un servicio de comunicación, puede usar Azure Portal, la Azure PowerShell o la biblioteca cliente de administración de .NET.

Autenticar el cliente

Este módulo no contiene un cliente y, en su lugar, bibliotecas que ayudan a otros clientes de Comunicación de Azure a autenticarse.

Conceptos clave

CommunicationTokenCredential

El CommunicationTokenCredential objeto se usa para autenticar a un usuario con Communication Services, como chat o llamadas. Opcionalmente, proporciona un mecanismo de actualización automática para garantizar un estado de autenticación estable continuamente durante las comunicaciones.

En función de su escenario, puede que desee inicializar con CommunicationTokenCredential :

un token estático (adecuado para clientes de corta duración que se usan para, por ejemplo, enviar mensajes de chat de un solo uso) o
una función de devolución de llamada que garantiza un estado de autenticación continua (por ejemplo, para sesiones de llamada largas).

Los tokens proporcionados al CommunicationTokenCredential a través del constructor o a través de la devolución de llamada del actualizador de tokens se pueden obtener mediante la biblioteca azure Communication Identity.

Seguridad para subprocesos

Garantizamos que todos los métodos de instancia de cliente son seguros para subprocesos e independientes entre sí (instrucciones). Esto garantiza que la recomendación de reutilizar instancias de cliente siempre es segura, incluso entre subprocesos.

Conceptos adicionales

Ejemplos

Creación de una credencial con un token estático

En el caso de los clientes de corta duración, no es necesario actualizar el token tras la expiración y CommunicationTokenCredential se pueden crear instancias con un token estático.

string token = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_USER_TOKEN");
using var tokenCredential = new CommunicationTokenCredential(token);

Creación de una credencial con una devolución de llamada

Como alternativa, para los clientes de larga duración, puede crear un CommunicationTokenCredential con una devolución de llamada para renovar tokens si ha expirado. Aquí pasamos dos funciones imaginadas que realizan solicitudes de red para recuperar cadenas de token para el usuario Bob. Si se pasan devoluciones de llamada, tras solicitudes (envío de un mensaje de chat), CommunicationTokenCredential se garantiza que se adquiere un token válido antes de ejecutar la solicitud. Es necesario que el FetchTokenForUserFromMyServer método devuelva un token válido (con una fecha de expiración establecida en el futuro) en todo momento.

Opcionalmente, puede habilitar la actualización proactiva de tokens en la que se adquirirá un token nuevo en cuanto el token anterior se aproxima a la expiración. Con este método, es menos probable que las solicitudes se bloqueen para adquirir un token nuevo:

using var tokenCredential = new CommunicationTokenCredential(
    new CommunicationTokenRefreshOptions(
        refreshProactively: true, // Indicates if the token should be proactively refreshed in the background or only on-demand
        tokenRefresher: cancellationToken => FetchTokenForUserFromMyServer("bob@contoso.com", cancellationToken))
    {
        AsyncTokenRefresher = cancellationToken => FetchTokenForUserFromMyServerAsync("bob@contoso.com", cancellationToken)
    });

Si ya tiene un token, puede optimizar aún más la actualización del token pasando ese token inicial:

string initialToken = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_USER_TOKEN");
using var tokenCredential = new CommunicationTokenCredential(
    new CommunicationTokenRefreshOptions(
       refreshProactively: true, // Indicates if the token should be proactively refreshed in the background or only on-demand
       tokenRefresher: cancellationToken => FetchTokenForUserFromMyServer("bob@contoso.com", cancellationToken))
    {
        AsyncTokenRefresher = cancellationToken => FetchTokenForUserFromMyServerAsync("bob@contoso.com", cancellationToken),
        InitialToken = initialToken
    });

Solución de problemas

Los errores de actualización proactiva se producen en un subproceso en segundo plano y para evitar bloquear la aplicación, las excepciones se controlarán de forma silenciosa. Todos los demás errores se producirán durante la solicitud con otros clientes, como chat, donde puede detectar la excepción mediante RequestFailedException.

Pasos siguientes

Más información sobre los tokens de acceso de usuario de comunicación

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 obtener más información, visite cla.microsoft.com.

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.

Compartir a través de