Azure Web PubSub Chat client library for JavaScript - version 1.0.0-beta.1

La bibliothèque client Azure Web PubSub Chat permet aux applications serveur de gérer les rôles de chat, les utilisateurs, les salles, l’adhésion à la salle, les conversations et les messages dans un hub de chat Azure Web PubSub.

Premiers pas

Environnements actuellement pris en charge

Pour plus d’informations, consultez notre de stratégie de support.

Prerequisites

  • Un abonnement Azure.
  • Une ressource existante sur Azure Web PubSub.
  • Un nom de hub pour l’application de chat.

Installer le package @azure/web-pubsub-chat

Installez la bibliothèque client Azure WebPubSubChatService pour JavaScript avec npm:

npm install @azure/web-pubsub-chat

Créer et authentifier un WebPubSubChatServiceClient

Le WebPubSubChatServiceClient support prend en charge l’authentification avec une chaîne de connexion, un identifiant Microsoft Entra ou un AzureKeyCredentialfichier .

Authentifier avec une chaîne de connexion

Vous pouvez trouver la chaîne de connexion pour votre ressource Azure Web PubSub dans Portail Azure. Parce que la chaîne de connexion contient une clé d’accès, stockez-la de manière sécurisée et ne l’incluez pas dans le code source.

S’authentifier avec Microsoft Entra ID

Pour s’authentifier avec Microsoft Entra ID, vous aurez besoin de la endpoint ressource de votre Azure Web PubSub et d’une accréditation. Vous pouvez trouver le point de terminaison dans Portail Azure.

Vous pouvez vous authentifier avec Microsoft Entra ID en utilisant un identifiant de la bibliothèque @azure/identity ou un jeton Microsoft Entra existant.

Pour utiliser le fournisseur DefaultAzureCredential indiqué ci-dessous ou d’autres fournisseurs d’informations d’identification fournis avec le Kit de développement logiciel (SDK) Azure, installez le package @azure/identity :

npm install @azure/identity

DefaultAzureCredentialprend en charge plusieurs identités Microsoft Entra. Lors du développement local, il peut utiliser une identité de développeur connectée via un outil de développement pris en charge. Dans Azure, il peut utiliser une identité gérée. Il peut également authentifier une identité de principal de service ou de charge de travail lorsqu’il est configuré pour l’environnement.

Quelle que soit l’identité que vous utilisez, il doit se voir attribuer un rôle approprié dans le plan de données Azure Web PubSub. Les rôles de gestion des ressources Azure, tels que Owner ne permettent pas les permissions sur le plan de données.

Créez le client avec une chaîne de connexion, une identifiante Microsoft Entra telle que DefaultAzureCredential, ou un AzureKeyCredentialfichier .

import { WebPubSubChatServiceClient, AzureKeyCredential } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";

const connectionStringClient = new WebPubSubChatServiceClient("<connectionString>", "<hubName>");
const tokenCredentialClient = new WebPubSubChatServiceClient(
  "<endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);
const keyCredentialClient = new WebPubSubChatServiceClient(
  "<endpoint>",
  new AzureKeyCredential("<accessKey>"),
  "<hubName>",
);

Concepts clés

WebPubSubChatServiceClient

WebPubSubChatServiceClient est l’interface principale pour gérer les ressources de chat dans un hub Web PubSub.

Pôle

Un hub est la limite logique pour une application de chat. Les rôles, utilisateurs, salles, conversations et messages gérés par un client appartiennent tous au hub fourni au constructeur client.

Rôles et autorisations

Un rôle utilisateur contrôle les actions au niveau du hub telles que la création de salles. Un rôle de salle contrôle les actions au sein d’une salle, telles que la publication de messages, la lecture de l’historique des messages ou l’invitation des utilisateurs.

Salles, membres et conversations

Une salle contient des membres et possède une conversation par défaut. Ajoutez un utilisateur à une salle en lui assignant un rôle de salle. Les messages sont publiés par des clients de chat connectés et peuvent être listés, mis à jour ou supprimés via le client du service.

Balises d'entités

Les ressources de chat incluent une etag valeur. Faites passer cette valeur dans l’option d’une ifMatch opération pour effectuer une mise à jour conditionnelle ou une suppression et éviter d’écraser une version de ressource plus récente.

Examples

Créez des rôles, un utilisateur et une salle

Créez des rôles utilisateur et de salle, créez un utilisateur humain et une salle, puis ajoutez l’utilisateur à la salle.

import { WebPubSubChatServiceClient, KnownChatPermission } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";

const client = new WebPubSubChatServiceClient(
  "<endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);
const userRoleName = "user.contoso_member";
const roomRoleName = "room.contoso_member";
const userId = "alice";
const roomId = "general";
await client.createOrReplaceRole(userRoleName, {
  permissions: [KnownChatPermission.UserCreateRoom],
});
await client.createOrReplaceRole(roomRoleName, {
  permissions: [KnownChatPermission.RoomPublishMessage, KnownChatPermission.RoomHistory],
});
await client.createOrReplaceUser(userId, {
  kind: "Human",
  nickname: "Alice",
  roleName: userRoleName,
});
const room = await client.createOrReplaceRoom(roomId, { title: "General" });
await client.createOrReplaceRoomMember(roomId, userId, { roleName: roomRoleName });
console.log(`Created room ${room.id} with conversation ${room.defaultConversation}`);

Utiliser des rôles intégrés et des autorisations connues

À utiliser BuiltInChatRoles lors de l’attribution d’un rôle défini par un service et KnownChatPermission lors de la création d’un rôle personnalisé. Les chaînes d’autorisation en dehors des valeurs connues sont également acceptées pour la compatibilité forward.

import {
  WebPubSubChatServiceClient,
  BuiltInChatRoles,
  KnownChatPermission,
} from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";

const client = new WebPubSubChatServiceClient(
  "<endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);
await client.createOrReplaceUser("alice", {
  kind: "Human",
  nickname: "Alice",
  roleName: BuiltInChatRoles.UserNormal,
});
await client.createOrReplaceRole("room.moderator", {
  permissions: [
    KnownChatPermission.RoomHistory,
    KnownChatPermission.RoomRemoveUser,
    KnownChatPermission.RoomPublishMessage,
  ],
});

Gérer les rôles

Créez un rôle personnalisé, récupérez-le, listez les rôles dans le hub, puis supprimez le rôle personnalisé une fois terminé.

import { WebPubSubChatServiceClient, KnownChatPermission } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";

const client = new WebPubSubChatServiceClient(
  "<endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);
const roleName = "user.contoso_member";
try {
  const role = await client.createOrReplaceRole(roleName, {
    permissions: [KnownChatPermission.UserCreateRoom, KnownChatPermission.UserFetchAllRooms],
  });
  console.log(`Created role: ${role.name}`);
  const fetchedRole = await client.getRole(roleName);
  console.log(`Fetched role: ${fetchedRole.name}`);
  for await (const listedRole of client.listRoles()) {
    console.log(`Role: ${listedRole.name}`);
  }
} finally {
  await client.deleteRole(roleName);
}

Gérer une pièce

Créez une pièce, récupérez son état actuel, puis supprimez-la.

import { WebPubSubChatServiceClient } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";

const client = new WebPubSubChatServiceClient(
  "<endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);
const roomId = "general";
const room = await client.createOrReplaceRoom(roomId, { title: "General" });
console.log(`Created room ${room.id} with conversation ${room.defaultConversation}`);
const fetchedRoom = await client.getRoom(roomId);
console.log(`Fetched room: ${fetchedRoom.id}, title: ${fetchedRoom.title}`);
await client.deleteRoom(roomId);

Gérer un utilisateur

Créez un utilisateur avec un rôle intégré, récupérez le profil et supprimez-le.

import { WebPubSubChatServiceClient, BuiltInChatRoles } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";

const client = new WebPubSubChatServiceClient(
  "<endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);
const userId = "alice";
const user = await client.createOrReplaceUser(userId, {
  kind: "Human",
  nickname: "Alice",
  roleName: BuiltInChatRoles.UserNormal,
});
console.log(`Created user: ${user.id}, nickname: ${user.nickname}`);
const fetchedUser = await client.getUser(userId);
console.log(`Fetched user: ${fetchedUser.id}, nickname: ${fetchedUser.nickname}`);
await client.deleteUser(userId);

Listez les messages dans une conversation

Utilisez une itération asynchrone pour lire les messages d’une conversation sur toutes les pages de résultats.

import { WebPubSubChatServiceClient } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";

const client = new WebPubSubChatServiceClient(
  "<endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);
for await (const message of client.listMessages("<conversationId>")) {
  console.log(`${message.createdBy}: ${message.content.text}`);
}

Générer un jeton d’accès client

Générez une URL qu’un client de chat peut utiliser pour se connecter au service Web PubSub en tant qu’utilisateur spécifique.

import { WebPubSubChatServiceClient } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";

const client = new WebPubSubChatServiceClient(
  "<endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);
const accessToken = await client.getClientAccessToken({ userId: "alice" });

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");

Pour obtenir des instructions plus détaillées sur l’activation des journaux, vous pouvez consulter la documentationdu package @azure/enregistreur d’événements.

Contribution

Si vous souhaitez contribuer à cette bibliothèque, lisez le guide de contribution pour en savoir plus sur la génération et le test du code.

  • Dernière mise à jour :