Biblioteca cliente de Azure Communication Identity para Java: versión 1.4.11

Artículo
10/21/2023

El paquete de identidad se usa para administrar usuarios y tokens para Azure Communication Services.

Código | fuentePaquete (Maven) | Documentación | de referencia de API Documentación del producto

Introducción

Requisitos previos

Suscripción a Azure. Cree una cuenta gratuita.
Kit de desarrollo de Java (JDK), versión 8 o posterior.
Apache Maven.
Un recurso de Communication Services. Puede usar Azure Portal o el Azure PowerShell para configurarlo.

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, luego, incluya la dependencia directa en la sección de dependencias sin la etiqueta de versión.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-identity</artifactId>
  </dependency>
</dependencies>

Inclusión de dependencias directas

Si quiere depender de una versión determinada de la biblioteca que no está presente en la lista de materiales, agregue la dependencia directa al proyecto como se indica a continuación.

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-communication-identity</artifactId>
  <version>1.4.11</version>
</dependency>

Autenticar el cliente

Hay dos formas de autenticación para usar el SDK de identidad:

Autenticación de tokens de Azure Active Directory

Se debe pasar un DefaultAzureCredential objeto a CommunicationIdentityClientBuilder a través de la función credential(). El punto de conexión y httpClient también deben establecerse a través de las funciones endpoint() y httpClient() respectivamente.

AZURE_CLIENT_SECRETSe necesitan variables AZURE_CLIENT_ID de entorno y AZURE_TENANT_ID para crear un objeto DefaultAzureCredential.

// You can find your endpoint and access key from your resource in the Azure Portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";

CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
    .endpoint(endpoint)
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

Autenticación azureKeyCredential

La identidad usa la autenticación HMAC con la clave de acceso al recurso. La clave de acceso se puede usar para crear una instancia de AzureKeyCredential y proporcionarla a CommunicationIdentityClientBuilder través de la función credential(). El punto de conexión y httpClient también deben establecerse a través de las funciones endpoint() y httpClient() respectivamente.

// You can find your endpoint and access key from your resource in the Azure Portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
AzureKeyCredential keyCredential = new AzureKeyCredential("<access-key>");

CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
    .endpoint(endpoint)
    .credential(keyCredential)
    .buildClient();

Autenticación de cadena de conexión

Como alternativa, puede proporcionar toda la cadena de conexión mediante la función connectionString() en lugar de proporcionar el punto de conexión y la clave de acceso.

// You can find your connection string from your resource in the Azure Portal
String connectionString = "<connection_string>";

CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
    .connectionString(connectionString)
    .buildClient();

Conceptos clave

CommunicationIdentityClient y CommunicationIdentityAsyncClient proporcionan las funcionalidades para administrar usuarios y tokens de usuario.

Ejemplos

Creación de un nuevo usuario

Use la createUser función para crear un nuevo usuario. user.getId() obtiene el identificador único del usuario que se creó.

CommunicationUserIdentifier user = communicationIdentityClient.createUser();
System.out.println("User id: " + user.getId());

Obtención de un token para un usuario existente

Use la getToken función para obtener un token para un usuario existente. La función también toma una lista de CommunicationTokenScope. Entre las opciones de ámbito se incluyen:

chat (Chat)
voip (Voz sobre IP)

 // Define a list of communication token scopes
List<CommunicationTokenScope> scopes = Arrays.asList(CommunicationTokenScope.CHAT);

AccessToken userToken = communicationIdentityClient.getToken(user, scopes);
System.out.println("User token value: " + userToken.getToken());
System.out.println("Expires at: " + userToken.getExpiresAt());

También es posible crear un token de acceso de Communication Identity personalizando la hora de expiración. El token se puede configurar para que expire en tan solo una hora o hasta 24 horas. El tiempo de expiración predeterminado es de 24 horas.

// Define a list of Communication Identity access token scopes
List<CommunicationTokenScope> scopes = Arrays.asList(CommunicationTokenScope.CHAT);
// Set custom validity period of the Communication Identity access token within [1,24]
// hours range. If not provided, the default value of 24 hours will be used.
Duration tokenExpiresIn = Duration.ofHours(1);
AccessToken userToken = communicationIdentityClient.getToken(user, scopes, tokenExpiresIn);
System.out.println("User token value: " + userToken.getToken());
System.out.println("Expires at: " + userToken.getExpiresAt());

Creación de un nuevo usuario y token en una sola solicitud

Para mayor comodidad, use createUserAndToken para crear un nuevo usuario y emitir un token con una llamada de función. Esto se traduce en una única solicitud web en lugar de crear un usuario primero y, a continuación, emitir un token.

// Define a list of communication token scopes
List<CommunicationTokenScope> scopes = Arrays.asList(CommunicationTokenScope.CHAT);

CommunicationUserIdentifierAndToken result = communicationIdentityClient.createUserAndToken(scopes);
System.out.println("User id: " + result.getUser().getId());
System.out.println("User token value: " + result.getUserToken().getToken());

Aquí también es posible especificar la hora de expiración del token de acceso de Communication Identity. El token se puede configurar para que expire en tan solo una hora o hasta 24 horas. El tiempo de expiración predeterminado es de 24 horas.

// Define a list of communication token scopes
List<CommunicationTokenScope> scopes = Arrays.asList(CommunicationTokenScope.CHAT);
// Set custom validity period of the Communication Identity access token within [1,24]
// hours range. If not provided, the default value of 24 hours will be used.
Duration tokenExpiresIn = Duration.ofHours(1);
CommunicationUserIdentifierAndToken result = communicationIdentityClient.createUserAndToken(scopes, tokenExpiresIn);
System.out.println("User id: " + result.getUser().getId());
System.out.println("User token value: " + result.getUserToken().getToken());

Revocar todos los tokens para un usuario existente

Use la revokeTokens función para revocar todos los tokens emitidos de un usuario.

// revoke tokens issued for the specified user
communicationIdentityClient.revokeTokens(user);

Eliminar un usuario

Use la deleteUser función para eliminar un usuario.

// delete a previously created user
communicationIdentityClient.deleteUser(user);

Intercambio de token de acceso de Azure AD de un usuario de Teams para un token de acceso de identidad de comunicación

Use la getTokenForTeamsUser función para intercambiar un token de acceso de Azure AD de un usuario de Teams para un nuevo token de acceso de Communication Identity.

String clientId = "<Client ID of an Azure AD application>";
String userObjectId = "<Object ID of an Azure AD user (Teams User)>";
GetTokenForTeamsUserOptions options = new GetTokenForTeamsUserOptions(teamsUserAadToken, clientId, userObjectId);
AccessToken accessToken = communicationIdentityClient.getTokenForTeamsUser(options);
System.out.println("User token value: " + accessToken.getToken());
System.out.println("Expires at: " + accessToken.getExpiresAt());

Solución de problemas

Todas las operaciones de servicio de token de usuario producirán una excepción en caso de error.

try {
    CommunicationUserIdentifier user = communicationIdentityClient.createUser();
} catch (RuntimeException ex) {
    System.out.println(ex.getMessage());
}

Pasos siguientes

Eche un vistazo al directorio de ejemplos para obtener ejemplos detallados de cómo usar esta biblioteca para administrar identidades y tokens.

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.

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