مكتبة عميل Azure Communication Chat ل JavaScript - الإصدار 1.6.0

تتيح Azure Communication Services للدردشة للمطورين إضافة قدرات الدردشة إلى تطبيقهم. استخدم مكتبة العميل هذه لإدارة مؤشرات ترابط الدردشة ومستخدميها، وإرسال رسائل الدردشة وتلقيها.

اقرأ المزيد حول خدمات اتصالات Azure هنا

الشروع

المتطلبات المسبقه

• اشتراك Azure .
• مورد Communication Services موجود. إذا كنت بحاجة إلى إنشاء المورد، يمكنك استخداممدخل Azure أو Azure PowerShellأو Azure CLI.
• Node.js

تثبيت

npm install @azure/communication-chat

دعم المستعرض

حزمة JavaScript

لاستخدام مكتبة العميل هذه في المستعرض، تحتاج أولا إلى استخدام مجمع. للحصول على تفاصيل حول كيفية القيام بذلك، يرجى الرجوع إلى وثائق التجميع . في rollup.config.js، أضف عمليات تصدير الأسماء المخصصة التالية في المكون الإضافي cjs.

cjs({
  namedExports: {
    events: ["EventEmitter"],
    "@azure/communication-signaling": ["CommunicationSignalingClient", "SignalingClient"],
    "@opentelemetry/api": ["CanonicalCode", "SpanKind", "TraceFlags"]
  }
})

المفاهيم الرئيسية

يتم تمثيل محادثة الدردشة بواسطة مؤشر ترابط. يسمى كل مستخدم في مؤشر الترابط بالمشارك في الدردشة. يمكن للمشاركين في الدردشة الدردشة مع بعضهم البعض بشكل خاص في دردشة 1:1 أو التكدس في دردشة جماعية 1:N. يحصل المستخدمون أيضا على تحديثات في الوقت الفعلي تقريبا عندما يكتب الآخرون ومتى قرأوا الرسائل.

ChatClient

ChatClient هي الواجهة الأساسية للمطورين الذين يستخدمون مكتبة العميل هذه. يوفر أساليب غير متزامنة لإنشاء مؤشر ترابط وحذفه.

ChatThreadClient

يوفر ChatThreadClient أساليب غير متزامنة للقيام بعمليات المشاركين في الرسالة والدردشة داخل مؤشر ترابط الدردشة.

امثله

تهيئة ChatClient

استخدم عنوان URL للمورد ورمز وصول المستخدم لتهيئة عميل الدردشة.

import { AzureCommunicationTokenCredential } from "@azure/communication-common";
import { ChatClient } from "@azure/communication-chat";

// Your unique Azure Communication service endpoint
const endpointUrl = "<ENDPOINT>";
const userAccessToken = "<USER_ACCESS_TOKEN>";
const tokenCredential = new AzureCommunicationTokenCredential(userAccessToken);
const chatClient = new ChatClient(endpointUrl, tokenCredential);

إنشاء مؤشر ترابط مع مستخدمين اثنين

استخدم أسلوب createThread لإنشاء مؤشر ترابط دردشة.

يتم استخدام createChatThreadRequest لوصف طلب مؤشر الترابط:

• استخدم topic لإعطاء موضوع مؤشر ترابط؛

يتم استخدام createChatThreadOptions لتعيين المعلمات الاختيارية لإنشاء مؤشر الترابط:

• استخدم participants لسرد المشاركين في الدردشة لإضافتها إلى مؤشر الترابط؛
• استخدام idempotencyToken لتحديد طلب قابل للتكرار

createChatThreadResult هي النتيجة التي تم إرجاعها من إنشاء مؤشر ترابط. يحتوي على chatThread وهو مؤشر الترابط الذي تم إنشاؤه، بالإضافة إلى خاصية errors التي ستحتوي على معلومات حول المشاركين غير الصالحين إذا فشل إضافتهم إلى مؤشر الترابط.

import { AzureCommunicationTokenCredential } from "@azure/communication-common";
import { ChatClient } from "@azure/communication-chat";

// Your unique Azure Communication service endpoint
const endpointUrl = "<ENDPOINT>";
const userAccessToken = "<USER_ACCESS_TOKEN>";
const tokenCredential = new AzureCommunicationTokenCredential(userAccessToken);
const chatClient = new ChatClient(endpointUrl, tokenCredential);

const createChatThreadRequest = {
  topic: "Hello, World!",
};

const createChatThreadOptions = {
  participants: [
    {
      id: { communicationUserId: "<USER_ID>" },
      displayName: "<USER_DISPLAY_NAME>",
    },
  ],
};

const createChatThreadResult = await chatClient.createChatThread(
  createChatThreadRequest,
  createChatThreadOptions,
);

const threadId = createChatThreadResult?.chatThread?.id;

إنشاء ChatThreadClient

سيسمح لك ChatThreadClient بإجراء عمليات خاصة بسلسلة رسائل الدردشة، مثل تحديث موضوع مؤشر ترابط الدردشة، وإرسال رسالة، وإضافة مشاركين إلى مؤشر ترابط الدردشة، وما إلى ذلك.

يمكنك تهيئة ChatThreadClient جديد باستخدام أسلوب getChatThreadClient ل ChatClient مع معرف مؤشر ترابط موجود:

import { AzureCommunicationTokenCredential } from "@azure/communication-common";
import { ChatClient } from "@azure/communication-chat";

// Your unique Azure Communication service endpoint
const endpointUrl = "<ENDPOINT>";
const userAccessToken = "<USER_ACCESS_TOKEN>";
const tokenCredential = new AzureCommunicationTokenCredential(userAccessToken);
const chatClient = new ChatClient(endpointUrl, tokenCredential);

const chatThreadClient = chatClient.getChatThreadClient("<threadId>");

إرسال رسالة إلى مؤشر الترابط

استخدم أسلوب sendMessage لإرسال رسالة إلى مؤشر ترابط تم تحديده بواسطة threadId.

يتم استخدام sendMessageRequest لوصف طلب الرسالة:

• استخدم content لتوفير محتوى رسالة الدردشة؛

يتم استخدام sendMessageOptions لوصف العملية المعلمات الاختيارية:

• استخدم senderDisplayName لتحديد اسم العرض للمرسل؛
• استخدم type لتحديد نوع الرسالة، مثل "نص" أو "html" ؛

sendChatMessageResult هي النتيجة التي يتم إرجاعها من إرسال رسالة، فهي تحتوي على معرف، وهو المعرف الفريد للرسالة.

import { AzureCommunicationTokenCredential } from "@azure/communication-common";
import { ChatClient, SendMessageOptions } from "@azure/communication-chat";

// Your unique Azure Communication service endpoint
const endpointUrl = "<ENDPOINT>";
const userAccessToken = "<USER_ACCESS_TOKEN>";
const tokenCredential = new AzureCommunicationTokenCredential(userAccessToken);
const chatClient = new ChatClient(endpointUrl, tokenCredential);

const chatThreadClient = chatClient.getChatThreadClient("<threadId>");

const sendMessageRequest = {
  content: "Hello Geeta! Can you share the deck for the conference?",
};

const sendMessageOptions: SendMessageOptions = {
  senderDisplayName: "Jack",
  type: "text",
};

const sendChatMessageResult = await chatThreadClient.sendMessage(
  sendMessageRequest,
  sendMessageOptions,
);

const messageId = sendChatMessageResult.id;

تلقي رسائل من مؤشر ترابط

باستخدام الإشارات في الوقت الحقيقي، يمكنك الاشتراك في الاستماع إلى الرسائل الواردة الجديدة وتحديث الرسائل الحالية في الذاكرة وفقا لذلك.

import { AzureCommunicationTokenCredential } from "@azure/communication-common";
import { ChatClient } from "@azure/communication-chat";

// Your unique Azure Communication service endpoint
const endpointUrl = "<ENDPOINT>";
const userAccessToken = "<USER_ACCESS_TOKEN>";
const tokenCredential = new AzureCommunicationTokenCredential(userAccessToken);
const chatClient = new ChatClient(endpointUrl, tokenCredential);

// open notifications channel
await chatClient.startRealtimeNotifications();
// subscribe to new notification
chatClient.on("chatMessageReceived", (e) => {
  console.log("Notification chatMessageReceived!");
  // your code here
});

بدلا من ذلك، يمكنك استرداد رسائل الدردشة عن طريق استقصاء أسلوب listMessages على فترات زمنية محددة.

import { AzureCommunicationTokenCredential } from "@azure/communication-common";
import { ChatClient } from "@azure/communication-chat";

// Your unique Azure Communication service endpoint
const endpointUrl = "<ENDPOINT>";
const userAccessToken = "<USER_ACCESS_TOKEN>";
const tokenCredential = new AzureCommunicationTokenCredential(userAccessToken);
const chatClient = new ChatClient(endpointUrl, tokenCredential);

const chatThreadClient = chatClient.getChatThreadClient("<threadId>");

for await (const chatMessage of chatThreadClient.listMessages()) {
  // your code here
}

إضافة مستخدمين إلى مؤشر ترابط

بمجرد إنشاء مؤشر ترابط، يمكنك بعد ذلك إضافة مستخدمين وإزالتها من مؤشر الترابط هذا. بإضافة مستخدمين، يمكنك منحهم حق الوصول حتى يتمكنوا من إرسال رسائل إلى مؤشر الترابط. ستحتاج إلى البدء بالحصول على رمز مميز جديد للوصول وهوية لهذا المستخدم. سيحتاج المستخدم إلى رمز الوصول المميز هذا من أجل تهيئة عميل الدردشة الخاص به. مزيد من المعلومات حول الرموز المميزة هنا: المصادقة على Azure Communication Services

import { AzureCommunicationTokenCredential } from "@azure/communication-common";
import { ChatClient } from "@azure/communication-chat";

// Your unique Azure Communication service endpoint
const endpointUrl = "<ENDPOINT>";
const userAccessToken = "<USER_ACCESS_TOKEN>";
const tokenCredential = new AzureCommunicationTokenCredential(userAccessToken);
const chatClient = new ChatClient(endpointUrl, tokenCredential);

const chatThreadClient = chatClient.getChatThreadClient("<threadId>");

const addParticipantsRequest = {
  participants: [
    {
      id: { communicationUserId: "<NEW_PARTICIPANT_USER_ID>" },
      displayName: "Jane",
    },
  ],
};

await chatThreadClient.addParticipants(addParticipantsRequest);

إزالة المستخدمين من مؤشر ترابط

كما هو موضح أعلاه، يمكنك أيضا إزالة المستخدمين من مؤشر ترابط. للإزالة، ستحتاج إلى تعقب معرفات المشاركين الذين أضفتمهم.

import { AzureCommunicationTokenCredential } from "@azure/communication-common";
import { ChatClient } from "@azure/communication-chat";

// Your unique Azure Communication service endpoint
const endpointUrl = "<ENDPOINT>";
const userAccessToken = "<USER_ACCESS_TOKEN>";
const tokenCredential = new AzureCommunicationTokenCredential(userAccessToken);
const chatClient = new ChatClient(endpointUrl, tokenCredential);

const chatThreadClient = chatClient.getChatThreadClient("<threadId>");

await chatThreadClient.removeParticipant({ communicationUserId: "<MEMBER_ID>" });

الاشتراك في حالة الاتصال للإعلامات في الوقت الحقيقي

يسمح لك الاشتراك في الأحداث realTimeNotificationConnectedrealTimeNotificationDisconnected بمعرفة متى يكون الاتصال بخادم الاتصال نشطا.

import { AzureCommunicationTokenCredential } from "@azure/communication-common";
import { ChatClient } from "@azure/communication-chat";

// Your unique Azure Communication service endpoint
const endpointUrl = "<ENDPOINT>";
const userAccessToken = "<USER_ACCESS_TOKEN>";
const tokenCredential = new AzureCommunicationTokenCredential(userAccessToken);
const chatClient = new ChatClient(endpointUrl, tokenCredential);

// subscribe to realTimeNotificationConnected event
chatClient.on("realTimeNotificationConnected", () => {
  console.log("Real time notification is now connected!");
  // your code here
});

// subscribe to realTimeNotificationDisconnected event
chatClient.on("realTimeNotificationDisconnected", () => {
  console.log("Real time notification is now disconnected!");
  // your code here
});

استكشاف الاخطاء

تسجيل

قد يساعد تمكين التسجيل في الكشف عن معلومات مفيدة حول حالات الفشل. لمشاهدة سجل طلبات واستجابات HTTP، قم بتعيين AZURE_LOG_LEVEL متغير البيئة إلى info. بدلا من ذلك، يمكن تمكين التسجيل في وقت التشغيل عن طريق استدعاء setLogLevel في @azure/logger:

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

setLogLevel("info");

الخطوات التالية

في هذا التشغيل السريع تعلمت كيفية:

• إنشاء عميل دردشة
• إنشاء مؤشر ترابط مع مستخدمين
• إرسال رسالة إلى مؤشر الترابط
• تلقي رسائل من مؤشر ترابط
• إزالة المستخدمين من مؤشر ترابط

المساهمه

إذا كنت ترغب في المساهمة في هذه المكتبة، فيرجى قراءة دليل المساهمة لمعرفة المزيد حول كيفية إنشاء التعليمات البرمجية واختبارها.