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

ابدأ باستخدام Azure Communication Services من خلال استخدام Chat SDK من Communication Services لإضافة المكالمات الصوتية والفيديو إلى تطبيقك. في هذا التشغيل السريع، سنستخدم 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> بنقطة النهاية الفعلية.

Windows

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

setx AZURE_COMMUNICATION_ENDPOINT "<yourEndpoint>"

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

ماك

تحرير .zshrc، وإضافة متغير البيئة:

export AZURE_COMMUNICATION_ENDPOINT="<yourEndpoint>"

بعد إضافة متغير البيئة، تشغيل source ~/.zshrc من إطار وحدة التحكم لجعل التغييرات فعالة. في حال قمت بإنشاء متغير البيئة مع فتح IDE الخاص بك قد تحتاج إلى إغلاق وإعادة فتح المحرر أو IDE أو shell للوصول إلى المتغير.

Linux

تحرير .bash_profile، وإضافة متغير البيئة:

export AZURE_COMMUNICATION_ENDPOINT="<yourEndpoint>"

بعد إضافة متغير البيئة، تشغيل source ~/.bash_profile من إطار وحدة التحكم لجعل التغييرات فعالة. في حال قمت بإنشاء متغير البيئة مع فتح IDE الخاص بك قد تحتاج إلى إغلاق وإعادة فتح المحرر أو IDE أو shell للوصول إلى المتغير.

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

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

Windows

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

setx AZURE_COMMUNICATION_ACCESS_TOKEN "<yourAccessToken>"

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

ماك

تحرير .zshrc، وإضافة متغير البيئة:

export AZURE_COMMUNICATION_ACCESS_TOKEN="<yourAccessToken>"

بعد إضافة متغير البيئة، تشغيل source ~/.zshrc من إطار وحدة التحكم لجعل التغييرات فعالة. في حال قمت بإنشاء متغير البيئة مع فتح IDE الخاص بك قد تحتاج إلى إغلاق وإعادة فتح المحرر أو IDE أو shell للوصول إلى المتغير.

Linux

تحرير .bash_profile، وإضافة متغير البيئة:

export AZURE_COMMUNICATION_ACCESS_TOKEN="<yourAccessToken>"

بعد إضافة متغير البيئة، تشغيل source ~/.bash_profile من إطار وحدة التحكم لجعل التغييرات فعالة. في حال قمت بإنشاء متغير البيئة مع فتح IDE الخاص بك قد تحتاج إلى إغلاق وإعادة فتح المحرر أو IDE أو shell للوصول إلى المتغير.

العمليات

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

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 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.

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

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

npm install parcel --save-dev

قم بإنشاء ملف 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="./client.js" type="module"></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 بالرمز المميز الذي أصدرته.

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

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

npx parcel index.html

افتح المستعرض وانتقل إلى http://localhost:1234/. لا بد أن تجد ما يلي في وحدة تحكم المطور «developer tools console» داخل المتصفح:

Azure Communication Chat client created!

نموذج الكائن

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

الاسم	‏‏الوصف
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.

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

قبل البدء، تأكد من:

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

• تثبيت Python 3.7+.

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

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

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

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

الإعداد

إنشاء تطبيق 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.

الاسم	‏‏الوصف
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.

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

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

• Java Development Kit (SDK) الإصدار 8 أو أحدث.

• Apache Maven.

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

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

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

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

الإعداد

إنشاء تطبيق 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

ستلاحظ أن الهدف 'إنشاء' أنشئ دليلاً بنفس اسم artifactId. تحت هذا الدليل، يحتوي src/main/java directory على التعليمات البرمجية المصدر للمشروع، src/test/java الدليل يحتوي على مصدر الاختبار، وملف pom.xml هو طراز الكائن Project للمشروع، أو 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.

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

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

لإنشاء عميل دردشة، استخدم نقطة نهاية Communication Services ورمز الوصول المميز الذي أُنشئ كجزء من خطوات المتطلبات الأساسية. تمكين رموز الوصول المميزة للمستخدمين من إنشاء تطبيقات العميل التي تكون مصادقة مباشرة على 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 الذي قمت بإنشائه بواسطة CommunicationIdentifier في بدء التشغيل السريع رمز الوصول المميز للمستخدم.
• 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 Activity كقالب المشروع.
3. عند اختيار الخيارات، أدخل ChatQuickstart كاسم المشروع.
4. انقر فوق التالي واختر الدليل حيث تريد إنشاء المشروع.

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

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

implementation 'com.azure.android:azure-communication-common:' + $azureCommunicationCommonVersion
implementation 'com.azure.android:azure-communication-chat:' + $azureCommunicationChatVersion
implementation 'org.slf4j:slf4j-log4j12:1.7.29'

يرجى الرجوع إلى 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) {
        Log.i(TAG, 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_ENDPOINTFIRST_USER_ACCESS_TOKEN، FIRST_USER_ID ويتم إرجاعها من استدعاء Azure Function. يرجى التحقق من تكامل Azure Function للحصول على التفاصيل. نستخدم الاستجابة من استدعاء Azure Function لتهيئة قائمة المعلمات:

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

الاسم	‏‏الوصف
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.

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

قبل البدء، تأكد من:

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

• تثبيت Visual Studio

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

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

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

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

الإعداد

إنشاء تطبيق 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#‎.

الاسم	‏‏الوصف
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 يحتاج مثيل العميل إلى الإنشاء باستخدام الأسلوب على GetChatThreadClientChatClient العميل.

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 في سيناريوهات Interop Teams.

• 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 لإنشاء تطبيق تشغيل للبدء السريع وCocoaPods لتثبيت التبعيات.

• أنشئ مورد خدمات اتصالات 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. ثم حدد لوحة العمل كواجهة، وUIKit App Delegate كدورة حياة، وSwift كلغة.

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

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

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

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

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

pod 'AzureCommunicationChat', '~> 1.3.4'

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

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

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

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

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

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

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.

الاسم	‏‏الوصف
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، اضغط على زر "Run" لإنشاء وتشغيل المشروع. في وحدة التحكم يمكنك عرض الإخراج من التعليمات البرمجية وإخراج المسجل من ChatClient.

ملاحظة: تعيين Build Settings > Build Options > Enable Bitcode إلى No. حاليًا، لا يدعم Sdk AzureCommunicationChat في iOS تمكين bitcode، مشكلة GitHub التالية تتعقب ذلك.

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

ابحث عن التعليمات البرمجية النهائية لهذا البداية السريعة في GitHub.

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

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

• مورد خدمات اتصالات Azure نشط، أو قم بإنشاء مورد خدمات الاتصال .

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

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

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

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

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

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

   

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

   

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

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

   

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

   

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

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

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

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

   

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

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

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

   

إرسال رسالة

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

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

   

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

   

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

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

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

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

   

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

   

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

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

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

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

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

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

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

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

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

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

جرب تطبيق Chat Hero

قد ترغب أيضًا بما يلي:

• بدء استخدام مكتبة واجهة المستخدم
• تعرف على مفاهيم الدردشة
• تعرف على Chat SDK
• استخدام Chat SDK في تطبيق React Native .