Azure Web PubSub Chat client library for JavaScript - version 1.0.0-beta.1

Azure Web PubSub Chat istemci kütüphanesi, sunucu uygulamalarının Azure Web PubSub Chat merkezinde sohbet rollerini, kullanıcıları, odaları, oda üyeliğini, konuşmalarını ve mesajlarını yönetmesini sağlar.

Başlangıç Yapmak

Şu anda desteklenen ortamlar

• Node.js LTS sürümleri

Daha fazla bilgi için bkz. destek ilkesi.

Prerequisites

• Bir Azure aboneliği.
• Mevcut bir Azure Web PubSub kaynağı.
• Sohbet uygulaması için bir hub adı.

@azure/web-pubsub-chat paketini yükleme

JavaScript için Azure WebPubSubChatService client library install with npm:

npm install @azure/web-pubsub-chat

Bir WebPubSubChatServiceClient oluşturun ve kimlik doğrulaması yapın.

Doğrulama WebPubSubChatServiceClient için bir bağlantı dizesi, Microsoft Entra credential veya AzureKeyCredential.

Bir bağlantı dizesi ile kimlik doğrulama yapın

Azure Web PubSub kaynağınız için bağlantı dizesi'i Azure portal'da bulabilirsiniz. Çünkü bağlantı dizesi erişim anahtarı içerdiğinden, onu güvenli bir şekilde saklayın ve kaynak koduna dahil etmeyin.

Microsoft Entra Kimliği ile kimlik doğrulama

Microsoft Entra ID ile kimlik doğrulaması yapmak için Azure Web PubSub kaynağınız ve bir kimlik belgeniz gerekecekendpoint. Uç noktayı Azure portal'da bulabilirsiniz.

@azure/identity kütüphanesinden veya mevcut bir Microsoft Entra token'ından bir kimlik bilgisi kullanarak Microsoft Entra ID ile kimlik doğrulaması yapabilirsiniz.

Aşağıda gösterilen DefaultAzureCredential sağlayıcısını veya Azure SDK ile sağlanan diğer kimlik bilgisi sağlayıcılarını kullanmak için lütfen @azure/identity paketini yükleyin:

npm install @azure/identity

DefaultAzureCredentialbirkaç Microsoft Entra kimliğini destekler. Yerel geliştirme sırasında, desteklenen bir geliştirme aracı aracılığıyla giriş yapmış bir geliştirici kimliği kullanabilir. Azure'da yönetilen bir kimlik kullanabilir. Ayrıca, ortam için yapılandırıldığında bir hizmet prensibini veya iş yükü kimliğini de doğrulayabilir.

Hangi kimliği kullanırsanız kullanın, uygun bir Azure Web PubSub veri düzlemi rolü atanmalıdır. Azure kaynak yönetimi rolleri, örneğin Owner veri düzlemi izni verme.

İstemciyi bir bağlantı dizesi, örneğin bir Microsoft Entra credential DefaultAzureCredentialveya bir 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>",
);

Temel kavramlar

WebPubSubChatServiceClient

WebPubSubChatServiceClient Web PubSub merkezindeki sohbet kaynaklarını yönetmek için birincil arayüzdür.

Merkez

Hub, bir sohbet uygulaması için mantıksal sınırdır. Bir istemci tarafından yönetilen roller, kullanıcılar, odalar, konuşmalar ve mesajlar, tamamı istemci yapıcısına sağlanan hub'a aittir.

Roller ve izinler

Bir kullanıcı rolü, odalar oluşturmak gibi merkez düzeyindeki işlemleri kontrol eder. Bir oda rolü, mesaj yayınlama, mesaj geçmişini okumak veya kullanıcıları davet etmek gibi oda içindeki eylemleri kontrol eder.

Odalar, üyeler ve sohbetler

Bir odada üyeler bulunur ve varsayılan bir konuşma vardır. Kullanıcıya bir oda rolü atayarak bir kullanıcıyı odaya ekleyin. Mesajlar, bağlı sohbet istemcileri tarafından yayınlanır ve hizmet istemcisi aracılığıyla listelenebilir, güncellenebilir veya sililebilir.

Varlık etiketleri

Sohbet kaynakları bir etag değer içerir. Bu değeri, koşullu güncelleme veya silme seçeneğinden geçirin ve yeni bir kaynak sürümünün üzerine yazılmasını ifMatch önleyin.

Örnekler

Roller, bir kullanıcı ve bir oda oluşturun

Kullanıcı ve oda rolleri oluşturun, insan kullanıcı ve bir oda oluşturun ve ardından kullanıcıyı odaya ekleyin.

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

Yerleşik rolleri ve bilinen izinleri kullanın

Hizmet tanımlı bir rol atarken ve KnownChatPermission özel bir rol oluştururken kullanınBuiltInChatRoles. Bilinen değerler dışındaki izin dizeleri de ilete uyumluluk için kabul edilir.

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

Rolleri yönetme

Özel bir rol oluşturun, alın, rolleri hub'da listeleyin ve bitince özel rolü silin.

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

Bir odayı yönetin

Bir oda oluşturun, mevcut durumunu geri alın ve silin.

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

Bir kullanıcıyı yönetin

Yerleşik bir role sahip bir kullanıcı oluşturun, profili alın ve silin.

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

Bir sohbette mesajları listele

Tüm sonuç sayfalarında bir konuşmadan gelen mesajları okumak için asenkron yineleme kullanın.

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

İstemci erişim tokenı oluştur

Bir sohbet istemcisinin, belirli bir kullanıcı olarak Web PubSub hizmetine bağlanmak için kullanabileceği bir URL oluşturun.

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

Ağaç kesimi

Loglamayı etkinleştirmek, hatalarla ilgili yararlı bilgilerin ortaya çıkmasına yardımcı olabilir. HTTP isteklerinin ve yanıtlarının günlüğünü görmek için ortam değişkenini AZURE_LOG_LEVEL olarak infoayarlayın. Alternatif olarak, çalışma zamanında setLogLevel@azure/logger çağrılarak günlük tutma etkinleştirilebilir.

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

setLogLevel("info");

Günlükleri etkinleştirme hakkında daha ayrıntılı yönergeler için @azure/günlükçü paketi belgelerine bakabilirsiniz.

Contributing

Bu kitaplığa katkıda bulunmak istiyorsanız kodu oluşturma ve test etme hakkında daha fazla bilgi edinmek için lütfen katkıda bulunma kılavuzu okuyun.