المصادقة والتفويض هي آليات تُستخدم لإثبات الهوية والوصول إلى الموارد على التوالي. يوضّح هذا المستند آلية عمل المصادقة والترخيص لتطبيقات Chat وطلبات البيانات من واجهة برمجة التطبيقات.
نظرة عامة على العملية
يوضّح المخطّط التالي الخطوات ذات المستوى العالي للمصادقة والتفويض في Google Chat:
ضبط مشروع Google Cloud وتفعيل Chat API وضبط تطبيق Chat: أثناء التطوير، عليك إنشاء مشروع على Google Cloud. في مشروع Google Cloud، يمكنك تفعيل Chat API وضبط تطبيق Chat وإعداد المصادقة. لمزيد من المعلومات، يُرجى الاطّلاع على التطوير على Google Workspace وإنشاء تطبيق Chat.
Call Chat API: عندما يستدعي تطبيقك واجهة Chat API، يتم إرسال بيانات اعتماد المصادقة إلى Chat API. إذا تمت مصادقة تطبيقك باستخدام حساب خدمة، سيتم إرسال بيانات الاعتماد كجزء من رمز التطبيق. إذا كان تطبيقك يتطلّب الاتصال بواجهة برمجة تطبيقات Chat باستخدام مصادقة مستخدم لم يتم منحها بعد، سيُطلب من المستخدم تسجيل الدخول.
طلب الموارد: يطلب تطبيقك إذن الوصول باستخدام النطاقات التي تحدّدها أثناء إعداد المصادقة.
طلب الموافقة: إذا تمت مصادقة تطبيقك كمستخدم، ستعرض Google شاشة موافقة OAuth حتى يتمكّن المستخدم من تحديد ما إذا كان سيمنح تطبيقك إذن الوصول إلى البيانات المطلوبة. لا تتطلب المصادقة باستخدام حساب خدمة موافقة المستخدم.
إرسال طلب الموافَق عليه للحصول على الموارد: إذا وافق المستخدم على نطاقات التفويض، سيجمع تطبيقك بيانات الاعتماد والنطاقات التي وافق عليها المستخدم في الطلب. يتم إرسال الطلب إلى خادم تفويض Google للحصول على رمز الدخول.
يعرض محرّك بحث Google رمز الدخول: يحتوي رمز الدخول على قائمة بالنطاقات التي تم منحها. إذا كانت قائمة النطاقات المعروضة أكثر تقييدًا من النطاقات المطلوبة، أوقف تطبيقك أي ميزات محدودة بالرمز المميّز.
الوصول إلى الموارد المطلوبة: يستخدم تطبيقك رمز الدخول المميز من Google لاستدعاء واجهة برمجة تطبيقات Chat والوصول إلى موارد واجهة برمجة تطبيقات Chat.
الحصول على رمز مميّز لإعادة التحميل (اختياري): إذا كان تطبيقك يجب أن يصل إلى Google Chat API بعد انتهاء فترة رمز الدخول الفريد، يمكن أن يحصل على رمز مميز لإعادة التحميل. لمزيد من المعلومات، يمكنك الاطّلاع على استخدام OAuth 2.0 للوصول إلى واجهات Google API.
طلب المزيد من المراجع: إذا كان تطبيقك بحاجة إلى المزيد من الوصول، يطلب من المستخدم منح نطاقات جديدة، ما يؤدي إلى طلب جديد للحصول على رمز دخول (الخطوات من 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:
- يرسل المستخدم رسالة إلى تطبيق Chat في Google Chat.
- يعيد تطبيق Google Chat توجيه الرسالة إلى التطبيق.
- يتلقّى التطبيق الرسالة ويعالجها، ويعرض ردًّا على Google Chat.
- يعرض تطبيق Google Chat الردّ للمستخدم، أو في مساحة.
يتكرر هذا التسلسل لكل حدث Chat.
تتطلب الرسائل غير المتزامنة المصادقة
تحدث الرسائل غير المتزامنة عندما يرسل تطبيق Chat طلبًا إلى Chat API، ما يتطلّب مصادقة وتفويضًا.
من خلال طلب Chat API، يمكن لتطبيقات Chat نشر الرسائل إلى Google Chat أو إكمال المهام والوصول إلى البيانات نيابةً عن المستخدم. على سبيل المثال، بعد رصد انقطاع في الخادم، يمكن لتطبيق Chat طلب واجهة برمجة تطبيقات Chat من أجل:
- أنشئ مساحة Chat مخصصة للتحقيق في انقطاع الخدمة وإصلاحه.
- إضافة مستخدمين إلى مساحة Chat.
- يمكنك نشر رسالة إلى مساحة Chat لتقديم تفاصيل عن انقطاع الخدمة.
يوضح المخطّط التالي تسلسلاً غير متزامن للرسائل بين تطبيق Chat ومساحة Chat:
- ينشئ تطبيق Chat رسالة من خلال طلب
واجهة برمجة التطبيقات من Chat باستخدام
spaces.messages.create method، وتضمين بيانات اعتماد المستخدم في طلب HTTP. - يصادق Google Chat على تطبيق Chat باستخدام بيانات اعتماد الحساب أو الخدمة.
- يعرض تطبيق 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 وما إذا كانت المصادقة مطلوبة أو متوافقة:
| السيناريو | لا حاجة إلى المصادقة | مصادقة المستخدم متاحة | إتاحة مصادقة التطبيقات | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| تلقّي رسائل من: |
|
|||||||||||||||
| الردّ على الرسائل: |
|
|||||||||||||||
| إرسال رسائل جديدة: |
|
|||||||||||||||
مواضيع ذات صلة
- للحصول على نظرة عامة عن المصادقة والتفويض في Google Workspace، اطّلِع على مزيد من المعلومات حول المصادقة والتفويض.
- للحصول على نظرة عامة عن المصادقة والتفويض في Google Cloud، يُرجى الاطِّلاع على نظرة عامة على المصادقة.
- ولمزيد من المعلومات عن حسابات الخدمة، يُرجى الاطّلاع على حسابات الخدمة.
- لمزيد من المعلومات عن كيفية استفادة Google APIs من OAuth 2.0، يمكنك الاطّلاع على استخدام OAuth 2.0 للوصول إلى Google APIs.
- إعداد المصادقة والتفويض باستخدام بيانات اعتماد المستخدم أو حساب الخدمة.