Azure Communication Identity client library for JavaScript - version 2.0.0

La bibliothèque d’identité est utilisée pour gérer les utilisateurs et les jetons pour Azure Communication Services.

Premiers pas

Prerequisites

  • Un abonnement Azure.
  • Ressource Communication Services existante. Si vous devez créer la ressource, vous pouvez utiliser le portail Azure , le Azure PowerShellou leAzure CLI .

Installation en cours

npm install @azure/communication-identity

Support des navigateurs

Offre groupée JavaScript

Pour utiliser cette bibliothèque cliente dans le navigateur, vous devez d’abord utiliser un bundler. Pour plus d’informations sur la procédure à suivre, reportez-vous à notre documentation de regroupement .

Concepts clés

Clients

Il CommunicationIdentityClient fournit des méthodes pour gérer les utilisateurs et leurs jetons.

Examples

Authentification

Vous pouvez obtenir une clé et/ou une chaîne de connexion depuis votre ressource Communication Services dans Portail Azure. Une fois que vous avez une clé, vous pouvez l’authentifier CommunicationIdentityClient avec l’une des méthodes suivantes :

Créer KeyCredential avec AzureKeyCredential avant d’initialiser le client

import { AzureKeyCredential } from "@azure/core-auth";
import { CommunicationIdentityClient } from "@azure/communication-identity";

const key = "<some-key>";
const endpoint = "https://contoso.eastus.communications.azure.net";

const credential = new AzureKeyCredential(key);
const client = new CommunicationIdentityClient(endpoint, credential);

Utilisation d’une chaîne de connexion

import { CommunicationIdentityClient } from "@azure/communication-identity";

// Example connection string
const connectionString =
  "endpoint=https://contoso.eastus.communications.azure.net/;accesskey=secret";

const client = new CommunicationIdentityClient(connectionString);

Utilisation d’un TokenCredential

import { DefaultAzureCredential } from "@azure/identity";
import { CommunicationIdentityClient } from "@azure/communication-identity";

const endpoint = "https://contoso.eastus.communications.azure.net";

const credential = new DefaultAzureCredential();
const client = new CommunicationIdentityClient(endpoint, credential);

Si vous utilisez une clé pour initialiser le client, vous devez également fournir le point de terminaison approprié. Vous pouvez obtenir ce point de terminaison à partir de votre ressource Communication Services dans portail Azure.

Usage

Création d’un nouvel utilisateur

Utilisez la createUser méthode pour créer un nouvel utilisateur.

import { DefaultAzureCredential } from "@azure/identity";
import { CommunicationIdentityClient } from "@azure/communication-identity";

const endpoint = "https://contoso.eastus.communications.azure.net";

const credential = new DefaultAzureCredential();
const client = new CommunicationIdentityClient(endpoint, credential);

const user = await client.createUser();

Création et rafraîchissement d’un jeton utilisateur

Utilisez cette getToken méthode pour émettre ou actualiser un jeton pour un utilisateur existant. La méthode prend également en compte une liste de portées de jetons de communication. Les options d’étendue sont les suivantes :

  • chat (Utilisez ceci pour un accès complet aux API de chat)
  • voip (Utilisez ceci pour un accès complet aux API d’appel)
  • chat.join (Accès aux API de discussion mais sans l’autorisation de créer, supprimer ou mettre à jour des fils de discussion)
  • chat.join.limited (Une version plus limitée de chat.join qui ne permet pas d’ajouter ou de supprimer des participants)
  • voip.join (Accès aux API d’appel mais sans autorisation de lancer de nouveaux appels)
import { DefaultAzureCredential } from "@azure/identity";
import { CommunicationIdentityClient } from "@azure/communication-identity";

const endpoint = "https://contoso.eastus.communications.azure.net";

const credential = new DefaultAzureCredential();
const client = new CommunicationIdentityClient(endpoint, credential);

const user = await client.createUser();

const { token } = await client.getToken(user, ["chat"]);

Pour rafraîchir le jeton utilisateur, émettez un autre jeton avec le même utilisateur.

import { DefaultAzureCredential } from "@azure/identity";
import { CommunicationIdentityClient } from "@azure/communication-identity";

const endpoint = "https://contoso.eastus.communications.azure.net";

const credential = new DefaultAzureCredential();
const client = new CommunicationIdentityClient(endpoint, credential);

const user = await client.createUser();

let { token } = await client.getToken(user, ["chat"]);

// Refresh the token again
({ token } = await client.getToken(user, ["chat"]));

Création d’un jeton utilisateur avec une expiration personnalisée

Il est également possible de créer un jeton d’accès Communication Identity en personnalisant le délai d’expiration. La durée de validité du jeton doit être dans une fourchette de [60,1440] minutes. Si cela n’est pas fourni, la valeur par défaut de 1440 minutes (24 heures) sera utilisée.

import { DefaultAzureCredential } from "@azure/identity";
import { CommunicationIdentityClient } from "@azure/communication-identity";

const endpoint = "https://contoso.eastus.communications.azure.net";

const credential = new DefaultAzureCredential();
const client = new CommunicationIdentityClient(endpoint, credential);

const user = await client.createUser();

const tokenOptions = { tokenExpiresInMinutes: 60 };
const { token } = await client.getToken(user, ["chat"], tokenOptions);

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

Pour plus de commodité, utilisez createUserAndToken pour créer un nouvel utilisateur et émettre un jeton avec un appel de fonction. Cela se traduit par une seule requête web plutôt que de créer d’abord un utilisateur puis d’émettre un jeton.

import { DefaultAzureCredential } from "@azure/identity";
import { CommunicationIdentityClient } from "@azure/communication-identity";

const endpoint = "https://contoso.eastus.communications.azure.net";

const credential = new DefaultAzureCredential();
const client = new CommunicationIdentityClient(endpoint, credential);

const { user, token } = await client.createUserAndToken(["chat"]);

Créer un utilisateur et un jeton avec une expiration personnalisée dans une seule requête

Il est également possible de créer un jeton d’accès Communication Identity en personnalisant le délai d’expiration. La durée de validité du jeton doit être dans une fourchette de [60,1440] minutes. Si cela n’est pas fourni, la valeur par défaut de 1440 minutes (24 heures) sera utilisée.

import { DefaultAzureCredential } from "@azure/identity";
import { CommunicationIdentityClient } from "@azure/communication-identity";

const endpoint = "https://contoso.eastus.communications.azure.net";

const credential = new DefaultAzureCredential();
const client = new CommunicationIdentityClient(endpoint, credential);

const userAndTokenOptions = { tokenExpiresInMinutes: 60 };
const { user, token } = await client.createUserAndToken(["chat"], userAndTokenOptions);

Révocation des jetons pour un utilisateur

Utilisez la revokeTokens méthode pour révoquer tous les jetons émis pour un utilisateur.

import { DefaultAzureCredential } from "@azure/identity";
import { CommunicationIdentityClient } from "@azure/communication-identity";

const endpoint = "https://contoso.eastus.communications.azure.net";

const credential = new DefaultAzureCredential();
const client = new CommunicationIdentityClient(endpoint, credential);

// Create user
const user = await client.createUser();

// Later when you want to revoke the user's tokens
await client.revokeTokens(user);

Suppression d’un utilisateur

Utilisez la deleteUser méthode pour supprimer un utilisateur.

import { DefaultAzureCredential } from "@azure/identity";
import { CommunicationIdentityClient } from "@azure/communication-identity";

const endpoint = "https://contoso.eastus.communications.azure.net";

const credential = new DefaultAzureCredential();
const client = new CommunicationIdentityClient(endpoint, credential);

// Create user
const user = await client.createUser();

// Later when you want to delete the user
await client.deleteUser(user);

Échanger le token d’accès Azure AD d’un utilisateur Teams contre un token d’accès Communication

Utilisez getTokenForTeamsUser la méthode pour échanger un jeton d’accès Azure AD d’un utilisateur Teams contre un nouveau CommunicationAccessToken avec un délai d’expiration correspondant.

import { DefaultAzureCredential } from "@azure/identity";
import { CommunicationIdentityClient } from "@azure/communication-identity";

const endpoint = "https://contoso.eastus.communications.azure.net";

const credential = new DefaultAzureCredential();
const client = new CommunicationIdentityClient(endpoint, credential);

const { token, expiresOn } = await client.getTokenForTeamsUser({
  teamsUserAadToken: "<aad-access-token-of-a-teams-user>",
  clientId: "<cliend-id-of-an-aad-application>",
  userObjectId: "<aad-object-id-of-a-teams-user>",
});

Troubleshooting

Logging

L’activation de la journalisation peut vous aider à découvrir des informations utiles sur les échecs. Pour afficher un journal des requêtes et réponses HTTP, définissez la variable d’environnement AZURE_LOG_LEVEL sur info. Vous pouvez également activer la journalisation au moment de l’exécution en appelant setLogLevel dans la @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Étapes suivantes

Consultez les exemples répertoire pour obtenir des exemples détaillés sur l’utilisation de cette bibliothèque.

Contributing

Si vous souhaitez contribuer à cette bibliothèque, veuillez lire le guide contribution pour en savoir plus sur la construction et le test du code.

  • Dernière mise à jour :