Bibliothèque cliente Azure Communication Identity pour Java - version 1.4.11

Article
10/25/2023

Le package d’identité est utilisé pour gérer les utilisateurs et les jetons pour Azure Communication Services.

| Code source Package (Maven) | Documentation de référence sur les | APIDocumentation produit

Prise en main

Prérequis

Un abonnement Azure. Créez un compte gratuitement.
Java Development Kit (JDK) version 8 ou ultérieure.
Apache Maven.
Ressource Communication Services. Vous pouvez utiliser le portail Azure ou le Azure PowerShell pour le configurer.

Inclure le package

Inclure le fichier de nomenclature

Incluez le kit azure-sdk-bom à votre projet pour qu’il soit dépendant de la version disponibilité générale (GA) de la bibliothèque. Dans l’extrait de code suivant, remplacez l’espace réservé {bom_version_to_target} par le numéro de version. Pour en savoir plus sur la nomenclature, consultez LE FICHIER README DE NOMENCLATURE DU KIT DE DÉVELOPPEMENT LOGICIEL 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>

Incluez ensuite la dépendance directe dans la section des dépendances sans la balise de version.

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

Inclure une dépendance directe

Si vous souhaitez prendre la dépendance sur une version particulière de la bibliothèque qui n’est pas présente dans la nomenclature, ajoutez la dépendance directe à votre projet comme suit.

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

Authentifier le client

Il existe deux formes d’authentification pour utiliser le Kit de développement logiciel (SDK) Identity :

Authentification par jeton Azure Active Directory

Un DefaultAzureCredential objet doit être passé à via la CommunicationIdentityClientBuilder fonction credential(). Endpoint et httpClient doivent également être définis via les fonctions endpoint() et httpClient() respectivement.

AZURE_CLIENT_SECRET, AZURE_CLIENT_ID et AZURE_TENANT_ID les variables d’environnement sont nécessaires pour créer un objet 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();

Authentification AzureKeyCredential

Identity utilise l’authentification HMAC avec la clé d’accès aux ressources. La clé d’accès peut être utilisée pour créer un AzureKeyCredential et fournie à la CommunicationIdentityClientBuilder via la fonction credential(). Endpoint et httpClient doivent également être définis via les fonctions endpoint() et httpClient() respectivement.

// 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();

Authentification par chaîne de connexion

Vous pouvez également fournir l’ensemble des chaîne de connexion à l’aide de la fonction connectionString() au lieu de fournir le point de terminaison et la clé d’accès.

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

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

Concepts clés

CommunicationIdentityClient et CommunicationIdentityAsyncClient fournissent les fonctionnalités permettant de gérer les utilisateurs et les jetons utilisateur.

Exemples

Création d’un utilisateur

Utilisez la createUser fonction pour créer un utilisateur. user.getId() obtient l’ID unique de l’utilisateur qui a été créé.

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

Obtention d’un jeton pour un utilisateur existant

Utilisez la getToken fonction pour obtenir un jeton pour un utilisateur existant. La fonction accepte également une liste de CommunicationTokenScope. Les options d’étendue sont les suivantes :

chat (Conversation)
voip (Voix sur 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());

Il est également possible de créer un jeton d’accès Communication Identity en personnalisant l’heure d’expiration. Le jeton peut être configuré pour expirer en à peine une heure ou 24 heures. Le délai d’expiration par défaut est de 24 heures.

// 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());

Créer un utilisateur et un jeton dans une requête unique

Pour plus de commodité, utilisez createUserAndToken pour créer un utilisateur et émettre un jeton avec un appel de fonction. Cela se traduit par une requête web unique au lieu de créer d’abord un utilisateur, puis d’émettre un jeton.

// 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());

Ici, il est également possible de spécifier l’heure d’expiration du jeton d’accès d’identité de communication. Le jeton peut être configuré pour expirer en à peine une heure ou 24 heures. Le délai d’expiration par défaut est de 24 heures.

// 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());

Révocation de tous les jetons pour un utilisateur existant

Utilisez la revokeTokens fonction pour révoquer tous les jetons émis d’un utilisateur.

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

Suppression d'un utilisateur

Utilisez la deleteUser fonction pour supprimer un utilisateur.

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

Échange d’un jeton d’accès Azure AD d’un utilisateur Teams pour un jeton d’accès d’identité de communication

Utilisez la getTokenForTeamsUser fonction pour échanger un jeton d’accès Azure AD d’un utilisateur Teams contre un nouveau jeton d’accès 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());

Dépannage

Toutes les opérations de service de jeton utilisateur lèvent une exception en cas d’échec.

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

Étapes suivantes

Consultez le répertoire d’exemples pour obtenir des exemples détaillés sur l’utilisation de cette bibliothèque pour gérer les identités et les jetons.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) spécifiant que vous avez le droit de nous accorder les droits d’utiliser votre contribution, et que vous nous les accordez.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Impressions

Partager via