Azure Web PubSub Chat biblioteca cliente para JavaScript - versão 1.0.0-beta.1

A biblioteca cliente Azure Web PubSub Chat permite que aplicações servidor gerenciem funções de chat, usuários, salas, associação de salas, conversas e mensagens em um hub de chat Azure Web PubSub.

Como começar

Ambientes com suporte no momento

Consulte nossa política de suporte para obter mais detalhes.

Pré-requisitos

  • Uma assinatura do Azure.
  • Um recurso existente do Azure Web PubSub.
  • Um nome de hub para o aplicativo de chat.

Instalar o pacote @azure/web-pubsub-chat

Instale a biblioteca cliente Azure WebPubSubChatService para JavaScript comnpm:

npm install @azure/web-pubsub-chat

Criar e autenticar um WebPubSubChatServiceClient

O WebPubSubChatServiceClient suporte autenticação com uma cadeia de conexão, uma credencial Microsoft Entra ou um AzureKeyCredentialarquivo .

Autenticar com uma cadeia de conexão

Você pode encontrar a cadeia de conexão do seu recurso Azure Web PubSub no portal do Azure. Como a cadeia de conexão contém uma chave de acesso, armazene-a de forma segura e não a inclua no código-fonte.

Autenticação com o Microsoft Entra ID

Para autenticar com o Microsoft Entra ID, você precisará do endpoint seu recurso Azure Web PubSub e de uma credencial. Você pode encontrar o endpoint no portal do Azure.

Você pode autenticar com o Microsoft Entra ID usando uma credencial da biblioteca @azure/identity ou um token Microsoft Entra existente.

Para usar o provedor DefaultAzureCredential mostrado abaixo ou outros provedores de credenciais fornecidos com o SDK do Azure, instale o pacote @azure/identity:

npm install @azure/identity

DefaultAzureCredentialsuporta várias identidades Microsoft Entra. Durante o desenvolvimento local, pode usar uma identidade de desenvolvedor logada por meio de uma ferramenta de desenvolvimento suportada. No Azure, ele pode usar uma identidade gerenciada. Também pode autenticar uma identidade de principal de serviço ou carga de trabalho quando configurada para o ambiente.

Qualquer identidade que você use deve receber um papel apropriado no plano de dados do Azure Web PubSub. Funções de gerenciamento de recursos do Azure, como Owner não concedem permissões de plano de dados.

Crie o cliente com uma cadeia de conexão, uma credencial Microsoft Entra como DefaultAzureCredential, ou um AzureKeyCredential.

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

Conceitos principais

WebPubSubChatServiceClient

WebPubSubChatServiceClient é a interface principal para gerenciar recursos de chat em um hub Web PubSub.

Núcleo

Um hub é o limite lógico para um aplicativo de chat. Papéis, usuários, salas, conversas e mensagens gerenciadas por um cliente pertencem ao hub fornecido ao construtor do cliente.

Funções e permissões

Um papel de usuário controla ações no nível do hub, como criar salas. Um papel de sala controla ações dentro de uma sala, como publicar mensagens, ler o histórico de mensagens ou convidar usuários.

Salas, membros e conversas

Uma sala contém membros e tem uma conversa padrão. Adicione um usuário a uma sala atribuindo a ele um papel de sala. As mensagens são publicadas por clientes de chat conectados e podem ser listadas, atualizadas ou excluídas pelo cliente de serviço.

Marcas de entidade

Recursos de chat incluem um etag valor. Passe esse valor pela opção de ifMatch uma operação para realizar uma atualização condicional ou exclusão e evite sobrescrever uma versão de recurso mais recente.

Exemplos

Configure papéis, um usuário e uma sala

Crie papéis de usuário e sala, crie um usuário humano e uma sala, e então adicione o usuário à sala.

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}`);

Use papéis embutidos e permissões conhecidas

Use BuiltInChatRoles ao atribuir um papel definido por um serviço e KnownChatPermission ao criar um papel personalizado. Cadeias de permissão fora dos valores conhecidos também são aceitas para compatibilidade futura.

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,
  ],
});

Gerenciar funções

Crie um papel personalizado, recupere-o, liste os papéis no hub e exclua o papel personalizado quando terminar.

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

Gerencie um quarto

Crie uma sala, recupere seu estado atual e delete-a.

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

Gerencie um usuário

Crie um usuário com uma função embutida, recupere o perfil e delete-o.

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

Liste mensagens em uma conversa

Use iteração assíncrona para ler mensagens de uma conversa em todas as páginas de resultados.

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}`);
}

Gerar um token de acesso ao cliente

Gerar uma URL que um cliente de chat possa usar para se conectar ao serviço Web PubSub como um usuário específico.

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

Registro em log

Habilitar o registro em log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a variável de ambiente AZURE_LOG_LEVEL como info. Como alternativa, o registro em log pode ser habilitado em runtime chamando setLogLevel no @azure/logger:

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

setLogLevel("info");

Para obter instruções mais detalhadas sobre como habilitar logs, você pode consultar os documentos do pacote @azure/logger.

Contributing

Se você quiser contribuir com essa biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar o código.

  • Last updated on