Azure Web PubSub Chat client library untuk JavaScript - versi 1.0.0-beta.1

Perpustakaan klien Azure Web PubSub Chat memungkinkan aplikasi server mengelola peran chat, pengguna, ruangan, keanggotaan ruangan, percakapan, dan pesan di Azure Web PubSub Chat hub.

Memulai Langkah Pertama

Lingkungan yang didukung saat ini

Lihat kebijakan dukungan kami untuk detail selengkapnya.

Prasyarat

  • Sebuah langganan Azure.
  • Sumber daya Azure Web PubSub yang sudah ada.
  • Nama hub untuk aplikasi chat.

Pasang paket @azure/web-pubsub-chat

Instal pustaka klien Azure WebPubSubChatService untuk JavaScript dengan npm:

npm install @azure/web-pubsub-chat

Membuat dan mengautentikasi WebPubSubChatServiceClient

Mendukung WebPubSubChatServiceClient autentikasi dengan string koneksi, kredensial Microsoft Entra, atau .AzureKeyCredential

Autentikasi dengan string koneksi

Anda dapat menemukan string koneksi untuk sumber daya Azure Web PubSub Anda di portal Azure. Karena string koneksi berisi kunci akses, simpan dengan aman dan jangan sertakan dalam kode sumber.

Mengautentikasi dengan Microsoft Entra ID

Untuk mengautentikasi dengan Microsoft Entra ID, Anda memerlukan endpoint sumber daya Azure Web PubSub Anda dan kredensial. Anda dapat menemukan endpoint di portal Azure.

Anda dapat mengautentikasi dengan Microsoft Entra ID menggunakan kredensial dari pustaka @azure/identity atau token Microsoft Entra yang ada.

Untuk menggunakan penyedia DefaultAzureCredential yang ditunjukkan di bawah ini, atau penyedia kredensial lain yang disediakan dengan Azure SDK, instal paket @azure/identity:

npm install @azure/identity

DefaultAzureCredentialmendukung beberapa identitas Microsoft Entra. Selama pengembangan lokal, perangkat dapat menggunakan identitas pengembang yang masuk melalui alat pengembangan yang didukung. Di Azure, dapat menggunakan identitas terkelola. Perangkat ini juga dapat mengautentikasi service principal atau identitas beban kerja saat dikonfigurasi untuk lingkungan.

Identitas mana pun yang Anda gunakan harus diberikan peran data-plane Azure Web PubSub yang sesuai. Peran manajemen sumber daya Azure seperti Owner tidak memberikan izin data-plane.

Buat klien dengan string koneksi, kredensial Microsoft Entra seperti DefaultAzureCredential, atau .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>",
);

Konsep Utama

WebPubSubChatServiceClient

WebPubSubChatServiceClient adalah antarmuka utama untuk mengelola sumber daya obrolan di hub Web PubSub.

Pusat

Hub adalah batas logis untuk aplikasi chat. Peran, pengguna, ruangan, percakapan, dan pesan yang dikelola oleh klien semuanya termasuk dalam hub yang disediakan kepada konstruktor klien.

Peran dan izin

Peran pengguna mengontrol tindakan tingkat hub seperti membuat ruangan. Peran ruang mengontrol tindakan di dalam ruangan, seperti mempublikasikan pesan, membaca riwayat pesan, atau mengundang pengguna.

Ruangan, anggota, dan percakapan

Sebuah ruangan berisi anggota dan memiliki percakapan default. Tambahkan pengguna ke ruangan dengan memberikan peran ruang kepada pengguna. Pesan dipublikasikan oleh klien chat yang terhubung dan dapat didaftarkan, diperbarui, atau dihapus melalui klien layanan.

Tag entitas

Sumber daya obrolan mencakup sebuah etag nilai. Teruskan nilai tersebut melalui opsi operasi ifMatch untuk melakukan pembaruan bersyarat atau menghapus dan mencegah menimpa versi sumber daya yang lebih baru.

Examples

Atur peran, pengguna, dan ruangan

Buat peran pengguna dan ruang, buat pengguna manusia dan ruang, lalu tambahkan pengguna ke ruang.

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

Gunakan peran bawaan dan izin yang sudah diketahui

Gunakan BuiltInChatRoles saat menetapkan peran yang didefinisikan layanan dan KnownChatPermission saat membuat peran kustom. String izin di luar nilai yang diketahui juga diterima untuk kompatibilitas ke depan.

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

Mengelola peran

Buat peran kustom, ambil, daftar peran di hub, dan hapus peran kustom setelah selesai.

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

Kelola sebuah ruangan

Buat ruangan, ambil status saat ini, dan hapus.

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

Kelola pengguna

Buat pengguna dengan peran bawaan, ambil profilnya, dan hapus.

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

Daftarkan pesan dalam percakapan

Gunakan iterasi asinkron untuk membaca pesan dari percakapan di semua halaman hasil.

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

Menghasilkan token akses klien

Buat URL yang dapat digunakan klien chat untuk terhubung ke layanan Web PubSub sebagai pengguna tertentu.

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

Penebangan kayu

Mengaktifkan pengelogan dapat membantu menemukan informasi yang berguna tentang kegagalan. Untuk melihat log permintaan dan respons HTTP, atur variabel lingkungan AZURE_LOG_LEVEL ke info. Atau, pengelogan dapat diaktifkan saat runtime dengan memanggil setLogLevel di @azure/logger:

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

setLogLevel("info");

Untuk instruksi lebih rinci tentang cara mengaktifkan log, Anda dapat melihat dokumen paket @azure/logger.

Contributing

Jika Anda ingin berkontribusi pada pustaka ini, baca panduan berkontribusi untuk mempelajari selengkapnya tentang cara membuat dan menguji kode.

  • Last updated on