Bibliothèque client Azure Web PubSub Chat pour JavaScript - version 1.0.0-beta.2

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 @azure/enregistreur d’événements.

É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.