مصادقة تطبيقات Chat وطلبات البيانات من Google Chat API واعتمادها

المصادقة والتفويض هي آليات تُستخدم لإثبات الهوية والوصول إلى الموارد على التوالي. يوضّح هذا المستند آلية عمل المصادقة والترخيص لتطبيقات Chat وطلبات البيانات من واجهة برمجة التطبيقات.

نظرة عامة على العملية

يوضّح المخطّط التالي الخطوات ذات المستوى العالي للمصادقة والتفويض في Google Chat:

خطوات عالية المستوى لمصادقة Google Chat وتفويضها
الشكل 1. الخطوات ذات المستوى العالي لمصادقة Google Chat وتفويضه:

  1. ضبط مشروع Google Cloud وتفعيل Chat API وضبط تطبيق Chat: أثناء التطوير، عليك إنشاء مشروع على Google Cloud. في مشروع Google Cloud، يمكنك تفعيل Chat API وضبط تطبيق Chat وإعداد المصادقة. لمزيد من المعلومات، يُرجى الاطّلاع على التطوير على Google Workspace وإنشاء تطبيق Chat.

  2. Call Chat API: عندما يستدعي تطبيقك واجهة Chat API، يتم إرسال بيانات اعتماد المصادقة إلى Chat API. إذا تمت مصادقة تطبيقك باستخدام حساب خدمة، سيتم إرسال بيانات الاعتماد كجزء من رمز التطبيق. إذا كان تطبيقك يتطلّب الاتصال بواجهة برمجة تطبيقات Chat باستخدام مصادقة مستخدم لم يتم منحها بعد، سيُطلب من المستخدم تسجيل الدخول.

  3. طلب الموارد: يطلب تطبيقك إذن الوصول باستخدام النطاقات التي تحدّدها أثناء إعداد المصادقة.

  4. طلب الموافقة: إذا تمت مصادقة تطبيقك كمستخدم، ستعرض Google شاشة موافقة OAuth حتى يتمكّن المستخدم من تحديد ما إذا كان سيمنح تطبيقك إذن الوصول إلى البيانات المطلوبة. لا تتطلب المصادقة باستخدام حساب خدمة موافقة المستخدم.

  5. إرسال طلب الموافَق عليه للحصول على الموارد: إذا وافق المستخدم على نطاقات التفويض، سيجمع تطبيقك بيانات الاعتماد والنطاقات التي وافق عليها المستخدم في الطلب. يتم إرسال الطلب إلى خادم تفويض Google للحصول على رمز الدخول.

  6. يعرض محرّك بحث Google رمز الدخول: يحتوي رمز الدخول على قائمة بالنطاقات التي تم منحها. إذا كانت قائمة النطاقات المعروضة أكثر تقييدًا من النطاقات المطلوبة، أوقف تطبيقك أي ميزات محدودة بالرمز المميّز.

  7. الوصول إلى الموارد المطلوبة: يستخدم تطبيقك رمز الدخول المميز من Google لاستدعاء واجهة برمجة تطبيقات Chat والوصول إلى موارد واجهة برمجة تطبيقات Chat.

  8. الحصول على رمز مميّز لإعادة التحميل (اختياري): إذا كان تطبيقك يجب أن يصل إلى Google Chat API بعد انتهاء فترة رمز الدخول الفريد، يمكن أن يحصل على رمز مميز لإعادة التحميل. لمزيد من المعلومات، يمكنك الاطّلاع على استخدام OAuth 2.0 للوصول إلى واجهات Google API.

  9. طلب المزيد من المراجع: إذا كان تطبيقك بحاجة إلى المزيد من الوصول، يطلب من المستخدم منح نطاقات جديدة، ما يؤدي إلى طلب جديد للحصول على رمز دخول (الخطوات من 3 إلى 6).

عندما تتطلب تطبيقات Chat المصادقة

يمكن لتطبيقات Chat إرسال رسائل إلى Google Chat بشكل متزامن أو غير متزامن. يمكنهم أيضًا إكمال المهام، مثل إنشاء مساحة Chat نيابةً عن المستخدم.

لا تتطلب الرسائل المتزامنة المصادقة، ما لم يطلب تطبيق Chat Chat API أو واجهة برمجة تطبيقات Google أخرى أثناء معالجة الرد.

لإرسال رسائل غير متزامنة أو العمل نيابةً عن المستخدم، ترسل تطبيقات Chat طلبات RESTful إلى Chat API، والتي تتطلّب المصادقة والتفويض.

الرسائل المتزامنة لا تتطلب المصادقة

الرسائل المتزامنة هي ردود على أحداث Chat. يمكن لتطبيقات Google Chat تلقّي الأحداث والردّ عليها بعد إعدادها ونشرها على صفحة إعداد تطبيق Chat، ولكنّها لا تتطلّب إجراء مصادقة أو تفويض.

تتضمّن أمثلة أحداث Chat المتزامنة ما يلي:

  • يرسل مستخدم رسالة إلى تطبيق Chat في Google Chat.
  • يشير مستخدم إلى تطبيق Chat.
  • يستدعي المستخدم أحد أوامر الأوامر المائلة في تطبيق Chat.

يعرض المخطّط التالي تسلسلاً متزامنًا لطلب الاستجابة بين مستخدم Chat وتطبيق Chat:

ما مِن إذن مطلوب للرسائل المتزامنة
الشكل 2. ولا تتطلب الرسائل المتزامنة المصادقة.

  1. يرسل المستخدم رسالة إلى تطبيق Chat في Google Chat.
  2. يعيد تطبيق Google Chat توجيه الرسالة إلى التطبيق.
  3. يتلقّى التطبيق الرسالة ويعالجها، ويعرض ردًّا على Google Chat.
  4. يعرض تطبيق Google Chat الردّ للمستخدم، أو في مساحة.

يتكرر هذا التسلسل لكل حدث Chat.

تتطلب الرسائل غير المتزامنة المصادقة

تحدث الرسائل غير المتزامنة عندما يرسل تطبيق Chat طلبًا إلى Chat API، ما يتطلّب مصادقة وتفويضًا.

من خلال طلب Chat API، يمكن لتطبيقات Chat نشر الرسائل إلى Google Chat أو إكمال المهام والوصول إلى البيانات نيابةً عن المستخدم. على سبيل المثال، بعد رصد انقطاع في الخادم، يمكن لتطبيق Chat طلب واجهة برمجة تطبيقات Chat من أجل:

  • أنشئ مساحة Chat مخصصة للتحقيق في انقطاع الخدمة وإصلاحه.
  • إضافة مستخدمين إلى مساحة Chat.
  • يمكنك نشر رسالة إلى مساحة Chat لتقديم تفاصيل عن انقطاع الخدمة.

يوضح المخطّط التالي تسلسلاً غير متزامن للرسائل بين تطبيق Chat ومساحة Chat:

المصادقة مطلوبة للرسائل غير المتزامنة
الشكل 3. وتتطلب الرسائل غير المتزامنة المصادقة.

  1. ينشئ تطبيق Chat رسالة من خلال طلب واجهة برمجة التطبيقات من Chat باستخدام spaces.messages.create method، وتضمين بيانات اعتماد المستخدم في طلب HTTP.
  2. يصادق Google Chat على تطبيق Chat باستخدام بيانات اعتماد الحساب أو الخدمة.
  3. يعرض تطبيق Google Chat رسالة التطبيق إلى مساحة Chat محدّدة.

نطاقات واجهة برمجة تطبيقات Chat

لتحديد مستوى الوصول الممنوح لتطبيقك، عليك تحديد نطاقات التفويض والإعلان عنها. نطاق التفويض هو سلسلة معرّف الموارد المنتظم (URI) لبروتوكول OAuth 2.0 التي تحتوي على اسم تطبيق Google Workspace ونوع البيانات التي تصل إليها ومستوى الوصول.

يتوافق Google Chat مع النطاقات التالية:

نطاق Google Chat API الوصف
https://www.googleapis.com/auth/chat.bot يسمح هذا الإعداد لتطبيقات Chat بعرض المحادثات وإرسال الرسائل. يمنح الإذن بالوصول إلى جميع الميزات المتاحة لتطبيقات Chat.
https://www.googleapis.com/auth/chat.delete حذف المحادثات والمساحات وإزالة إمكانية الوصول إلى الملفات المرتبطة بها في Google Chat
الاشتراكات الداعمة  
https://www.googleapis.com/auth/chat.memberships الاطّلاع على المشاركين في محادثات في Google Chat وإضافتهم وإزالتهم
https://www.googleapis.com/auth/chat.memberships.app يتيح لتطبيق Chat إضافة نفسه إلى المحادثات في Google Chat وإزالتها منه (وليس التطبيقات الأخرى).
https://www.googleapis.com/auth/chat.memberships.readonly يمكنك الحصول على تفاصيل حول الانتساب وإدراجه في مساحة.
الرسائل  
https://www.googleapis.com/auth/chat.messages إنشاء رسائل في Google Chat والحصول عليها وتحديثها وحذفها وإدراجها في قائمة.
https://www.googleapis.com/auth/chat.messages.create إنشاء رسائل وتحميل المرفقات في Google Chat.
https://www.googleapis.com/auth/chat.messages.reactions عرض وإضافة وحذف التفاعلات مع الرسائل في Google Chat.
https://www.googleapis.com/auth/chat.messages.reactions.create إضافة تفاعلات إلى الرسائل في Google Chat
https://www.googleapis.com/auth/chat.messages.reactions.readonly عرض التفاعلات مع الرسائل في Google Chat.
https://www.googleapis.com/auth/chat.messages.readonly تلقّي الرسائل وإدراجها في Google Chat
المساحات  
https://www.googleapis.com/auth/chat.spaces يمكنك إنشاء محادثات ومساحات والاطّلاع على البيانات الوصفية أو تعديلها (بما في ذلك إعدادات السجلّ) في Google Chat.
https://www.googleapis.com/auth/chat.spaces.create إنشاء محادثات في Google Chat
https://www.googleapis.com/auth/chat.spaces.readonly يمكنك عرض المحادثات والمساحات في Google Chat.

لمزيد من المعلومات حول نطاقات Google Workspace API، يُرجى الاطّلاع على كيفية اختيار النطاقات لتطبيقك.

للحصول على قائمة بالنطاقات المتاحة، يُرجى الاطِّلاع على نطاقات OAuth 2.0 لواجهات برمجة تطبيقات Google.

أنواع المصادقة المطلوبة

هناك طريقتان لمصادقة تطبيقات Chat واعتمادها باستخدام Chat API، وهما: بيانات اعتماد المستخدم أو حسابات الخدمة.

باستخدام تفويض بيانات الاعتماد للمستخدم، يمكن لتطبيق Chat الوصول إلى بيانات المستخدم وإكمال الإجراءات نيابةً عن المستخدم. تحدد نطاقات OAuth البيانات والإجراءات المسموح بها. ومع ذلك، لا يمكن نشر تطبيقات Chat هذه بشكل علني. لمزيد من المعلومات، راجِع نشر تطبيقات Google Chat.

من خلال تفويض التطبيق، يصل تطبيق Chat إلى واجهة برمجة التطبيقات كتطبيق باستخدام بيانات اعتماد حساب الخدمة. تستخدم أذونات التطبيق دائمًا نطاق تفويض chat.bot.

إذا كنت مشرفًا لنطاق، يمكنك منح التفويض على مستوى النطاق لتفويض حساب خدمة التطبيق للوصول إلى بيانات المستخدمين بدون أن يطلب من كل مستخدم منح موافقته. بعد ضبط التفويض على مستوى النطاق، يمكنك إجراء طلبات بيانات من واجهة برمجة التطبيقات باستخدام حساب الخدمة من أجل انتحال هوية حساب مستخدم. على الرغم من استخدام حساب الخدمة للمصادقة، تنتحل التفويض على مستوى النطاق هوية المستخدم، وبالتالي تُعتبر مصادقة المستخدم. أي وظائف تتطلّب مصادقة المستخدم، يمكنها استخدام التفويض على مستوى النطاق.

عند تحديد نوع بيانات الاعتماد المطلوب استخدامها لطلب بيانات معيّنة لواجهة برمجة التطبيقات، يُرجى العِلم أنّ بعض طرق بيانات واجهة برمجة التطبيقات لا تتيح سوى نوع معيّن من بيانات الاعتماد. إذا كانت طريقة واجهة برمجة التطبيقات تتيح كلا نوعَي بيانات الاعتماد، سيؤثّر نوع بيانات الاعتماد المستخدَمة في المكالمة في النتيجة التي يتم عرضها:

  • باستخدام تفويض التطبيق، لا تعرض الطرق سوى الموارد التي يمكن للتطبيق الوصول إليها.
  • بعد الحصول على إذن المستخدم، لن تعرض الطرق إلا الموارد التي يمكن للمستخدم الوصول إليها في واجهة مستخدم Chat.

على سبيل المثال، يؤدي طلب طريقة ListSpaces باستخدام تفويض التطبيق إلى عرض قائمة المساحات التي كان التطبيق عضوًا فيها. يؤدي طلب ListSpaces بإذن من المستخدم إلى عرض قائمة المساحات التي يكون المستخدم عضوًا فيها. من الناحية العملية، قد يستخدم تطبيقك نوعَي التفويض عند طلب Chat API، وذلك اعتمادًا على الوظيفة التي تريدها.

لطلبات البيانات من واجهة برمجة التطبيقات Chat غير المتزامنة

يسرد الجدول التالي طرق Chat API ونطاقات التفويض المتوافقة:

الطريقة مصادقة المستخدم متاحة إتاحة مصادقة التطبيقات نطاقات التفويض المتوافقة
المساحات  
إنشاء مساحة
  • chat.spaces.create
  • chat.spaces
إعداد مساحة
  • chat.spaces.create
  • chat.spaces
الحصول على مساحة باستخدام مصادقة المستخدم:
  • chat.spaces.readonly
  • chat.spaces
باستخدام مصادقة التطبيقات:
  • chat.bot
إدراج المساحات باستخدام مصادقة المستخدم:
  • chat.spaces.readonly
  • chat.spaces
باستخدام مصادقة التطبيقات:
  • chat.bot
تعديل مساحة
  • chat.spaces
حذف مساحة
  • chat.delete
البحث عن رسالة مباشرة باستخدام مصادقة المستخدم:
  • chat.spaces.readonly
  • chat.spaces
باستخدام مصادقة التطبيقات:
  • chat.bot
الأعضاء  
إنشاء اشتراك
  • chat.memberships
  • chat.memberships.app
الاشتراك باستخدام مصادقة المستخدم:
  • chat.memberships.readonly
  • chat.memberships
باستخدام مصادقة التطبيقات:
  • chat.bot
أعضاء القائمة باستخدام مصادقة المستخدم:
  • chat.memberships.readonly
  • chat.memberships
باستخدام مصادقة التطبيقات:
  • chat.bot
حذف عضو
  • chat.memberships
  • chat.memberships.app
الرسائل  
إنشاء رسالة باستخدام مصادقة المستخدم:
  • chat.messages.create
  • chat.messages
باستخدام مصادقة التطبيقات:
  • chat.bot
تلقّي رسالة باستخدام مصادقة المستخدم:
  • chat.messages.readonly
  • chat.messages
باستخدام مصادقة التطبيقات:
  • chat.bot
إدراج الرسائل
  • chat.messages.readonly
  • chat.messages
تعديل رسالة باستخدام مصادقة المستخدم:
  • chat.messages
باستخدام مصادقة التطبيقات:
  • chat.bot
حذف رسالة باستخدام مصادقة المستخدم:
  • chat.messages
باستخدام مصادقة التطبيقات:
  • chat.bot
التفاعلات  
إنشاء تفاعل
  • chat.messages.reactions.create
  • chat.messages.reactions
  • chat.messages
إدراج التفاعلات
  • chat.messages.reactions.readonly
  • chat.messages.reactions
  • chat.messages.readonly
  • chat.messages
حذف تفاعل
  • chat.messages.reactions
  • chat.messages
الوسائط والمرفقات  
تحميل الوسائط كمرفق ملف
  • chat.messages.create
  • chat.messages
تنزيل الوسائط باستخدام مصادقة المستخدم:
  • chat.messages.readonly
  • chat.messages
باستخدام مصادقة التطبيقات:
  • chat.bot
الحصول على مرفق رسالة
  • chat.bot

مزامنة تفاعلات المستخدمين والردّ عليها بشكلٍ متزامن

يسرد الجدول التالي الطرق الشائعة التي يتفاعل بها المستخدمون مع تطبيقات Chat وما إذا كانت المصادقة مطلوبة أو متوافقة:

السيناريو لا حاجة إلى المصادقة مصادقة المستخدم متاحة إتاحة مصادقة التطبيقات
تلقّي رسائل من:
أحداث الدردشة
استدعاءات برمجة التطبيقات
Google Cloud Pub/Sub
الردّ على الرسائل:
بشكل متزامن، من خلال حدث Chat
بشكل متزامن، من خلال قيمة عرض معاودة الاتصال لبرمجة التطبيقات
إرسال رسائل جديدة:
باستخدام الردود التلقائية الواردة على الويب