Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
La bibliothèque client Azure Web PubSub Chat permet aux applications serveur de gérer les rôles de chat, les utilisateurs, les salles, les sujets, l’adhésion à une salle, les conversations et les messages dans un hub de chat Azure Web PubSub. Utilisez-le pour organiser les discussions par thèmes de salle, découvrir les utilisateurs et leurs salles, et gérer les ressources de chat depuis votre application serveur.
Liens clés :
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 hub configuré avec le Chat activé et un stockage persistant.
Installer le package @azure/web-pubsub-chat
Installez la bibliothèque client Azure WebPubSubChatService pour JavaScript avec npm:
npm install @azure/web-pubsub-chat
Configurer TypeScript
Ce paquet inclut des déclarations TypeScript. Pour Node.js applications écrites en TypeScript, installez les Node.js définitions de type :
npm install --save-dev @types/node
Aucun paramètre supplémentaire spécifique au module de compilation n’est requis.
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
Pôle
Un hub est une collection logique de connexions WebSocket. Un hub de chat ajoute des salles intégrées, la gestion des membres, la persistance des messages et des API spécifiques au chat.
Ce SDK s’applique uniquement aux hubs de discussion. Le chat doit être activé sur le hub cible avant que le SDK puisse gérer les rôles, utilisateurs, salles, membres, conversations ou messages.
Rôle et autorisation
Un rôle est une collection nommée de permissions de chat. Les noms des rôles utilisateurs commencent par user., et les noms de rôles de salle commencent par room.. Ne combinez pas les permissions utilisateur et de salle dans un seul rôle.
Les rôles des utilisateurs contrôlent des opérations telles que la création de salles. Les rôles de salle contrôlent ce qu’un membre peut faire dans une salle particulière, comme publier des messages ou lire l’historique des messages.
User
Un utilisateur représente une identité participant au chat, comme un utilisateur final humain ou une application. Les identifiants d’accès client associent les connexions WebSocket à un identifiant utilisateur.
Salle
Une salle regroupe les utilisateurs et constitue l’unité organisationnelle principale des interactions de chat. Chaque pièce possède une conversation par défaut automatiquement créée.
Membre de la salle
Un membre de salle représente un utilisateur ajouté à une salle. L’adhésion contrôle les utilisateurs qui peuvent recevoir et envoyer des messages dans la salle. Dans l’API de service, chaque membre de la salle se voit attribuer un rôle de salle.
Historique des conversations et des messages
Une conversation est un flux de messages ordonné à l’intérieur d’une pièce. Chaque salle a une conversation par défaut, et des conversations nommées supplémentaires peuvent être créées via des thèmes.
Les messages envoyés à une conversation sont transmis en temps réel aux membres connectés de la salle. Le service de chat gère la commande et la persistance, permettant aux membres de charger l’historique des messages après leur reconnexion ou leur rejoint ultérieurement. Le client de service peut lister, mettre à jour et supprimer les messages persistés.
Sujet
Un sujet représente une conversation nommée au sein d’une pièce. Les sujets peuvent être créés, renommés, archivés et supprimés en mode logiciel indépendamment de la conversation par défaut de la salle.
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.
La requête accepte HumanChatUserCreateOrReplace, ce qui nécessite kind: "Human", nickname, et roleName. Les profils retournés conservent les champs de ressources et peuvent représenter des types d’utilisateurs inconnus.
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);
Mettre à jour un message
Lors de la mise à jour d’un message, ChatMessageUpdate.createdBy et content sont optionnels.
Fournissez uniquement les champs à modifier ; les champs omis, conservent leurs valeurs actuelles.
Listez les messages dans une conversation
Utilisez l’itération asynchrone pour lire les messages d’une conversation sur toutes les pages de résultats, de la plus récente à la plus ancienne. Les ID de message sont des curseurs de pagination : l’itérateur suit le curseur du nextLinkservice , qui contient le curseur ID du message suivant. Pour reprendre plus tard, enregistrez celles d’une continuationToken page et passez-la à byPage({ continuationToken }); utilisez le jeton retourné sans modification plutôt que de transmettre un ID de message pur.
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" });
Lister les chambres dans un hub
import { WebPubSubChatServiceClient } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";
const client = new WebPubSubChatServiceClient(
"<endpoint>",
new DefaultAzureCredential(),
"<hubName>",
);
for await (const room of client.listRooms({ maxPageSize: 20 })) {
console.log(`${room.id}: ${room.title}`);
}
Lister les utilisateurs dans un hub
import { WebPubSubChatServiceClient } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";
const client = new WebPubSubChatServiceClient(
"<endpoint>",
new DefaultAzureCredential(),
"<hubName>",
);
for await (const user of client.listUsers({ maxPageSize: 20 })) {
console.log(`${user.id}: ${user.nickname}`);
}
Listez les chambres d’un utilisateur
import { WebPubSubChatServiceClient } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";
const client = new WebPubSubChatServiceClient(
"<endpoint>",
new DefaultAzureCredential(),
"<hubName>",
);
for await (const room of client.listRoomsForUser("alice", { maxPageSize: 20 })) {
console.log(`${room.id}: ${room.title}`);
}
Créer un sujet
Créez un sujet dans une pièce existante. Le service crée la conversation associée.
import { WebPubSubChatServiceClient } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";
const client = new WebPubSubChatServiceClient(
"<endpoint>",
new DefaultAzureCredential(),
"<hubName>",
);
const topic = await client.createOrReplaceTopic(
"general",
"announcements",
{
title: "Announcements",
},
{ ifNoneMatch: "*" },
);
console.log(`Topic conversation: ${topic.conversationId}`);
Obtenir une rubrique
import { WebPubSubChatServiceClient } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";
const client = new WebPubSubChatServiceClient(
"<endpoint>",
new DefaultAzureCredential(),
"<hubName>",
);
const topic = await client.getTopic("general", "announcements");
console.log(`${topic.title}: ${topic.state}, ETag: ${topic.etag}`);
Mettre à jour un sujet
Archiver un sujet existant sans en changer le titre. Remplacez-le <etag> par sa balise d’entité actuelle.
import { WebPubSubChatServiceClient, KnownChatTopicState } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";
const client = new WebPubSubChatServiceClient(
"<endpoint>",
new DefaultAzureCredential(),
"<hubName>",
);
const topic = await client.updateTopic(
"general",
"announcements",
{
state: KnownChatTopicState.Archived,
},
{ ifMatch: "<etag>" },
);
console.log(`Topic state: ${topic.state}`);
Lister les sujets dans une pièce
import { WebPubSubChatServiceClient } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";
const client = new WebPubSubChatServiceClient(
"<endpoint>",
new DefaultAzureCredential(),
"<hubName>",
);
for await (const topic of client.listTopics("general", { maxPageSize: 20 })) {
console.log(`${topic.id}: ${topic.title} (${topic.state})`);
}
Pagination du sujet du CV
Les opérations de liste acceptent les jetons de continuation via byPage({ continuationToken }), et non via les options de la méthode liste. Passez le jeton retourné sur une page sans modification.
import { WebPubSubChatServiceClient } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";
const client = new WebPubSubChatServiceClient(
"<endpoint>",
new DefaultAzureCredential(),
"<hubName>",
);
const pages = client.listTopics("general", { maxPageSize: 20 }).byPage();
const firstPage = await pages.next();
if (!firstPage.done) {
console.log(firstPage.value);
const continuationToken = firstPage.value.continuationToken;
if (continuationToken) {
const resumedPages = client
.listTopics("general", { maxPageSize: 20 })
.byPage({ continuationToken });
const nextPage = await resumedPages.next();
console.log(nextPage.value);
}
}
Supprimer une rubrique
Supprimer doucement un sujet existant. Remplacez-le <etag> par sa balise d’entité actuelle.
import { WebPubSubChatServiceClient } from "@azure/web-pubsub-chat";
import { DefaultAzureCredential } from "@azure/identity";
const client = new WebPubSubChatServiceClient(
"<endpoint>",
new DefaultAzureCredential(),
"<hubName>",
);
await client.deleteTopic("general", "announcements", { ifMatch: "<etag>" });
Troubleshooting
Erreurs de service et requêtes conditionnelles
Les défaillances de service se multiplient RestError par un statusCode. HTTP 404 indique une ressource manquante, y compris un sujet supprimé. HTTP 412 indique qu’une ifMatch précondition ou ifNoneMatch a échoué. Récupérez la ressource actuelle et examinez sa balise entité avant de réessayer une écriture conditionnelle. À utiliser ifNoneMatch: "*" lors de la création d’une ressource uniquement si elle n’existe pas déjà.
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
Étapes suivantes
Explorez les exemples JavaScript et TypeScript ainsi que la référence API.
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.
Azure SDK for JavaScript