إضافة دردشة إلى تطبيقك

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

المتطلبات الأساسية

  • حساب Azure مع اشتراك نشط. أنشئ حساباً مجاناً.

  • مورد "خدمات الاتصال" النشطة وسلسلة الاتصال. إنشاء مورد Communication Services

  • تثبيت Azure CLI.

  • لاحظ نقطة نهاية مورد Communication Services. يمكنك الحصول على نقطة النهاية من مدخل Microsoft Azure. بدلا من ذلك، يمكنك العثور على عنوان url لنقطة النهاية في سلسلة الاتصال. إنه عنوان URL الذي يأتي بعد endpoint= ويبدأ ب https://.

  • رمز مميز لوصول المستخدم. تأكد من تعيين النطاق للدردشة، ولاحظ سلسلة الرمز المميز بالإضافة إلى سلسلة user_id. يمكنك أيضا استخدام Azure CLI وتشغيل الأمر التالي مع سلسلة الاتصال لإنشاء مستخدم ورمز مميز للوصول.

    az communication identity token issue --scope chat --connection-string "yourConnectionString"

    للحصول على التفاصيل، راجع استخدام Azure CLI لإنشاء الرموز المميزة للوصول وإدارتها.

الإعداد

إضافة الملحق

أضف ملحق Azure Communication Services ل Azure CLI باستخدام az extension الأمر .

az extension add --name communication

تسجيل الدخول إلى واجهة سطر الأوامر Azure

تحتاج إلى تسجيل الدخول إلى Azure CLI. يمكنك تسجيل الدخول عن طريق تشغيل az login الأمر من المحطة الطرفية وتوفير بيانات الاعتماد الخاصة بك.

(اختياري) استخدام عمليات هوية Azure CLI دون تمرير نقطة نهاية أو رمز مميز للوصول

تخزين نقطة النهاية في متغير بيئة

يمكنك تكوين AZURE_COMMUNICATION_ENDPOINT متغير البيئة لاستخدام عمليات دردشة Azure CLI دون الحاجة إلى استخدام --endpoint لتمرير نقطة النهاية. لتكوين متغير بيئة، افتح نافذة وحدة تحكم وحدد نظام التشغيل الخاص بك من علامات التبويب التالية. استبدل <yourEndpoint> بنقطة النهاية الفعلية.

افتح إطار وحدة التحكم وأدخل الأمر التالي:

setx AZURE_COMMUNICATION_ENDPOINT "<yourEndpoint>"

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

تخزين الرمز المميز للوصول في متغير بيئة

يمكنك تكوين AZURE_COMMUNICATION_ACCESS_TOKEN متغير البيئة لاستخدام عمليات دردشة Azure CLI دون الحاجة إلى استخدام --access-token لتمرير رمز الوصول المميز. لتكوين متغير بيئة، افتح نافذة وحدة تحكم وحدد نظام التشغيل الخاص بك من علامات التبويب التالية. استبدل <yourAccessToken> برمز الوصول الفعلي الخاص بك.

افتح إطار وحدة التحكم وأدخل الأمر التالي:

setx AZURE_COMMUNICATION_ACCESS_TOKEN "<yourAccessToken>"

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

العمليات

بدء تشغيل مؤشر ترابط الدردشة

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

az communication chat thread create --topic "<chatTopic>" --endpoint "<endpoint>" --access-token "<token>"

إذا قمت بتخزين نقطة النهاية ورمز الوصول المميز في متغيرات البيئة كما ذكر سابقا، فلن تحتاج إلى تمريرها إلى الأمر .

az communication chat thread create --topic "<chatTopic>"
  • يستخدم <chatTopic> لإعطاء الموضوع مؤشر ترابط. يمكنك تحديث الموضوع بعد إنشاء مؤشر ترابط الدردشة thread update-topic باستخدام الأمر .
  • استبدل <endpoint> بنقطة نهاية Azure Communication Services.
  • استبدل <token> برمز الوصول المميز الذي تم الحصول عليه سابقا بأمر قيد التشغيل identity token issue .

تحديث موضوع مؤشر ترابط محادثة

az communication chat thread update-topic --thread "<chatThreadId>" --topic "<chatTopic>" --endpoint "<endpoint>" --access-token "<token>"
  • استبدل <chatThreadId> بمعرف مؤشر ترابط الدردشة.
  • استبدل <chatTopic> بموضوع الدردشة الجديد الذي تريد تعيينه.
  • استبدل <endpoint> بنقطة نهاية Azure Communication Services.
  • استبدل <token> برمز الوصول المميز الذي تم الحصول عليه سابقا بأمر قيد التشغيل identity token issue .

سرد جميع مؤشرات ترابط الدردشة

يقوم thread list الأمر بإرجاع قائمة مؤشرات ترابط الدردشة للمستخدم.

az communication chat thread list --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"
  • اختياري: استخدم <startTime> لتحديد أقرب نقطة زمنية للحصول على رسائل الدردشة.
  • استبدل <endpoint> بنقطة نهاية Azure Communication Services.
  • استبدل <token> برمز الوصول المميز الذي تم الحصول عليه سابقا بأمر قيد التشغيل identity token issue .

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

message send استخدم الأمر لإرسال رسالة إلى مؤشر ترابط دردشة قمت بإنشائه، تم تعريفه بواسطة threadId.

az communication chat message send --thread "<chatThreadId>" --display-name "<displayName>" --content "<content>" --message-type "<messageType>"  --endpoint "<endpoint>" --access-token "<token>"
  • استبدل <chatThreadId> بمعرف مؤشر ترابط الدردشة.
  • استخدم <content> لتوفير محتوى رسالة الدردشة.
  • استخدم <messageType> لتحديد نوع محتوى الرسالة. القيم المُحتملة هي text وhtml. إذا لم تُحدد قيمة، فسيكون الافتراضي هو text.
  • استخدم <displayName> اختياريا لتحديد اسم العرض للمرسل.
  • استبدل <endpoint> بنقطة نهاية Azure Communication Services.
  • استبدل <token> برمز الوصول المميز الذي تم الحصول عليه سابقا بأمر قيد التشغيل identity token issue .

سرد رسائل الدردشة في مؤشر ترابط الدردشة

يقوم message list الأمر بإرجاع قائمة رسائل الدردشة في مؤشر ترابط الدردشة.

az communication chat message list --thread "<chatThreadId>" --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"
  • استبدل <chatThreadId> بمعرف مؤشر ترابط الدردشة.
  • استخدم <startTime> اختياريا لتحديد أقرب نقطة زمنية للحصول على رسائل الدردشة.
  • استبدل <endpoint> بنقطة نهاية Azure Communication Services.
  • استبدل <token> برمز الوصول المميز الذي تم الحصول عليه سابقا بأمر قيد التشغيل identity token issue .

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

يمكنك استرداد رسائل الدردشة message list باستخدام الأمر .

az communication chat message get --thread "<chatThreadId>" --message-id "<messageId>" --endpoint "<endpoint>" --access-token "<token>"
  • استبدل <chatThreadId> بمعرف مؤشر ترابط الدردشة.
  • استبدل <messageId> بمعرف الرسالة التي تريد استردادها.
  • استبدل <endpoint> بنقطة نهاية Azure Communication Services.
  • استبدل <token> برمز الوصول المميز الذي تم الحصول عليه سابقا بأمر قيد التشغيل identity token issue .

إرسال إيصال بالقراءة

يمكنك استخدام message receipt send الأمر لنشر حدث إيصال قراءة إلى مؤشر ترابط، نيابة عن مستخدم.

az communication chat message receipt send --thread "<chatThreadId>" --message-id "<messageId>" --endpoint "<endpoint>" --access-token "<token>"
  • استبدل <chatThreadId> بمعرف مؤشر ترابط الدردشة.
  • استبدل <messageId> لتحديد معرف أحدث رسالة يقرأها المستخدم الحالي.
  • استبدل <endpoint> بنقطة نهاية Azure Communication Services.
  • استبدل <token> برمز الوصول المميز الذي تم الحصول عليه سابقا بأمر قيد التشغيل identity token issue .

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

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

az communication chat participant add --thread "<chatThreadId>" --user "<userId>" --display-name "<displayName>" --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"
  • استبدل <chatThreadId> بمعرف مؤشر ترابط الدردشة.
  • استبدل <userId> بمعرف المستخدم الخاص بك.
  • استخدم <displayName> اختياريا لتحديد اسم العرض للمرسل.
  • استخدم <startTime> اختياريا لتحديد أقرب نقطة زمنية للحصول على رسائل الدردشة.
  • استبدل <endpoint> بنقطة نهاية Azure Communication Services.
  • استبدل <token> برمز الوصول المميز الذي تم الحصول عليه سابقا بأمر قيد التشغيل identity token issue .

قائمة المشاركين في مؤشر ترابط الدردشة

على غرار إضافة مشارك، يمكنك أيضاً سرد المشاركين من مؤشر الترابط.

استخدم participant list الأمر لاسترداد المشاركين في مؤشر الترابط.

az communication chat participant list --thread "<chatThreadId>" --skip "<skip>" --endpoint "<endpoint>" --access-token "<token>"
  • استبدل <chatThreadId> بمعرف مؤشر ترابط الدردشة.
  • استخدم <skip> اختياريا لتخطي المشاركين وصولا إلى موضع محدد في الاستجابة.
  • استبدل <endpoint> بنقطة نهاية Azure Communication Services.
  • استبدل <token> برمز الوصول المميز الذي تم الحصول عليه سابقا بأمر قيد التشغيل identity token issue .

إزالة مشارك من محادثة نصية للدردشة

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

az communication chat participant remove --thread "<chatThreadId>" --user "<userId>" --endpoint "<endpoint>" --access-token "<token>"
  • استبدل <chatThreadId> بمعرف مؤشر ترابط الدردشة.
  • استبدل <userId> بمعرف المستخدم الذي تريد إزالته من مؤشر ترابط الدردشة.
  • استبدل <endpoint> بنقطة نهاية Azure Communication Services.
  • استبدل <token> برمز الوصول المميز الذي تم الحصول عليه سابقا بأمر قيد التشغيل identity token issue .

المتطلبات الأساسية

  • إنشاء حساب في Azure باستخدام اشتراك نشط. لمزيد من التفاصيل، راجع إنشاء حساب مجانًا.

  • تثبيت Node.js إصدارات LTS Active LTS والصيانة LTS.

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

  • إنشاء ثلاثة مستخدمي خدمات اتصالات Azure وإصدار رمز مميز لوصول المستخدم لهم. تأكد من تعيين النطاق للدردشة، ولاحظ سلسلة الرمز المميز بالإضافة إلى سلسلة user_id. يحتوي العرض التوضيحي الكامل على إنشاء مؤشر ترابط مع المشاركيْن الأوليين ثم يضيف مشاركًا ثالثًا إلى مؤشر الترابط. يمكنك أيضا استخدام Azure CLI وتشغيل الأمر التالي مع سلسلة الاتصال لإنشاء مستخدم ورمز مميز للوصول.

    az communication identity token issue --scope chat --connection-string "yourConnectionString"

    للحصول على التفاصيل، راجع استخدام Azure CLI لإنشاء الرموز المميزة للوصول وإدارتها.

الإعداد

أنشئ تطبيق ويب جديدًا

أولاً، افتح المحطة الطرفية أو نافذة الأوامر لإنشاء دليل جديد لتطبيقك، وانتقل إليه.

mkdir chat-quickstart && cd chat-quickstart

قم بتشغيل npm init -y لإنشاء ملف package.json بالإعدادات الافتراضية.

npm init -y

قم بتثبيت الحِزَم

npm install استخدم الأمر لتثبيت Communication Services SDKs التالية ل JavaScript.

npm install @azure/communication-common --save

npm install @azure/communication-identity --save

npm install @azure/communication-signaling --save

npm install @azure/communication-chat --save

يسرد الخيار --save المكتبة كتبعية في ملف package.json.

إعداد إطار عمل التطبيق

تستخدم هذه المقالة webpack لتجميع أصول التطبيق. قم بتشغيل الأمر التالي لتثبيته وإدراجه كتبعية تطوير في package.json:

npm install webpack webpack-cli webpack-dev-server --save-dev

قم بإنشاء webpack.config.js في الدليل الجذر لمشروعك.

module.exports = {
    entry: "./client.js",
    output: {
        filename: "bundle.js"
    },
    devtool: "inline-source-map",
    mode: "development"
}

قم بإنشاء ملف index.html في الدليل الجذر لمشروعك. استخدم هذا الملف كقالب لإضافة إمكانية الدردشة باستخدام Azure Communication Chat SDK ل JavaScript.

<!DOCTYPE html>
<html>
  <head>
    <title>Communication Client - Chat Sample</title>
  </head>
  <body>
    <h4>Azure Communication Services</h4>
    <h1>Chat Quickstart</h1>
    <script src="./bundle.js"></script>
  </body>
</html>

أنشئ ملفا في الدليل الجذر لمشروعك يسمى client.js لاحتواء منطق التطبيق لهذه المقالة.

إنشاء عميل دردشة

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

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

داخل client.js استخدم نقطة النهاية ورمز الوصول المميز في التعليمات البرمجية التالية لإضافة إمكانية الدردشة باستخدام Azure Communication Chat SDK ل JavaScript.


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

// Your unique Azure Communication service endpoint
let endpointUrl = '<replace with your resource endpoint>';
// The user access token generated as part of the pre-requisites
let userAccessToken = '<USER_ACCESS_TOKEN>';

let chatClient = new ChatClient(endpointUrl, new AzureCommunicationTokenCredential(userAccessToken));
console.log('Azure Communication Chat client created!');
  • استبدل endpointUrl بنقطة نهاية مورد Communication Services. لمعرفة المزيد من المعلومات، انظر إنشاء مورد Azure Communication Services.
  • استبدل userAccessToken بالرمز المميز الذي أصدرته.

تشغيل التعليمات البرمجية

قم بتحديث القسم scripts في package.json ليشمل "ابدأ"

"start": "webpack serve --config ./webpack.config.js"

قم بتشغيل الأمر التالي لتشغيل التطبيق الخاص بك:

npm install
npm run start

افتح المستعرض وانتقل إلى http://localhost:8080/. في وحدة تحكم أدوات المطور داخل المستعرض، يجب أن ترى:

Azure Communication Chat client created!

نموذج الكائن

تعالج الفئات والواجهات التالية بعض الميزات الرئيسية لـ Azure Communication Services Chat SDK لـ JavaScript.

Name ‏‏الوصف
ChatClient هذه الفئة مطلوبة لوظيفة الدردشة. يمكنك إنشاء مثيل لها بمعلومات اشتراكك واستخدامها لإنشاء مؤشرات الترابط والحصول عليها وحذفها والاشتراك في أحداث الدردشة.
ChatThreadClient هذه الفئة مطلوبة لوظيفة مؤشر ترابط الدردشة. يمكنك الحصول على مثيل عبر ChatClient، واستخدامه في إرسال الرسائل/استقبالها/تحديثها/حذفها، وإضافة المستخدمين/حذفهم/الحصول عليهم، وإرسال إشعارات الكتابة وإعلامات بالقراءة.

بدء تشغيل مؤشر ترابط الدردشة

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

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

  • استخدم topic لإعطاء موضوع لهذه الدردشة. يمكن تحديث الموضوعات بعد إنشاء مؤشر ترابط الدردشة باستخدام الدالة UpdateThread .
  • استخدم participants لسرد المشاركين المطلوب إضافتهم إلى مؤشر ترابط الدردشة.

عند حلها، createChatThread يقوم الأسلوب بإرجاع CreateChatThreadResult. يحتوي هذا النموذج على خاصية chatThread حيث يمكنك الوصول إلى id مؤشر الترابط الذي تم إنشاؤه حديثا. يمكنك بعد ذلك استخدام id للحصول على مثيل .ChatThreadClient ChatThreadClient يمكن بعد ذلك استخدام لتنفيذ العملية داخل مؤشر الترابط مثل إرسال الرسائل أو سرد المشاركين.

async function createChatThread() {
  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;
  return threadId;
}

createChatThread().then(async threadId => {
  console.log(`Thread created:${threadId}`);
  // PLACEHOLDERS
  // <CREATE CHAT THREAD CLIENT>
  // <RECEIVE A CHAT MESSAGE FROM A CHAT THREAD>
  // <SEND MESSAGE TO A CHAT THREAD>
  // <LIST MESSAGES IN A CHAT THREAD>
  // <ADD NEW PARTICIPANT TO THREAD>
  // <LIST PARTICIPANTS IN A THREAD>
  // <REMOVE PARTICIPANT FROM THREAD>
  });

عند تحديث علامة تبويب المستعرض، يجب أن تشاهد الرسالة التالية في وحدة التحكم:

Thread created: <thread_id>

الحصول على عميل مؤشر ترابط الدردشة

يقوم getChatThreadClient الأسلوب بإرجاع chatThreadClient لسلسلة رسائل موجودة بالفعل. ويمكن استخدامه لتنفيذ العمليات على مؤشر الترابط المنشأ، مثل: إضافة المشاركين، إرسال رسالة، وما إلى ذلك. وتمثل الدالة «threadId» المعرف الفريد لمؤشر ترابط الدردشة الموجود.

let chatThreadClient = chatClient.getChatThreadClient(threadId);
console.log(`Chat Thread client for threadId:${threadId}`);

أضف هذه التعليمة البرمجية <CREATE CHAT THREAD CLIENT> بدلا من التعليق في client.js، وحدث علامة تبويب المستعرض وتحقق من وحدة التحكم، يجب أن ترى:

Chat Thread client for threadId: <threadId>

سرد جميع مؤشرات ترابط الدردشة

يقوم listChatThreads الأسلوب بإرجاع PagedAsyncIterableIterator من نوع ChatThreadItem. ويمكن استخدامه لسرد جميع موضوعات الدردشة. مكرر هو [ChatThreadItem] الاستجابة التي تم إرجاعها من سرد مؤشرات الترابط

const threads = chatClient.listChatThreads();
for await (const thread of threads) {
   // your code here
}

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

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

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

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

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

  • استخدم senderDisplayName لتحديد اسم العرض للمرسل؛
  • يستخدم type لتحديد نوع الرسالة، مثل "نص" أو "html"؛
  • استخدم metadata اختياريا لتضمين أي بيانات أخرى تريد إرسالها مع الرسالة. يوفر هذا الحقل آلية للمطورين لتوسيع وظائف رسالة الدردشة وإضافة معلومات مُخصصة لحالة الاستخدام. على سبيل المثال، عند مشاركة ارتباط ملف في الرسالة، قد تحتاج إلى إضافة "hasAttachment: true" في بيانات التعريف بحيث يمكن لتطبيق المستلم تحليل ذلك وعرضه وفقا لذلك.

SendChatMessageResult هو الاستجابة المُرجعة من إرسال رسالة. يحتوي على المعرف الفريد للرسالة.

const sendMessageRequest =
{
  content: 'Please take a look at the attachment'
};
let sendMessageOptions =
{
  senderDisplayName : 'Jack',
  type: 'text',
  metadata: {
    'hasAttachment': 'true',
    'attachmentUrl': 'https://contoso.com/files/attachment.docx'
  }
};
const sendChatMessageResult = await chatThreadClient.sendMessage(sendMessageRequest, sendMessageOptions);
const messageId = sendChatMessageResult.id;
console.log(`Message sent!, message id:${messageId}`);

أضف هذه التعليمة البرمجية <SEND MESSAGE TO A CHAT THREAD> بدلا من التعليق في client.js، وحدث علامة تبويب المستعرض وتحقق من وحدة التحكم.

Message sent!, message id:<number>

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

الآن، يمكنك الاشتراك للاستماع للرسائل الواردة الجديدة وتحديث الرسائل الحالية في الذاكرة وفقًا لذلك. تدعم خدمة Azure Communication Services قائمة بالأحداث التي يمكنك الاشتراك فيها.

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

أضف هذه التعليمة البرمجية بدلا من <RECEIVE A CHAT MESSAGE FROM A CHAT THREAD> التعليق في client.js. تحديث علامة تبويب المستعرض، يجب أن تشاهد رسالة Notification chatMessageReceivedفي وحدة التحكم ؛

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


const messages = chatThreadClient.listMessages();
for await (const message of messages) {
   // your code here
}

أضف هذه التعليمة البرمجية <LIST MESSAGES IN A CHAT THREAD> بدلا من التعليق في client.js. حدّث علامة التبويب لديك، وسترى في وحدة التحكم قائمة الرسائل المرسلة في مؤشر ترابط الدردشة هذا.

listMessages إرجاع أنواع مختلفة من الرسائل التي يمكنك تحديدها بواسطة chatMessage.type.

لمزيد من المعلومات، راجع أنواع الرسائل.

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

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

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

addParticipantsRequest يصف كائن الطلب حيث يسرد participants المشاركين المراد إضافتهم إلى مؤشر ترابط الدردشة؛

  • id، مطلوب، هو معرف الاتصال الذي ستتم إضافته إلى مؤشر ترابط الدردشة.
  • displayName، الاختيارية تمثل الاسم المعروض للمشارك في مؤشر الترابط.
  • دالة shareHistoryTime-الاختيارية- تمثل الوقت الذي يشارّك فيه سجل الدردشة مع المشارك. لمشاركة السجلات منذ بداية مؤشر ترابط الدردشة، حدد هذه الخاصية إلى أي تاريخ يوافق وقت إنشاء مؤشر الترابط أو يسبقه. لمشاركة أي سجل سابق من وقت إضافة المشارك، حدده على التاريخ الحالي. لمشاركة السجل الجزئي، حدده على التاريخ الذي تختاره.

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

await chatThreadClient.addParticipants(addParticipantsRequest);

استبدل NEW_PARTICIPANT_USER_IDبمعرف مستخدم جديد أضف هذه التعليمة البرمجية <ADD NEW PARTICIPANT TO THREAD> بدلا من التعليق في client.js

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

const participants = chatThreadClient.listParticipants();
for await (const participant of participants) {
   // your code here
}

أضف هذه التعليمة البرمجية <LIST PARTICIPANTS IN A THREAD> بدلا من التعليق في client.js، وحدث علامة تبويب المستعرض وتحقق من وحدة التحكم. يجب أن تشاهد معلومات حول المستخدمين في مؤشر ترابط.

حذف مستخدم من مؤشر ترابط الدردشة

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

استخدم removeParticipant الأسلوب حيث participant هو مستخدم الاتصال المراد إزالته من مؤشر الترابط.


await chatThreadClient.removeParticipant({ communicationUserId: <PARTICIPANT_ID> });
await listParticipants();

استبدل PARTICIPANT_ID بمعرف المستخدم المستخدم في الخطوة السابقة (<NEW_PARTICIPANT_USER_ID>). أضف هذه التعليمة البرمجية <REMOVE PARTICIPANT FROM THREAD> بدلا من التعليق في client.js.

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

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

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

التعليمة البرمجية العينة

ابحث عن التعليمات البرمجية النهائية لهذه المقالة في نموذج GitHub إضافة دردشة إلى تطبيقك.

المتطلبات الأساسية

الإعداد

إنشاء تطبيق Python جديد

افتح نافذة الأوامر أو المحطة الطرفية، وأنشئ دليلاً جديداً لتطبيقك، ثم انتقل إليه.

mkdir chat-quickstart && cd chat-quickstart

استخدم محرر نص لإنشاء ملف يُسمى start-chat.py في الدليل الجذر للمشروع. إضافة البنية للبرنامج، بما في ذلك معالجة الاستثناء الأساسية. في الأقسام التالية، أضف كافة التعليمات البرمجية المصدر لهذه المقالة إلى هذا الملف.

import os
# Add required SDK components from quickstart here

try:
    print('Azure Communication Services - Chat Quickstart')
    # Quickstart code goes here
except Exception as ex:
    print('Exception:')
    print(ex)

تثبيت SDK

استخدم الأمر التالي لتثبيت SDK:


pip install azure-communication-chat

نموذج الكائن

تُعالج الفئات والواجهات التالية بعض الميزات الرئيسية Azure Communication Services Chat SDK لـ Python.

Name ‏‏الوصف
ChatClient هذه الفئة مطلوبة لوظيفة الدردشة. إنشاء مثيل مع معلومات اشتراك، واستخدامه لإنشاء مؤشرات الترابط والحصول عليها وحذفها.
ChatThreadClient هذه الفئة مطلوبة لوظيفة مؤشر ترابط الدردشة. يمكنك الحصول على مثيل عبر ChatClient، واستخدامه لإرسال الرسائل وتلقيها وتحديثها وحذفها. يمكنك أيضاً استخدامه لإضافة مستخدمين وإزالتهم والحصول عليهم وإرسال إشعارات الكتابة وقراءة الإيصالات.

إنشاء عميل دردشة

لإنشاء عميل دردشة، استخدم نقطة نهاية Communication Services ورمز الوصول المميز المُنشأ كجزء من خطوات المتطلبات الأساسية.

pip install azure-communication-identity

from azure.communication.chat import ChatClient, CommunicationTokenCredential

endpoint = "<replace with your resource endpoint>"
chat_client = ChatClient(endpoint, CommunicationTokenCredential("<Access Token>"))

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

بدء تشغيل مؤشر ترابط الدردشة

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

  • يستخدم topic لإعطاء الموضوع مؤشر ترابط. يمكنك تحديث الموضوع بعد إنشاء مؤشر ترابط الدردشة باستخدام update_thread الدالة.
  • يُستخدم thread_participants لسرد ChatParticipant لإضافته إلى مؤشر ترابط الدردشة. يأخذ ChatParticipant النوع CommunicationUserIdentifier كـ user.

CreateChatThreadResult هو النتيجة التي أُرجعت من إنشاء مؤشر الترابط. يمكنك استخدامه لإحضار id من مؤشر ترابط الدردشة المُنشأ. يمكن استخدام هذا id ثم لإحضار ChatThreadClient كائن باستخدام get_chat_thread_client الأسلوب. يمكنك استخدام ChatThreadClient لتنفيذ عمليات الدردشة الأخرى لمؤشر ترابط الدردشة هذا.

topic="test topic"

create_chat_thread_result = chat_client.create_chat_thread(topic)
chat_thread_client = chat_client.get_chat_thread_client(create_chat_thread_result.chat_thread.id)

الحصول على عميل مؤشر ترابط الدردشة

يُرجع get_chat_thread_client الأسلوب عميل مؤشر الترابط لمؤشر الترابط الموجود مسبقاً. يمكنك استخدامه لتنفيذ العمليات على مؤشر الترابط المُنشأ. على سبيل المثال، يمكنك إضافة المشاركين وإرسال الرسائل. thread_id هو المُعرف الفريد لمؤشر ترابط الدردشة الموجود.

يمكنك استخدام ChatThreadClient لتنفيذ عمليات الدردشة الأخرى لمؤشر ترابط الدردشة هذا.

thread_id = create_chat_thread_result.chat_thread.id
chat_thread_client = chat_client.get_chat_thread_client(thread_id)

سرد جميع مؤشرات ترابط الدردشة

يُرجع list_chat_threadsالأسلوب مكرراً من نوع ChatThreadItem.

  • استخدم start_time لتحديد أقرب نقطة زمنية للحصول على مؤشرات ترابط الدردشة.
  • استخدم results_per_page لتحديد الحد الأقصى لعدد مؤشرات ترابط الدردشة المُرجعة لكل صفحة.

المكرر من [ChatThreadItem]هو استجابة مُرجعة من سرد مؤشرات الترابط.

from datetime import datetime, timedelta

start_time = datetime.utcnow() - timedelta(days=2)

chat_threads = chat_client.list_chat_threads(results_per_page=5, start_time=start_time)
for chat_thread_item_page in chat_threads.by_page():
    for chat_thread_item in chat_thread_item_page:
        print(chat_thread_item)
        print('Chat Thread Id: ', chat_thread_item.id)

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

send_message استخدم الأسلوب لإرسال رسالة إلى مؤشر ترابط دردشة قمت بإنشائه، تم تعريفه بواسطة thread_id.

  • استخدم content لتوفير محتوى رسالة الدردشة.
  • استخدم chat_message_type لتحديد نوع محتوى الرسالة. القيم المُحتملة هي text وhtml. إذا لم تُحدد قيمة، فسيكون الافتراضي هو text.
  • استخدم sender_display_name لتحديد اسم العرض للمرسل.
  • استخدم metadata اختياريا لتضمين أي بيانات أخرى تريد إرسالها مع الرسالة. يوفر هذا الحقل آلية للمطورين لتوسيع وظائف رسالة الدردشة وإضافة معلومات مُخصصة لحالة الاستخدام. على سبيل المثال، عند مشاركة رابط ملف في الرسالة، قد تحتاج إلى إضافة "hasAttachment:true" في بيانات التعريف حتى يمكن لتطبيق المستلم تحليل ذلك وعرضه وفقاً لذلك.

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

from azure.communication.chat import ChatMessageType

topic = "test topic"
create_chat_thread_result = chat_client.create_chat_thread(topic)
thread_id = create_chat_thread_result.chat_thread.id
chat_thread_client = chat_client.get_chat_thread_client(create_chat_thread_result.chat_thread.id)


content='Please take a look at the attachment'
sender_display_name='sender name'
metadata={
    'hasAttachment': 'true',
    'attachmentUrl': 'https://contoso.com/files/attachment.docx'
}

# specify chat message type with pre-built enumerations
send_message_result_w_enum = chat_thread_client.send_message(content=content, sender_display_name=sender_display_name, chat_message_type=ChatMessageType.TEXT, metadata=metadata)
print("Message sent: id: ", send_message_result_w_enum.id)

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

يمكنك استرداد رسائل الدردشة باستقصاء list_messages الأسلوب في فترات زمنية محددة.

  • استخدم results_per_page لتحديد الحد الأقصى لعدد الرسائل المُرجعة لكل صفحة.
  • استخدم start_time لتحديد أقرب نقطة زمنية للحصول على الرسائل.

المكرر من [ChatMessage]هو استجابة مُرجعة من سرد الرسائل.

from datetime import datetime, timedelta

start_time = datetime.utcnow() - timedelta(days=1)

chat_messages = chat_thread_client.list_messages(results_per_page=1, start_time=start_time)
for chat_message_page in chat_messages.by_page():
    for chat_message in chat_message_page:
        print("ChatMessage: Id=", chat_message.id, "; Content=", chat_message.content.message)

list_messages يُرجع أحدث إصدار من الرسالة، بما في ذلك أي تعديل أو حذف حدث للرسالة باستخدام update_message وdelete_message. بالنسبة للرسائل ChatMessage.deleted_on المحذوفة، ترجع datetime قيمة تُشير إلى وقت حذف تلك الرسالة. بالنسبة للرسائل ChatMessage.edited_on المُحررة ترجع datetime قيمة تُشير إلى وقت تحرير تلك الرسالة. يمكنك الوصول إلى الوقت الأصلي لإنشاء الرسالة باستخدام ChatMessage.created_on، والذي يمكن استخدامه لترتيب الرسائل.

list_messages ترجع أنواعا مختلفة من الرسائل، والتي تحددها من ChatMessage.type.

لمزيد من المعلومات، راجع أنواع الرسائل.

إرسال إيصال بالقراءة

يمكنك استخدام send_read_receipt الأسلوب لنشر حدث إيصال بالقراءة إلى مؤشر الترابط، نيابة عن مستخدم.

  • استخدم message_id لتحديد مُعرف آخر رسالة قرأها المستخدم الحالي.
content='hello world'

send_message_result = chat_thread_client.send_message(content)
chat_thread_client.send_read_receipt(message_id=send_message_result.id)

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

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

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

يُرجع list(tuple(ChatParticipant, CommunicationError)). عند إضافة المشارك بنجاح، من المتوقع وجود قائمة فارغة. إذا واجهت خطأ أثناء إضافة مشارك، يتم ملء القائمة بالمشاركين الفاشلين والخطأ الذي تمت مواجهته.

from azure.communication.identity import CommunicationIdentityClient
from azure.communication.chat import ChatParticipant
from datetime import datetime

# create 2 users
identity_client = CommunicationIdentityClient.from_connection_string('<connection_string>')
new_users = [identity_client.create_user() for i in range(2)]

# # conversely, you can also add an existing user to a chat thread; provided the user_id is known
# from azure.communication.identity import CommunicationUserIdentifier
#
# user_id = 'some user id'
# user_display_name = "Wilma Flinstone"
# new_user = CommunicationUserIdentifier(user_id)
# participant = ChatParticipant(
#     identifier=new_user,
#     display_name=user_display_name,
#     share_history_time=datetime.utcnow())

participants = []
for _user in new_users:
  chat_thread_participant = ChatParticipant(
    identifier=_user,
    display_name='Fred Flinstone',
    share_history_time=datetime.utcnow()
  ) 
  participants.append(chat_thread_participant) 

response = chat_thread_client.add_participants(participants)

def decide_to_retry(error, **kwargs):
    """
    Insert some custom logic to decide if retry is applicable based on error
    """
    return True

# verify if all users has been successfully added or not
# in case of partial failures, you can retry to add all the failed participants 
retry = [p for p, e in response if decide_to_retry(e)]
if retry:
    chat_thread_client.add_participants(retry)

قائمة المشاركين في مؤشر ترابط الدردشة

على غرار إضافة مشارك، يمكنك أيضاً سرد المشاركين من مؤشر الترابط.

استخدم list_participants لاسترداد المشاركين في مؤشر الترابط. كلا الأمرين التاليين اختياريان:

  • استخدم results_per_page لتحديد الحد الأقصى لعدد المشاركين المُرجع لكل صفحة.
  • استخدم skip لتخطي المشاركين إلى موضع محدد في الاستجابة.

المكرر من [ChatParticipant]هو استجابة مُرجعة من سرد المشاركين.

chat_thread_participants = chat_thread_client.list_participants()
for chat_thread_participant_page in chat_thread_participants.by_page():
    for chat_thread_participant in chat_thread_participant_page:
        print("ChatParticipant: ", chat_thread_participant)

تشغيل التعليمات البرمجية

شغّل التطبيق من دليل تطبيقك باستخدام الأمر python.

python start-chat.py

التعليمة البرمجية العينة

ابحث عن التعليمات البرمجية النهائية لهذه المقالة في نموذج GitHub إضافة دردشة إلى تطبيقك.

المتطلبات الأساسية

الإعداد

إنشاء تطبيق Java جديد

افتح نافذة الأوامر أو terminal وانتقل إلى الدليل حيث ترغب في إنشاء تطبيق Java خاصتك. قم بتشغيل الأمر التالي لإنشاء مشروع Java من القالب maven-archetype-quickstart .

mvn archetype:generate -DgroupId=com.communication.quickstart -DartifactId=communication-quickstart -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false

generate يتم إنشاء الهدف دليل بنفس اسم artifactId. ضمن هذا الدليل، src/main/java directory يحتوي على التعليمات البرمجية لمصدر المشروع، src/test/java ويحتوي الدليل على مصدر الاختبار، والملف pom.xml هو نموذج كائن المشروع أو POM الخاص بالمشروع.

تحديث ملف POM لتطبيقك لاستخدام Java 8 أو أعلى:

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
</properties>

إضافة مراجع الحزمة لـ Chat SDK

في ملف POM،ارجع إلى الحزمة azure-communication-chat باستخدام واجهات برمجة تطبيقات الدردشة:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-chat</artifactId>
    <version><!-- Please refer to https://search.maven.org/artifact/com.azure/azure-communication-chat for the latest version --></version>
</dependency>

للمصادقة، يحتاج عميلك إلى الرجوع إلى azure-communication-common الحزمة:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-common</artifactId>
    <version><!-- Please refer to https://search.maven.org/artifact/com.azure/azure-communication-common for the latest version --></version>
</dependency>

نموذج الكائن

تُعالج الفئات والواجهات التالية بعض الميزات الرئيسية في Azure Communication Services Chat SDK لـ Java.

Name ‏‏الوصف
ChatClient هذه الفئة مطلوبة لوظيفة الدردشة. إنشاء مثيل مع معلومات اشتراك، واستخدامه لإنشاء مؤشرات الترابط والحصول عليها وحذفها.
ChatAsyncClient هذه الفئة ضرورية لوظيفة الدردشة غير المتزامنة. إنشاء مثيل مع معلومات اشتراك، واستخدامه لإنشاء مؤشرات الترابط والحصول عليها وحذفها.
ChatThreadClient هذه الفئة مطلوبة لوظيفة مؤشر ترابط الدردشة. يمكنك الحصول على مثيل عبر ChatClient، واستخدامه في إرسال الرسائل/استقبالها/تحديثها/حذفها، وإضافة المستخدمين/حذفهم/الحصول عليهم، وإرسال إشعارات الكتابة وإعلامات بالقراءة.
ChatThreadAsyncClient هذه الفئة مطلوبة لوظيفة مؤشر ترابط الدردشة غير المتزامنة. يمكنك الحصول على مثيل عبر ChatAsyncClient، واستخدامه في إرسال الرسائل/استقبالها/تحديثها/حذفها، وإضافة المستخدمين/حذفهم/الحصول عليهم، وإرسال إشعارات الكتابة وإعلامات بالقراءة.

إنشاء عميل دردشة

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

تعرف على المزيد حول تصميم الدردشة

عند إضافة عبارات الاستيراد، تأكد من إضافة استيرادات فقط من مساحة الاسم com.azure.communication.chat، com.azure.communication.chat.models، وليس من مساحة الاسم com.azure.communication.chat.implementation. في ملف App.java الذي أُنشئ عبر Maven، يمكنك استخدام التعليمات البرمجية التالية لتبدأ:

package com.communication.quickstart;

import com.azure.communication.chat.*;
import com.azure.communication.chat.models.*;
import com.azure.communication.common.*;
import com.azure.core.http.rest.PagedIterable;

import java.io.*;
import java.util.*;

public class App
{
    public static void main( String[] args ) throws IOException
    {
        System.out.println("Azure Communication Services - Chat Quickstart");

        // Your unique Azure Communication service endpoint
        String endpoint = "<replace with your resource endpoint>";

        // User access token fetched from your trusted service
        String userAccessToken = "<USER_ACCESS_TOKEN>";

        // Create a CommunicationTokenCredential with the given access token, which is only valid until the token is valid
        CommunicationTokenCredential userCredential = new CommunicationTokenCredential(userAccessToken);

        // Initialize the chat client
        final ChatClientBuilder builder = new ChatClientBuilder();
        builder.endpoint(endpoint)
            .credential(userCredential);
        ChatClient chatClient = builder.buildClient();
    }
}

بدء تشغيل مؤشر ترابط الدردشة

استخدم الأسلوب createChatThread لإنشاء مؤشر ترابط الدردشة. تستخدم createChatThreadOptions لوصف طلب مؤشر الترابط.

  • استخدم topic معلمة المُنشئ لإعطاء موضوع لهذه الدردشة؛ يمكنك تحديث الموضوعات بعد إنشاء مؤشر ترابط الدردشة باستخدام UpdateThread الدالة.
  • تُستخدم participants لسرد مؤشر ترابط المشاركين وإضافتهم إلى مؤشر الترابط. ChatParticipant يأخذ المستخدم الذي أنشأته في رمز وصول المستخدم المميز.

CreateChatThreadResult هي الاستجابة التي أُرجعت من إنشاء مؤشر ترابط الدردشة. يحتوي على أسلوب getChatThread() يقوم بإرجاع ChatThread الكائن الذي يمكن استخدامه للحصول على عميل مؤشر الترابط الذي يمكنك من خلاله الحصول على ChatThreadClient لتنفيذ العمليات على مؤشر الترابط الذي تم إنشاؤه: إضافة مشاركين وإرسال رسالة وما إلى ذلك. ChatThread يحتوي الكائن أيضا على getId() الأسلوب الذي يسترد المعرف الفريد لسلسلة الرسائل.

CommunicationUserIdentifier identity1 = new CommunicationUserIdentifier("<USER_1_ID>");
CommunicationUserIdentifier identity2 = new CommunicationUserIdentifier("<USER_2_ID>");

ChatParticipant firstThreadParticipant = new ChatParticipant()
    .setCommunicationIdentifier(identity1)
    .setDisplayName("Participant Display Name 1");

ChatParticipant secondThreadParticipant = new ChatParticipant()
    .setCommunicationIdentifier(identity2)
    .setDisplayName("Participant Display Name 2");

CreateChatThreadOptions createChatThreadOptions = new CreateChatThreadOptions("Topic")
    .addParticipant(firstThreadParticipant)
    .addParticipant(secondThreadParticipant);

CreateChatThreadResult result = chatClient.createChatThread(createChatThreadOptions);
String chatThreadId = result.getChatThread().getId();

قائمة مؤشرات ترابط الدردشة

استخدم listChatThreads الأسلوب لاسترداد قائمة بمؤشرات ترابط الدردشة الموجودة.

PagedIterable<ChatThreadItem> chatThreads = chatClient.listChatThreads();

chatThreads.forEach(chatThread -> {
    System.out.printf("ChatThread id is %s.\n", chatThread.getId());
});

الحصول على عميل مؤشر ترابط الدردشة

يُرجع getChatThreadClient الأسلوب عميل مؤشر الترابط لمؤشر الترابط الموجود مسبقاً. ويمكن استخدامه لتنفيذ العمليات على مؤشر الترابط المنشأ، مثل: إضافة المشاركين، إرسال رسالة، وما إلى ذلك. وتمثل الدالة chatThreadId المُعرف الفريد لمؤشر ترابط الدردشة الموجود.

ChatThreadClient chatThreadClient = chatClient.getChatThreadClient(chatThreadId);

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

sendMessage استخدم الأسلوب لإرسال رسالة إلى سلسلة الرسائل التي قمت بإنشائها، والتي تم تعريفها بواسطة chatThreadId. تستخدم الدالة ⁧sendChatMessageOptions⁩ لوصف طلب رسالة الدردشة.

  • استخدم content لتوفير محتوى رسالة الدردشة.
  • استخدم type لتحديد نوع محتوى رسالة الدردشة، TEXT أو HTML.
  • استخدم senderDisplayName لتحديد اسم العرض للمرسل.
  • استخدم metadata اختياريا لتضمين أي بيانات أخرى تريد إرسالها مع الرسالة. يوفر هذا الحقل آلية للمطورين لتوسيع وظائف رسالة الدردشة وإضافة معلومات مُخصصة لحالة الاستخدام. على سبيل المثال، عند مشاركة ارتباط ملف في الرسالة، قد تحتاج إلى إضافة hasAttachment:true بيانات التعريف بحيث يمكن لتطبيق المستلم تحليل ذلك وعرضه وفقا لذلك.

تحتوي الاستجابة sendChatMessageResult على id، وهو المُعرف الفريد للرسالة.

Map<String, String> metadata = new HashMap<String, String>();
metadata.put("hasAttachment", "true");
metadata.put("attachmentUrl", "https://contoso.com/files/attachment.docx");

SendChatMessageOptions sendChatMessageOptions = new SendChatMessageOptions()
    .setContent("Please take a look at the attachment")
    .setType(ChatMessageType.TEXT)
    .setSenderDisplayName("Sender Display Name")
    .setMetadata(metadata);

SendChatMessageResult sendChatMessageResult = chatThreadClient.sendMessage(sendChatMessageOptions);
String chatMessageId = sendChatMessageResult.getId();

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

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

chatThreadClient.listMessages().forEach(message -> {
    System.out.printf("Message id is %s.\n", message.getId());
});

listMessages يُرجع أحدث إصدار من الرسالة، بما في ذلك أي تحرير أو حذف حدث للرسالة باستخدام .editMessage() و.deleteMessage(). بالنسبة للرسائل المحذوفة، chatMessage.getDeletedOn() تُرجع الدالة قيمة تُشير إلى وقت وتاريخ حذف تلك الرسالة. بالنسبة للرسائل المُحررة، chatMessage.getEditedOn() تُرجع الدالة تاريخاً ووقتاً يُشيران إلى وقت تحرير تلك الرسالة. الوصول للوقت الأصلي لإنشاء الرسالة باستخدام chatMessage.getCreatedOn()، والذي يمكن استخدامه لترتيب الرسائل.

اقرأ المزيد عن أنواع الرسائل هنا: أنواع الرسائل.

إرسال إيصال بالقراءة

استخدم sendReadReceipt الأسلوب لنشر حدث إيصال بالقراءة إلى مؤشر ترابط الدردشة، نيابة عن مستخدم. chatMessageId هو المُعرف الفريد لرسالة الدردشة التي قُرئت.

String chatMessageId = message.getId();
chatThreadClient.sendReadReceipt(chatMessageId);

قائمة المشاركين في الدردشة

استخدم listParticipants لاسترداد مجموعة مقسمة إلى صفحات تحتوي على المشاركين في مؤشر ترابط الدردشة المُعرف بواسطة chatThreadId.

PagedIterable<ChatParticipant> chatParticipantsResponse = chatThreadClient.listParticipants();
chatParticipantsResponse.forEach(chatParticipant -> {
    System.out.printf("Participant id is %s.\n", ((CommunicationUserIdentifier) chatParticipant.getCommunicationIdentifier()).getId());
});

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

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

استخدم أسلوب addParticipants لإضافة المشاركين إلى مؤشر الترابط.

  • communicationIdentifier، مطلوب، هو CommunicationIdentifier الذي قمت بإنشائه بواسطة CommunicationIdentityClient في رمز وصول المستخدم المميز.
  • displayName، الاختيارية تمثل الاسم المعروض للمشارك في مؤشر الترابط.
  • دالة shareHistoryTime-الاختيارية- تمثل الوقت الذي يشارّك فيه سجل الدردشة مع المشارك. لمشاركة السجلات منذ بداية مؤشر ترابط الدردشة، حدد هذه الخاصية إلى أي تاريخ يوافق وقت إنشاء مؤشر الترابط أو يسبقه. لمشاركة أي سجل سابق من وقت إضافة المشارك، حدده على التاريخ الحالي. لمشاركة المحفوظات الجزئية، اضبطهاواعمل اسماء 50 كلمة على التاريخ المطلوب.
List<ChatParticipant> participants = new ArrayList<ChatParticipant>();

CommunicationUserIdentifier identity3 = new CommunicationUserIdentifier("<USER_3_ID>");
CommunicationUserIdentifier identity4 = new CommunicationUserIdentifier("<USER_4_ID>");

ChatParticipant thirdThreadParticipant = new ChatParticipant()
    .setCommunicationIdentifier(identity3)
    .setDisplayName("Display Name 3");

ChatParticipant fourthThreadParticipant = new ChatParticipant()
    .setCommunicationIdentifier(identity4)
    .setDisplayName("Display Name 4");

participants.add(thirdThreadParticipant);
participants.add(fourthThreadParticipant);

chatThreadClient.addParticipants(participants);

تشغيل التعليمات البرمجية

انتقل إلى الدليل الذي يحتوي على pom.xml الملف وقم بتجميع المشروع باستخدام الأمر التالي mvn .

mvn compile

ثم قم ببناء الحزمة.

mvn package

قم بتشغيل الأمر التالي mvn لتنفيذ التطبيق.

mvn exec:java -Dexec.mainClass="com.communication.quickstart.App" -Dexec.cleanupDaemonThreads=false

التعليمة البرمجية العينة

ابحث عن التعليمات البرمجية النهائية لهذه المقالة في نموذج GitHub إضافة دردشة إلى تطبيقك.

المتطلبات الأساسية

  • إنشاء حساب في Azure باستخدام اشتراك نشط. لمزيد من التفاصيل، راجع إنشاء حساب مجانًا.

  • تثبيت Android Studio، نستخدم Android Studio لإنشاء تطبيق Android وتثبيت التبعيات.

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

  • إنشاء اثنين من مستخدمي خدمات الاتصال وإصدار رمز مميز لوصول المستخدم لهم. تأكد من تعيين النطاق للدردشة، ولاحظ سلسلة الرمز المميز وسلسلة user_id. في هذه المقالة، نقوم بإنشاء مؤشر ترابط مع مشارك أولي ثم نضيف مشاركا ثانيا إلى مؤشر الترابط. يمكنك أيضا استخدام Azure CLI وتشغيل الأمر التالي مع سلسلة الاتصال لإنشاء مستخدم ورمز مميز للوصول.

    az communication identity token issue --scope chat --connection-string "yourConnectionString"

    للحصول على التفاصيل، راجع استخدام Azure CLI لإنشاء الرموز المميزة للوصول وإدارتها.

الإعداد

إنشاء تطبيق Android جديد

  1. افتح Android Studio وحدد Create a new project.
  2. في الإطار التالي، حدد Empty Views Activity كقالب المشروع.
  3. عند اختيار الخيارات، أدخل ChatQuickstart كاسم المشروع.
  4. يستخدم هذا النموذج Java كلغة
  5. انقر فوق التالي واختر الدليل حيث تريد إنشاء المشروع.

تثبيت المكتبات

نستخدم Gradle لتثبيت تبعيات Communication Services الضرورية. من سطر الأوامر، انتقل داخل الدليل الجذر للمشروع ChatQuickstart. افتح ملف build.gradle الخاص بالتطبيق وأضف التبعيات التالية إلى الهدف ChatQuickstart:

implementation libs.azure.communication.common
implementation libs.azure.communication.chat
implementation libs.slf4j.log4j12

للحصول على أحدث أرقام الإصدار، راجع https://search.maven.org/artifact/com.azure.android/azure-communication-common و https://search.maven.org/artifact/com.azure.android/azure-communication-chat.

استبعاد ملفات التعريف في خيارات التعبئة والتغليف في build.gradle الجذر

android {
   ...
    packagingOptions {
        exclude 'META-INF/DEPENDENCIES'
        exclude 'META-INF/LICENSE'
        exclude 'META-INF/license'
        exclude 'META-INF/NOTICE'
        exclude 'META-INF/notice'
        exclude 'META-INF/ASL2.0'
        exclude("META-INF/*.md")
        exclude("META-INF/*.txt")
        exclude("META-INF/*.kotlin_module")
    }
}

(بديل) لتثبيت المكتبات من خلال Maven

لاستيراد المكتبة إلى مشروعك باستخدام نظام إصدار Maven، أضفها إلى ملف dependencies قسم التطبيق لديك pom.xmlمع تحديد معرف البيانات الاصطناعية والإصدار الذي ترغب في استخدامه:

<dependency>
  <groupId>com.azure.android</groupId>
  <artifactId>azure-communication-chat</artifactId>
  <version><!-- Please refer to https://search.maven.org/artifact/com.azure.android/azure-communication-chat for the latest version --></version>
</dependency>

إعداد Azure Function

للحصول على التفاصيل، راجع تكامل Azure Function. نوصي بالتكامل مع Azure Function لتجنب معلمات التطبيق ذات الترميز الثابت.

إعداد ثوابت التطبيق

إنشاء فئة ApplicationConstants تخزن جميع ثوابت التطبيق:

public class ApplicationConstants {
    public static final String SDK_VERSION = "<your_version>";
    public final static String SDK_NAME = "azure-communication-com.azure.android.communication.chat";
    public final static String APPLICATION_ID = "Chat_Test_App";
    public final static String TAG = "[Chat Test App]";
    public static CommunicationTokenCredential COMMUNICATION_TOKEN_CREDENTIAL;
}

إعداد العناصر النائبة

افتح الملف واحرره MainActivity.java. في هذه المقالة، نضيف التعليمات البرمجية الخاصة بنا إلى MainActivity، ونعرض الإخراج في وحدة التحكم. لا تتناول هذه المقالة إنشاء واجهة مستخدم. في أعلى الملف، قم باستيراد Azure Communication CommonAzure Communication Chatمكتبات النظام الأخرى و و:

import com.azure.android.communication.chat.*;
import com.azure.android.communication.chat.models.*;
import com.azure.android.communication.common.*;

import android.os.Bundle;
import android.util.Log;
import android.widget.Toast;

import com.jakewharton.threetenabp.AndroidThreeTen;

import java.util.ArrayList;
import java.util.List;

انسخ التعليمة البرمجية التالية إلى الفئة MainActivity في الملف MainActivity.java:

    private ChatAsyncClient chatAsyncClient;

    private void log(String msg) {
        Toast.makeText(this, msg, Toast.LENGTH_LONG).show();
    }
    
   @Override
    protected void onStart() {
        super.onStart();
        try {
            AndroidThreeTen.init(this);

            // Initialize application parameters if one of the conditions in '### Initialize Application Parameters' are met.

            // <CREATE A CHAT CLIENT>

            // <CREATE A CHAT THREAD>

            // <CREATE A CHAT THREAD CLIENT>

            // <SEND A MESSAGE>
            
            // <RECEIVE CHAT MESSAGES>

            // <ADD A USER>

            // <LIST USERS>

            // <REMOVE A USER>
            
            // <<SEND A TYPING NOTIFICATION>>
            
            // <<SEND A READ RECEIPT>>
               
            // <<LIST READ RECEIPTS>>
        } catch (Exception e){
            System.out.println("Quickstart failed: " + e.getMessage());
        }
    }

تهيئة معلمات التطبيق

إشعار

يجب إضافة التهيئة ApplicationConstants إلى MainActivity.java إذا تم استيفاء أي من الشروط التالية: 1. لم يتم تمكين ميزة الإعلامات المؤقتة. 2. إصدار مكتبة Azure Communication Chat لنظام التشغيل Android هو < 2.0.0. وإلا، فراجع الخطوة 11 في إشعارات دفع Android. راجع نموذج التطبيق لإصدار SDK الذي تستهلكه للرجوع إليه.

ACS_ENDPOINT، FIRST_USER_IDويتم إرجاع و FIRST_USER_ACCESS_TOKEN من استدعاء دالة Azure. لمزيد من المعلومات، راجع تكامل Azure Function. نستخدم الاستجابة من استدعاء Azure Function لتهيئة قائمة المعلمات:

  • ACS_ENDPOINT: نقطة نهاية مورد Communication Services.
  • FIRST_USER_ID و SECOND_USER_ID: معرفات مستخدم Communication Services صالحة تم إنشاؤها بواسطة مورد Communication Services.
  • FIRST_USER_ACCESS_TOKEN: الرمز المميز للوصول إلى Communication Services ل <FIRST_USER_ID>.

كتلة التعليمات البرمجية لتهيئة معلمات التطبيق عن طريق استدعاء Azure Function:

try {
        UserTokenClient userTokenClient = new UserTokenClient(AZURE_FUNCTION_URL);
        //First user context
        userTokenClient.getNewUserContext();
        ACS_ENDPOINT = userTokenClient.getACSEndpoint();
        FIRST_USER_ID = userTokenClient.getUserId();
        FIRST_USER_ACCESS_TOKEN = userTokenClient.getUserToken();
        COMMUNICATION_TOKEN_CREDENTIAL = new CommunicationTokenCredential(FIRST_USER_ACCESS_TOKEN);
        //Second user context
        userTokenClient.getNewUserContext();
        SECOND_USER_ID = userTokenClient.getUserId();
    } catch (Throwable throwable) {
        //Your handling code
        logger.logThrowableAsError(throwable);
    }

إنشاء عميل دردشة

استبدل التعليق <CREATE A CHAT CLIENT> بالتعليمة البرمجية التالية (ضع عبارات الاستيراد أعلى الملف):

import com.azure.android.core.http.policy.UserAgentPolicy;

chatAsyncClient = new ChatClientBuilder()
    .endpoint(endpoint)
    .credential(new CommunicationTokenCredential(firstUserAccessToken))
    .addPolicy(new UserAgentPolicy(APPLICATION_ID, SDK_NAME, sdkVersion))
    .buildAsyncClient();

نموذج الكائن

تعالج الفئات والواجهات التالية بعض الميزات الرئيسية لـ Azure Communication Services Chat SDK لـ JavaScript.

Name ‏‏الوصف
ChatClient/ChatAsyncClient هذه الفئة مطلوبة لوظيفة الدردشة. يمكنك إنشاء مثيل لها بمعلومات اشتراكك واستخدامها لإنشاء مؤشرات الترابط والحصول عليها وحذفها والاشتراك في أحداث الدردشة.
ChatThreadClient/ChatThreadAsyncClient هذه الفئة مطلوبة لوظيفة مؤشر ترابط الدردشة. يمكنك الحصول على مثيل عبر ChatClient، واستخدامه في إرسال الرسائل/استقبالها/تحديثها/حذفها، وإضافة المستخدمين/حذفهم/الحصول عليهم، وإرسال إشعارات الكتابة وإعلامات بالقراءة.

بدء تشغيل مؤشر ترابط الدردشة

استخدمنا ChatAsyncClient لإنشاء مؤشر ترابط جديد مع مستخدم أولي.

استبدل التعليق <CREATE A CHAT THREAD> بالتعليمة البرمجية التالية:

// A list of ChatParticipant to start the thread with.
List<ChatParticipant> participants = new ArrayList<>();
// The display name for the thread participant.
String displayName = "initial participant";
participants.add(new ChatParticipant()
    .setCommunicationIdentifier(new CommunicationUserIdentifier(firstUserId))
    .setDisplayName(displayName));

// The topic for the thread.
final String topic = "General";
// Optional, set a repeat request ID.
final String repeatabilityRequestID = "";
// Options to pass to the create method.
CreateChatThreadOptions createChatThreadOptions = new CreateChatThreadOptions()
    .setTopic(topic)
    .setParticipants(participants)
    .setIdempotencyToken(repeatabilityRequestID);

CreateChatThreadResult createChatThreadResult =
    chatAsyncClient.createChatThread(createChatThreadOptions).get();
ChatThreadProperties chatThreadProperties = createChatThreadResult.getChatThreadProperties();
threadId = chatThreadProperties.getId();

الحصول على عميل مؤشر ترابط الدردشة

الآن بعد أن أنشأنا مؤشر ترابط دردشة، نحتاج إلى الحصول على ChatThreadAsyncClient لتنفيذ العمليات داخل مؤشر الترابط. استبدل التعليق <CREATE A CHAT THREAD CLIENT> بالتعليمة البرمجية التالية:

ChatThreadAsyncClient chatThreadAsyncClient = new ChatThreadClientBuilder()
    .endpoint(endpoint)
    .credential(new CommunicationTokenCredential(firstUserAccessToken))
    .addPolicy(new UserAgentPolicy(APPLICATION_ID, SDK_NAME, sdkVersion))
    .chatThreadId(threadId)
    .buildAsyncClient();

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

إرسال رسالة إلى مؤشر ترابط الدردشة الآن.

استبدل التعليق <SEND A MESSAGE> بالتعليمة البرمجية التالية:

// The chat message content, required.
final String content = "Please take a look at the attachment";

// The display name of the sender, if null (i.e. not specified), an empty name will be set.
final String senderDisplayName = "An important person";

// Use metadata optionally to include any additional data you want to send along with the message.
// This field provides a mechanism for developers to extend chat message functionality and add
// custom information for your use case. For example, when sharing a file link in the message, you
// might want to add 'hasAttachment:true' in metadata so that recipient's application can parse
// that and display accordingly.
final Map<String, String> metadata = new HashMap<String, String>();
metadata.put("hasAttachment", "true");
metadata.put("attachmentUrl", "https://contoso.com/files/attachment.docx");

SendChatMessageOptions chatMessageOptions = new SendChatMessageOptions()
    .setType(ChatMessageType.TEXT)
    .setContent(content)
    .setSenderDisplayName(senderDisplayName)
    .setMetadata(metadata);

// A string is the response returned from sending a message, it is an id, which is the unique ID
// of the message.
chatMessageId = chatThreadAsyncClient.sendMessage(chatMessageOptions).get().getId();

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

الإخطارات في الوقت الحقيقي

مع الإشارة في الوقت الحقيقي، يمكنك الاشتراك في الرسائل الواردة الجديدة وتحديث الرسائل الحالية في الذاكرة وفقاً لذلك. تدعم خدمة Azure Communication Services قائمة بالأحداث التي يمكنك الاشتراك فيها.

استبدل التعليق <RECEIVE CHAT MESSAGES> بالتعليمة البرمجية التالية (ضع عبارات الاستيراد أعلى الملف):


// Start real time notification
chatAsyncClient.startRealtimeNotifications(firstUserAccessToken, getApplicationContext());

// Register a listener for chatMessageReceived event
chatAsyncClient.addEventHandler(ChatEventType.CHAT_MESSAGE_RECEIVED, (ChatEvent payload) -> {
    ChatMessageReceivedEvent chatMessageReceivedEvent = (ChatMessageReceivedEvent) payload;
    // You code to handle chatMessageReceived event
    
});

هام

المشكلة المعروفة: عند استخدام Android Chat و Calling SDK معا في نفس التطبيق، لا تعمل ميزة إعلامات Chat SDK في الوقت الفعلي. قد تحصل على مشكلة حل التبعية. يمكنك إيقاف تشغيل ميزة الإعلامات في الوقت الحقيقي عن طريق إضافة معلومات التبعية التالية في ملف التطبيق build.gradle والاستقصاء بدلا من ذلك عن واجهة برمجة تطبيقات GetMessages لعرض الرسائل الواردة للمستخدمين.

implementation ("com.azure.android:azure-communication-chat:1.0.0") {
    exclude group: 'com.microsoft', module: 'trouter-client-android'
}
implementation 'com.azure.android:azure-communication-calling:1.0.0'

لاحظ مع هذا التحديث، إذا حاول التطبيق الاتصال بواجهة برمجة تطبيقات الإعلام باستخدام chatAsyncClient.startRealtimeNotifications() أو chatAsyncClient.addEventHandler()، فإنه ينشئ خطأ وقت التشغيل.

الإعلامات

لمزيد من المعلومات، راجع إعلامات الدفع في Android.

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

استبدل التعليق <ADD A USER> بالتعليمة البرمجية التالية:

// The display name for the thread participant.
String secondUserDisplayName = "a new participant";
ChatParticipant participant = new ChatParticipant()
    .setCommunicationIdentifier(new CommunicationUserIdentifier(secondUserId))
    .setDisplayName(secondUserDisplayName);
        
chatThreadAsyncClient.addParticipant(participant);

سرد المستخدمين في مؤشر ترابط

استبدل التعليق <LIST USERS> بالتعليمة البرمجية التالية (ضع عبارات الاستيراد أعلى الملف):

import com.azure.android.core.rest.util.paging.PagedAsyncStream;
import com.azure.android.core.util.RequestContext;

// The maximum number of participants to be returned per page, optional.
int maxPageSize = 10;

// Skips participants up to a specified position in response.
int skip = 0;

// Options to pass to the list method.
ListParticipantsOptions listParticipantsOptions = new ListParticipantsOptions()
    .setMaxPageSize(maxPageSize)
    .setSkip(skip);

PagedAsyncStream<ChatParticipant> participantsPagedAsyncStream =
      chatThreadAsyncClient.listParticipants(listParticipantsOptions, RequestContext.NONE);

participantsPagedAsyncStream.forEach(chatParticipant -> {
    // You code to handle participant
});

حذف مستخدم من مؤشر ترابط الدردشة

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

استبدل التعليق <REMOVE A USER> بالتعليمة البرمجية التالية:

// Using the unique ID of the participant.
chatThreadAsyncClient.removeParticipant(new CommunicationUserIdentifier(secondUserId)).get();

إرسال إعلام بالكتابة

استبدل التعليق <SEND A TYPING NOTIFICATION> بالتعليمة البرمجية التالية:

chatThreadAsyncClient.sendTypingNotification().get();

إرسال إيصال القراءة

نرسل إيصال قراءة للرسالة المرسلة مسبقا.

استبدل التعليق <SEND A READ RECEIPT> بالتعليمة البرمجية التالية:

chatThreadAsyncClient.sendReadReceipt(chatMessageId).get();

قائمة إيصالات القراءة

استبدل التعليق <READ RECEIPTS> بالتعليمة البرمجية التالية:

// The maximum number of participants to be returned per page, optional.
maxPageSize = 10;
// Skips participants up to a specified position in response.
skip = 0;
// Options to pass to the list method.
ListReadReceiptOptions listReadReceiptOptions = new ListReadReceiptOptions()
    .setMaxPageSize(maxPageSize)
    .setSkip(skip);

PagedAsyncStream<ChatMessageReadReceipt> readReceiptsPagedAsyncStream =
      chatThreadAsyncClient.listReadReceipts(listReadReceiptOptions, RequestContext.NONE);

readReceiptsPagedAsyncStream.forEach(readReceipt -> {
    // You code to handle readReceipt
});

تشغيل التعليمات البرمجية

في Android Studio، اضغط على زر "Run" لإنشاء وتشغيل المشروع. في وحدة التحكم، يمكنك عرض الإخراج من التعليمة البرمجية وإخراج المسجل من ChatClient.

التعليمة البرمجية العينة

ابحث عن التعليمات البرمجية النهائية لهذه المقالة في نموذج GitHub إضافة دردشة إلى تطبيقك.

المتطلبات الأساسية

الإعداد

إنشاء تطبيق C# جديد

في نافذة وحدة تحكم (مثل cmd أو PowerShell أو Bash)، استخدم الأمر ⁧dotnet new⁩ لإنشاء تطبيق وحدة تحكم جديد بالاسم ⁧ChatQuickstart⁩. هذا الأمر ينشئ مشروع "مرحباً بالعالم" بسيطاً بلغة #C باستخدام ملف مصدر واحد: Program.cs.

dotnet new console -o ChatQuickstart

قم بتغيير الدليل الخاص بك إلى مجلد التطبيق الذي تم إنشاؤه حديثًا، واستخدم الأمر dotnet build للتحويل البرمجي لتطبيقك.

cd ChatQuickstart
dotnet build

تثبيت الحزمة

تثبيت Azure Communication Chat SDK لـ .NET

dotnet add package Azure.Communication.Chat

نموذج الكائن

تُعالج الفئات التالية بعض الميزات الرئيسية Azure Communication Services Chat SDK لـ C#‎.

Name ‏‏الوصف
ChatClient هذه الفئة مطلوبة لوظيفة الدردشة. إنشاء مثيل مع معلومات اشتراك، واستخدامه لإنشاء مؤشرات الترابط والحصول عليها وحذفها.
ChatThreadClient هذه الفئة مطلوبة لوظيفة مؤشر ترابط الدردشة. يمكنك الحصول على مثيل عبر ChatClient، واستخدامه في إرسال/استقبال/تحديث/حذف الرسائل، وإضافة/حذف/الحصول على المُشاركين، وإرسال إشعارات الكتابة وإعلامات بالقراءة.

إنشاء عميل دردشة

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

تعرف على المزيد حول الرموز المميزة لوصول المستخدم.

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

انسخ قصاصات التعليمات البرمجية التالية والصقها في Program.cs الملف المصدر.

using Azure;
using Azure.Communication;
using Azure.Communication.Chat;
using System;

namespace ChatQuickstart
{
    class Program
    {
        static async System.Threading.Tasks.Task Main(string[] args)
        {
            // Your unique Azure Communication service endpoint
            Uri endpoint = new Uri("<replace with your resource endpoint>");

            CommunicationTokenCredential communicationTokenCredential = new CommunicationTokenCredential(<Access_Token>);
            ChatClient chatClient = new ChatClient(endpoint, communicationTokenCredential);
        }
    }
}

بدء تشغيل مؤشر ترابط الدردشة

استخدام createChatThread الأسلوب على chatClient لإنشاء مؤشر ترابط محادثة

  • استخدم topic لإعطاء موضوع لهذه الدردشة. يمكنك تحديث الموضوع بعد إنشاء مؤشر ترابط الدردشة باستخدام الدالة UpdateTopic .
  • استخدم participants خاصية لتمرير قائمة من ChatParticipant الكائنات لإضافتها إلى مؤشر ترابط الدردشة. ChatParticipantتهيئة الكائن مع CommunicationIdentifier كائن. CommunicationIdentifier يمكن أن يكون من نوع CommunicationUserIdentifierأو MicrosoftTeamsUserIdentifierأو PhoneNumberIdentifier. على سبيل المثال، للحصول على كائن CommunicationIdentifier ، تحتاج إلى تمرير معرف Access الذي قمت بإنشائه باتباع الإرشادات لإنشاء مستخدم

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

var chatParticipant = new ChatParticipant(identifier: new CommunicationUserIdentifier(id: "<Access_ID>"))
{
    DisplayName = "UserDisplayName"
};
CreateChatThreadResult createChatThreadResult = await chatClient.CreateChatThreadAsync(topic: "Hello world!", participants: new[] { chatParticipant });
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: createChatThreadResult.ChatThread.Id);
string threadId = chatThreadClient.Id;

الحصول على عميل مؤشر ترابط الدردشة

يُرجع GetChatThreadClient الأسلوب عميل مؤشر الترابط لمؤشر الترابط الموجود مسبقاً. يمكنك استخدامه لتنفيذ العمليات على مؤشر الترابط الذي تم إنشاؤه: إضافة أعضاء وإرسال رسالة وما إلى ذلك. threadId هو المُعرف الفريد لمؤشر ترابط الدردشة الموجود.

string threadId = "<THREAD_ID>";
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: threadId);

سرد جميع مؤشرات ترابط الدردشة

استخدم GetChatThreads لاسترداد جميع مؤشرات ترابط الدردشة التي يكون المستخدم جزءاً منها.

AsyncPageable<ChatThreadItem> chatThreadItems = chatClient.GetChatThreadsAsync();
await foreach (ChatThreadItem chatThreadItem in chatThreadItems)
{
    Console.WriteLine($"{ chatThreadItem.Id}");
}

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

استخدم SendMessage لإرسال رسالة إلى مؤشر الترابط.

  • استخدم content لتوفير محتوى الرسالة. مطلوب.
  • استخدم type لنوع محتوى الرسالة مثل "نص" أو "Html". إذا لم يتم تحديده، يتم تعيين "نص".
  • استخدم senderDisplayName لتحديد اسم العرض للمرسل. إذا لم يتم تحديدها، يتم تعيين سلسلة فارغة.
  • اختياري: استخدم metadata لتضمين البيانات الأخرى التي تريد إرسالها مع الرسالة. يوفر هذا الحقل آلية للمطورين لتوسيع وظائف رسالة الدردشة وإضافة معلومات مُخصصة لحالة الاستخدام. على سبيل المثال، عند مشاركة رابط ملف في الرسالة، قد تحتاج إلى إضافة "hasAttachment:true" في بيانات التعريف حتى يمكن لتطبيق المستلم تحليل ذلك وعرضه وفقاً لذلك.
SendChatMessageOptions sendChatMessageOptions = new SendChatMessageOptions()
{
    Content = "Please take a look at the attachment",
    MessageType = ChatMessageType.Text
};
sendChatMessageOptions.Metadata["hasAttachment"] = "true";
sendChatMessageOptions.Metadata["attachmentUrl"] = "https://contoso.com/files/attachment.docx";

SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(sendChatMessageOptions);

string messageId = sendChatMessageResult.Id;

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

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

AsyncPageable<ChatMessage> allMessages = chatThreadClient.GetMessagesAsync();
await foreach (ChatMessage message in allMessages)
{
    Console.WriteLine($"{message.Id}:{message.Content.Message}");
}

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

GetMessages يُرجع أحدث إصدار من الرسالة، بما في ذلك أي تحرير أو حذف حدث للرسالة باستخدام UpdateMessage وDeleteMessage. بالنسبة للرسائل المحذوفة، chatMessage.DeletedOn تُرجع الدالة قيمة تُشير إلى وقت وتاريخ حذف تلك الرسالة. بالنسبة للرسائل المُحررة، chatMessage.EditedOn تُرجع الدالة تاريخاً ووقتاً يُشيران إلى وقت تحرير تلك الرسالة. الوصول للوقت الأصلي لإنشاء الرسالة باستخدام chatMessage.CreatedOn، والذي يمكن استخدامه لترتيب الرسائل.

GetMessages إرجاع أنواع مختلفة من الرسائل. يمكنك تحديد النوع من chatMessage.Type. الأنواع هي:

  • Text: رسالة الدردشة العادية المُرسلة من قِبل عضو مؤشر ترابط.

  • Html: رسالة نصية مُنسقة. لا يمكن لمستخدمي Communication Services حاليا إرسال رسائل RichText. نوع الرسالة هذا مدعوم للرسائل المرسلة من مستخدمي Teams إلى مستخدمي Communication Services في سيناريوهات Teams Interop.

  • TopicUpdated: رسالة النظام التي تشير إلى تحديث الموضوع. (للقراءة فقط)

  • ParticipantAdded: رسالة النظام التي تشير إلى إضافة مشارك واحد أو أكثر إلى مؤشر ترابط الدردشة (للقراءة فقط).

  • ParticipantRemoved: رسالة النظام التي تشير إلى إزالة مشارك من مؤشر ترابط الدردشة.

لمزيد من المعلومات، راجع أنواع الرسائل.

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

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

استخدم AddParticipants لإضافة مشارك واحد أو أكثر إلى مؤشر ترابط الدردشة. فيما يلي السمات المدعومة لكل مشارك في مؤشر الترابط:

  • communicationUser، مطلوب، هو هوية المشارك في مؤشر الترابط.
  • displayName، الاختيارية تمثل الاسم المعروض للمشارك في مؤشر الترابط.
  • shareHistoryTime، الاختيارية تمثل الوقت الذي يحدث فيه مشاركة محفوظات الدردشة مع المشارك.
var josh = new CommunicationUserIdentifier(id: "<Access_ID_For_Josh>");
var gloria = new CommunicationUserIdentifier(id: "<Access_ID_For_Gloria>");
var amy = new CommunicationUserIdentifier(id: "<Access_ID_For_Amy>");

var participants = new[]
{
    new ChatParticipant(josh) { DisplayName = "Josh" },
    new ChatParticipant(gloria) { DisplayName = "Gloria" },
    new ChatParticipant(amy) { DisplayName = "Amy" }
};

await chatThreadClient.AddParticipantsAsync(participants: participants);

الحصول على المشاركين في مؤشر الترابط

استخدم GetParticipants لاسترداد المشاركين في مؤشر ترابط الدردشة.

AsyncPageable<ChatParticipant> allParticipants = chatThreadClient.GetParticipantsAsync();
await foreach (ChatParticipant participant in allParticipants)
{
    Console.WriteLine($"{((CommunicationUserIdentifier)participant.User).Id}:{participant.DisplayName}:{participant.ShareHistoryTime}");
}

إرسال إيصال بالقراءة

يتم استخدامها SendReadReceipt لإعلام المشاركين الآخرين بقراءة المستخدم للرسالة.

await chatThreadClient.SendReadReceiptAsync(messageId: messageId);

تشغيل التعليمات البرمجية

شغّل التطبيق من دليل تطبيقك باستخدام الأمر dotnet run.

dotnet run

نموذج التعليمات البرمجية

ابحث عن التعليمات البرمجية النهائية لهذه المقالة في نموذج GitHub إضافة دردشة إلى تطبيقك.

المتطلبات الأساسية

  • إنشاء حساب في Azure باستخدام اشتراك نشط. لمزيد من التفاصيل، راجع إنشاء حساب مجانًا.

  • تثبيت Xcode وCococoPods. يمكنك استخدام Xcode لإنشاء تطبيق iOS لهذه المقالة، وCococoPods لتثبيت التبعيات.

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

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

    az communication identity token issue --scope chat --connection-string "yourConnectionString"

    للحصول على التفاصيل، راجع استخدام Azure CLI لإنشاء الرموز المميزة للوصول وإدارتها.

الإعداد

إنشاء تطبيق تشغيل iOS جديد

افتح "إكس كود" وحدد "إنشاء مشروع إكس كود جديد". ثم حدد iOS كمنصة والتطبيق للقالب.

بالنسبة إلى اسم المشروع، أدخل ChatQuickstart. ثم حدد Storyboard كواجهة ، و Swift كلغة

حدد التالي، واختر الدليل الذي تريد إنشاء المشروع فيه.

تثبيت المكتبات

استخدم CocoaPods لتثبيت تبعيات خدمات الاتصال الضرورية.

من سطر الأوامر، انتقل داخل الدليل ChatQuickstart الجذر لمشروع iOS. إنشاء Podfile باستخدام الأمر التالي: pod init.

افتح Podfile، وأضف التبعيات التالية إلى ChatQuickstart الهدف:

pod 'AzureCommunicationChat', '~> 1.3.6'

قم بتثبيت التبعيات باستخدام الأمر التالي: pod install. يؤدي هذا أيضا إلى إنشاء مساحة عمل Xcode.

بعد تشغيل pod install، أعد فتح المشروع في Xcode عن طريق تحديد ..xcworkspace

إعداد العناصر النائبة

افتح مساحة ChatQuickstart.xcworkspace العمل في Xcode، ثم افتح ViewController.swift.

في هذه المقالة، يمكنك إضافة التعليمات البرمجية الخاصة بك إلى viewController، وعرض الإخراج في وحدة تحكم Xcode. لا تتناول هذه المقالة إنشاء واجهة مستخدم في iOS.

في الجزء العلوي من viewController.swift، قم باستيراد AzureCommunication المكتبات و AzureCommunicationChat :

import AzureCommunicationCommon
import AzureCommunicationChat

انسخ التعليمات البرمجية التالية في viewDidLoad() أسلوب ViewController:

override func viewDidLoad() {
        super.viewDidLoad()
        // Do any additional setup after loading the view.

        let semaphore = DispatchSemaphore(value: 0)
        DispatchQueue.global(qos: .background).async {
            do {
                // <CREATE A CHAT CLIENT>
                
                // <CREATE A CHAT THREAD>

                // <LIST ALL CHAT THREADS>

                // <GET A CHAT THREAD CLIENT>

                // <SEND A MESSAGE>

                // <SEND A READ RECEIPT >

                // <RECEIVE MESSAGES>

                // <ADD A USER>
                
                // <LIST USERS>
            } catch {
                print("Quickstart failed: \(error.localizedDescription)")
            }
        }
    }

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

إنشاء عميل دردشة

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

تعرف على المزيد حول الرموز المميزة لوصول المستخدم.

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

استبدل التعليق <CREATE A CHAT CLIENT> بمقتطف التعليمات البرمجية التالي:

let endpoint = "<ACS_RESOURCE_ENDPOINT>"
let credential =
try CommunicationTokenCredential(
    token: "<ACCESS_TOKEN>"
)
let options = AzureCommunicationChatClientOptions()

let chatClient = try ChatClient(
    endpoint: endpoint,
    credential: credential,
    withOptions: options
)

استبدل <ACS_RESOURCE_ENDPOINT> بنقطة نهاية مورد Azure Communication Services. استبدل <ACCESS_TOKEN> برمز مميز صالح للوصول إلى Communication Services.

نموذج الكائن

تُعالج الفئات والواجهات التالية بعض الميزات الرئيسية في Azure Communication Services Chat SDK لـ iOS.

Name ‏‏الوصف
ChatClient هذه الفئة مطلوبة لوظيفة الدردشة. يمكنك إنشاء مثيل لها بمعلومات اشتراكك واستخدامها لإنشاء مؤشرات الترابط والحصول عليها وحذفها والاشتراك في أحداث الدردشة.
ChatThreadClient هذه الفئة مطلوبة لوظيفة مؤشر ترابط الدردشة. يمكنك الحصول على مثيل عبر ChatClient، واستخدامه لإرسال الرسائل وتلقيها وتحديثها وحذفها. يمكنك أيضًا استخدامه لإضافة مستخدمين وإزالتهم والحصول عليهم، وإرسال إشعارات الكتابة وقراءة الإيصالات.

بدء تشغيل مؤشر ترابط الدردشة

CreateChatThreadResult هي الاستجابة التي أُرجعت من إنشاء مؤشر ترابط الدردشة. إنه يحتوي على خاصية chatThread وهو الكائن ChatThreadProperties. يحتوي هذا الكائن على threadId الذي يمكن استخدامه للحصول على ChatThreadClient لتنفيذ العمليات على السلسلة التي تم إنشاؤها: إضافة مشاركين، وإرسال رسالة، وما إلى ذلك.

استبدل التعليق <CREATE A CHAT THREAD> بمقتطف التعليمات البرمجية التالي:

let request = CreateChatThreadRequest(
    topic: "Quickstart",
    participants: [
        ChatParticipant(
            id: CommunicationUserIdentifier("<USER_ID>"),
            displayName: "Jack"
        )
    ]
)

var threadId: String?
chatClient.create(thread: request) { result, _ in
    switch result {
    case let .success(result):
        threadId = result.chatThread?.id

    case .failure:
        fatalError("Failed to create thread.")
    }
    semaphore.signal()
}
semaphore.wait()

استبدل <USER_ID> بمعرف مستخدم Communication Services صالح.

تستخدم أنت إشارة هنا؛ لانتظار معالج الاكتمال قبل المتابعة. في الخطوات اللاحقة threadId ، استخدم من الاستجابة التي تم إرجاعها إلى معالج الإكمال.

سرد جميع مؤشرات ترابط الدردشة

بعد إنشاء مؤشر ترابط دردشة، يمكننا سرد جميع مؤشرات ترابط الدردشة عن طريق استدعاء listChatThreads الأسلوب على ChatClient. استبدل التعليق <LIST ALL CHAT THREADS> بالتعليمة البرمجية التالية:

chatClient.listThreads { result, _ in
    switch result {
    case let .success(threads):
        guard let chatThreadItems = threads.pageItems else {
            print("No threads returned.")
            return
        }

        for chatThreadItem in chatThreadItems {
            print("Thread id: \(chatThreadItem.id)")
        }
    case .failure:
        print("Failed to list threads")
    }
    semaphore.signal()
}
semaphore.wait()

الحصول على عميل مؤشر ترابط الدردشة

يقوم createClient الأسلوب بإرجاع ChatThreadClient لسلسلة رسائل موجودة بالفعل. ويمكن استخدامه لتنفيذ العمليات على مؤشر الترابط المنشأ، مثل: إضافة المشاركين، إرسال رسالة، وما إلى ذلك. وتمثل الدالة «threadId» المعرف الفريد لمؤشر ترابط الدردشة الموجود.

استبدل التعليق <GET A CHAT THREAD CLIENT> بالتعليمة البرمجية التالية:

let chatThreadClient = try chatClient.createClient(forThread: threadId!)

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

استخدم الأسلوب ⁧send⁩ لإرسال رسالة إلى مؤشر ترابط مُعرّف في الدالة «threadId».

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

  • استخدم content لتوفير محتوى رسالة الدردشة
  • استخدم senderDisplayName لتحديد اسم العرض للمرسل
  • استخدم الدالة type لتحديد نوع الرسالة، مثل "نص" أو "html"
  • استخدم metadata اختياريا لتضمين أي بيانات أخرى تريد إرسالها مع الرسالة. يوفر هذا الحقل آلية للمطورين لتوسيع وظائف رسالة الدردشة وإضافة معلومات مُخصصة لحالة الاستخدام. على سبيل المثال، عند مشاركة رابط ملف في الرسالة، قد تحتاج إلى إضافة "hasAttachment:true" في بيانات التعريف حتى يمكن لتطبيق المستلم تحليل ذلك وعرضه وفقاً لذلك.

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

استبدل التعليق <SEND A MESSAGE> بمقتطف التعليمات البرمجية التالي:

let message = SendChatMessageRequest(
                        content: "Hello!",
                        senderDisplayName: "Jack",
                        type: .text,
                        metadata: [
                            "hasAttachment": "true",
                            "attachmentUrl": "https://contoso.com/files/attachment.docx"
                        ]
                    )

var messageId: String?

chatThreadClient.send(message: message) { result, _ in
    switch result {
    case let .success(result):
        print("Message sent, message id: \(result.id)")
        messageId = result.id
    case .failure:
        print("Failed to send message")
    }
    semaphore.signal()
}
semaphore.wait()

إرسال إيصال القراءة

استخدم sendReadReceipt الأسلوب لنشر حدث إيصال بالقراءة إلى مؤشر ترابط الدردشة، نيابة عن مستخدم. messageId هو المُعرف الفريد لرسالة الدردشة التي قُرئت.

استبدل التعليق <SEND A READ RECEIPT> بالتعليمة البرمجية التالية:

if let id = messageId {
    chatThreadClient.sendReadReceipt(forMessage: id) { result, _ in
        switch result {
        case .success:
            print("Read receipt sent")
        case .failure:
            print("Failed to send read receipt")
        }
        semaphore.signal()
    }
    semaphore.wait()
} else {
    print("Cannot send read receipt without a message id")
}

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

الآن، يمكنك الاشتراك للاستماع للرسائل الواردة الجديدة وتحديث الرسائل الحالية في الذاكرة وفقًا لذلك. تدعم خدمة Azure Communication Services قائمة بالأحداث التي يمكنك الاشتراك فيها.

استبدل التعليق <RECEIVE MESSAGES> بالتعليمة البرمجية التالية. بعد تمكين الإعلامات، حاول إرسال رسائل جديدة لمشاهدة ChatMessageReceivedEvents.

chatClient.startRealTimeNotifications { result in
    switch result {
    case .success:
        print("Real-time notifications started.")
    case .failure:
        print("Failed to start real-time notifications.")
    }
    semaphore.signal()
}
semaphore.wait()

chatClient.register(event: .chatMessageReceived, handler: { response in
    switch response {
    case let .chatMessageReceivedEvent(event):
        print("Received a message: \(event.message)")
    default:
        return
    }
})

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

chatThreadClient.listMessages { result, _ in
    switch result {
    case let .success(messagesResult):
        guard let messages = messagesResult.pageItems else {
            print("No messages returned.")
            return
        }

        for message in messages {
            print("Received message with id: \(message.id)")
        }

    case .failure:
        print("Failed to receive messages")
    }
    semaphore.signal()
}
semaphore.wait()

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

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

استخدم الأسلوب add لـ ChatThreadClient لإضافة مشارك واحد أو أكثر إلى سلسلة الدردشة. فيما يلي السمات المدعومة لكل مشارك في مؤشر الترابط:

  • id، مطلوب، هو هوية المشارك في مؤشر الترابط.
  • displayName، الاختيارية تمثل الاسم المعروض للمشارك في مؤشر الترابط.
  • shareHistoryTime، الاختيارية تمثل الوقت الذي يحدث فيه مشاركة محفوظات الدردشة مع المشارك.

استبدل التعليق <ADD A USER> بالتعليمة البرمجية التالية:

let user = ChatParticipant(
    id: CommunicationUserIdentifier("<USER_ID>"),
    displayName: "Jane"
)

chatThreadClient.add(participants: [user]) { result, _ in
    switch result {
    case let .success(result):
        if let errors = result.invalidParticipants, !errors.isEmpty {
            print("Error adding participant")
        } else {
            print("Added participant")
        }
    case .failure:
        print("Failed to add the participant")
    }
    semaphore.signal()
}
semaphore.wait()

استبدل <USER_ID> بمعرف مستخدم Communication Services للمستخدم المراد إضافته.

سرد المستخدمين في مؤشر ترابط

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

استبدل التعليق <LIST USERS> بالتعليمة البرمجية التالية:

chatThreadClient.listParticipants { result, _ in
    switch result {
    case let .success(participantsResult):
        guard let participants = participantsResult.pageItems else {
            print("No participants returned.")
            return
        }

        for participant in participants {
            let user = participant.id as! CommunicationUserIdentifier
            print("User with id: \(user.identifier)")
        }
    case .failure:
        print("Failed to list participants")
    }
    semaphore.signal()
}
semaphore.wait()

الإعلامات

تقوم الإعلامات المنبثقة بإعلام العملاء بالرسائل الواردة في مؤشر ترابط الدردشة في الحالات التي لا يعمل فيها تطبيق الأجهزة المحمولة في المقدمة.

حاليا، يتم دعم إرسال إعلامات دفع الدردشة باستخدام Notification Hub ل IOS SDK في الإصدار 1.3.0.

لمزيد من المعلومات، راجع تمكين الإعلام المؤقت في تطبيق الدردشة.

تشغيل التعليمات البرمجية

إيقاف تشغيل بيئة الاختبار المعزولة للبرنامج النصي للمستخدم

تكتب بعض البرامج النصية داخل المكتبات المرتبطة الملفات أثناء عملية الإنشاء. لتمكين كتابة الملفات، قم بتعطيل بيئة الاختبار المعزولة للبرنامج النصي للمستخدم في Xcode.

في مشروع Xcode ، ضمن إعدادات الإنشاء ، قم بتعيين خيار وضع الحماية للبرنامج النصي للمستخدم إلى لا. للعثور على الإعداد، قم بتغيير الفلتر من أساسي إلى الكل أو استخدم شريط البحث.

لقطة شاشة تعرض خيار Build Settings لإيقاف تشغيل بيئة الاختبار المعزولة للبرنامج النصي للمستخدم.

تشغيل المشروع

في Xcode، اضغط على زر "Run" لإنشاء وتشغيل المشروع. في وحدة التحكم، يمكنك عرض الإخراج من التعليمة البرمجية وإخراج المسجل من ChatClient.

التعليمة البرمجية العينة

ابحث عن التعليمات البرمجية النهائية لهذه المقالة في نموذج GitHub إضافة دردشة إلى تطبيقك.

المتطلبات الأساسية

إنشاء المستخدم

أكمل هذه الخطوات في Power Automate مع فتح تدفق Power Automate في وضع التحرير.

لإضافة خطوة جديدة في سير العمل باستخدام موصل Communication Services Identity:

  1. في المصمم، ضمن الخطوة حيث تريد إضافة الإجراء الجديد، حدد خطوة جديدة. بدلا من ذلك، لإضافة الإجراء الجديد بين الخطوات، حرك المؤشر فوق السهم بين هذه الخطوات، وحدد علامة الجمع (+)، ثم حدد إضافة إجراء.

  2. في مربع البحث Choose an operation ، أدخل Communication Services Identity. في قائمة الإجراءات، حدد إنشاء مستخدم.

    لقطة شاشة تعرض إجراء إنشاء مستخدم لموصل هوية Azure Communication Services.

  3. أدخل سلسلة الاتصال. للحصول على عنوان URL سلسلة الاتصال في مدخل Microsoft Azure، انتقل إلى مورد Azure Communication Services. في قائمة الموارد، حدد Keys، ثم حدد Connection string. حدد أيقونة النسخ لنسخ سلسلة الاتصال.

    لقطة شاشة تعرض جزء Keys لمورد Azure Communication Services.

  4. أدخل اسماً للاتصال.

  5. حدد إظهار الخيارات المتقدمة، ثم حدد نطاق الرمز المميز. ينشئ الإجراء رمزا مميزا للوصول ووقت انتهاء صلاحيته مع النطاق المحدد. ينشئ هذا الإجراء أيضا معرف مستخدم هوية مستخدم Communication Services.

    لقطة شاشة تعرض موصل هوية Azure Communication Services إنشاء خيارات إجراء المستخدم.

  6. في عنصر نطاقات الرمز المميز، حدد الدردشة.

    لقطة شاشة تعرض الخيارات المتقدمة لموصل دردشة Azure Communication Services.

  7. حدد إنشاء. يتم عرض معرف المستخدم ورمز الوصول المميز.

إنشاء مؤشر ترابط دردشة

  1. إضافة إجراء جديد

  2. في مربع البحث Choose an operation ، أدخل Communication Services Chat. في قائمة الإجراءات، حدد Create chat thread.

    لقطة شاشة تعرض موصل دردشة Azure Communication Services إنشاء إجراء مؤشر ترابط دردشة.

  3. أدخل عنوان URL لنقطة نهاية Communication Services. للحصول على عنوان URL لنقطة النهاية في مدخل Microsoft Azure، انتقل إلى مورد Azure Communication Services. في قائمة الموارد، حدد Keys، ثم حدد Endpoint.

  4. أدخل اسماً للاتصال.

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

    لقطة شاشة تعرض مربع حوار إجراء إجراء مؤشر ترابط الدردشة في Azure Communication Services Chat.

إرسال رسالة

  1. إضافة إجراء جديد

  2. في مربع البحث Choose an operation ، أدخل Communication Services Chat. في قائمة الإجراءات، حدد إرسال رسالة إلى مؤشر ترابط الدردشة.

    لقطة شاشة تعرض إجراء رسالة إرسال رسالة دردشة لموصل دردشة Azure Communication Services.

  3. أدخل رمز الوصول ومعرف مؤشر الترابط والمحتوى والاسم.

    لقطة شاشة تعرض مربع حوار إجراء رسالة إرسال رسالة الدردشة لموصل Azure Communication Services Chat.

سرد رسائل مؤشر ترابط الدردشة

للتحقق من أنك أرسلت رسالة بشكل صحيح:

  1. إضافة إجراء جديد

  2. في مربع البحث Choose an operation ، أدخل Communication Services Chat. في قائمة الإجراءات، حدد قائمة رسائل مؤشر ترابط الدردشة.

    لقطة شاشة تعرض إجراء رسائل الدردشة في قائمة موصلات Azure Communication Services Chat.

  3. أدخل الرمز المميز للوصول ومعرف مؤشر الترابط.

    لقطة شاشة تعرض مربع حوار إجراء رسائل الدردشة في قائمة موصلات Azure Communication Services Chat.

اختبر تطبيق المنطق الخاص بك

لبدء سير العمل يدويًا، في شريط أدوات المصمم، حدد Run. ينشئ سير العمل مستخدما، ويصدر رمزا مميزا للوصول لهذا المستخدم، ثم يزيل الرمز المميز ويحذف المستخدم. لمزيد من المعلومات، راجع كيفية تشغيل سير العمل.

الآن، حدد سرد رسائل مؤشر ترابط الدردشة. في مخرجات الإجراء، تحقق من الرسالة التي تم إرسالها.

لقطة شاشة تعرض نتائج إجراء رسالة رسالة الدردشة لموصل Azure Communication Services Chat.

تنظيف موارد سير العمل

لتنظيف سير عمل تطبيق المنطق والموارد ذات الصلة، راجع كيفية تنظيف موارد Logic Apps.

تنظيف الموارد

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

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

وصفت هذه المقالة كيفية:

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

جرب تطبيق Chat Hero

  • Last updated on