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 de servidor gerenciem funções de chat, utilizadores, salas, membros de salas, conversas e mensagens num hub de chat Azure Web PubSub.

Como Começar

Ambientes atualmente suportados

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

Pré-requisitos

  • Uma assinatura do Azure.
  • Um recurso já existente no Azure Web PubSub.
  • Um nome de hub para a aplicação 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

Suporta WebPubSubChatServiceClient autenticação com uma cadeia de ligação, uma credencial Microsoft Entra ou um AzureKeyCredential.

Autenticar com uma cadeia de ligação

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

Autenticar com o Microsoft Entra ID

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

Pode autenticar-se com o Microsoft Entra ID usando uma credencial da biblioteca @azure/identity ou um token Microsoft Entra existente.

Para usar o provedor de 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 programador iniciada através de uma ferramenta de desenvolvimento suportada. No Azure, pode usar uma identidade gerida. Também pode autenticar uma identidade de principal de serviço ou carga de trabalho quando configurada para o ambiente.

Qualquer identidade que utilize deve ser atribuída a um papel apropriado no plano de dados Azure Web PubSub. Funções de gestão de recursos no Azure, como Owner não concedem permissões no plano de dados.

Crie o cliente com uma cadeia de ligaçã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-chave

WebPubSubChatServiceClient

WebPubSubChatServiceClient é a interface principal para gerir recursos de chat num hub Web PubSub.

Núcleo

Um hub é o limite lógico para uma aplicação de chat. Papéis, utilizadores, salas, conversas e mensagens geridas por um cliente pertencem todos ao hub fornecido ao construtor do cliente.

Funções e permissões

Um papel de utilizador controla ações ao 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 utilizadores.

Salas, membros e conversas

Uma sala contém membros e tem uma conversa por defeito. Adicione um utilizador a uma sala atribuindo-lhe um papel de sala. As mensagens são publicadas por clientes de chat ligados e podem ser listadas, atualizadas ou eliminadas através do cliente de serviço.

Etiquetas de entidade

Os 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 eliminar e evite sobrescrever uma versão de recurso mais recente.

Examples

Configurar papéis, um utilizador e uma sala

Crie papéis de utilizador e de sala, crie um utilizador humano e uma sala, e depois adicione o utilizador à 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}`);

Usar papéis incorporados e permissões conhecidas

Use BuiltInChatRoles ao atribuir um papel definido pelo serviço e KnownChatPermission ao criar um papel personalizado. Cadeias de permissões fora dos valores conhecidos também são aceites 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 apague 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);
}

Gerir uma sala

Cria uma sala, recupera o seu estado atual e apaga-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);

Gerir um utilizador

Crie um utilizador com um papel incorporado, recupere o perfil e elimine-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);

Listar mensagens numa 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 ligar ao serviço Web PubSub como utilizador 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

Exploração Florestal

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 tempo de execução 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 para esta biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar o código.

  • Last updated on