المصادقة والترخيص هما آليتان تستخدمان للتحقق من الهوية والوصول إلى الموارد على التوالي. يوضّح هذا المستند آلية عمل المصادقة والتفويض لتطبيقات Chat وطلبات واجهة برمجة التطبيقات في 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 API باستخدام مصادقة مستخدم لم يتم منحها بعد، سيطلب من المستخدم تسجيل الدخول.
طلب الموارد: يطلب تطبيقك الوصول باستخدام النطاقات التي تحدّدها أثناء إعداد المصادقة.
طلب الموافقة: إذا كان تطبيقك تتم المصادقة عليه كمستخدم، ستعرض Google شاشة طلب الموافقة على بروتوكول OAuth حتى يتمكن المستخدم من تحديد ما إذا كان يريد منح التطبيق إذن الوصول إلى البيانات المطلوبة. لا تتطلب المصادقة باستخدام حساب الخدمة موافقة المستخدم.
إرسال طلب تمت الموافقة عليه للحصول على الموارد: إذا وافق المستخدم على نطاقات التفويض، سيجمع تطبيقك بيانات الاعتماد والنطاقات التي وافق عليها المستخدم في الطلب. يتم إرسال الطلب إلى خادم تفويض Google للحصول على رمز الدخول.
إرجاع Google رمز دخول: يحتوي رمز الدخول على قائمة بالنطاقات الممنوحة. إذا كانت قائمة النطاقات المعروضة أكثر تقييدًا من النطاقات المطلوبة، يوقف تطبيقك أي ميزات محدودة بالرمز المميز.
الوصول إلى الموارد المطلوبة: يستخدم تطبيقك رمز الدخول من Google لاستدعاء Chat API والوصول إلى موارد Chat API.
الحصول على رمز مميّز لإعادة التحميل (اختياري): إذا كان يجب أن يصل تطبيقك إلى Google Chat API بعد انتهاء صلاحية رمز دخول واحد، يمكن أن يحصل على رمز مميّز لإعادة التحميل. لمزيد من المعلومات، راجع استخدام OAuth 2.0 للوصول إلى Google APIs.
طلب المزيد من الموارد: إذا كان تطبيقك يحتاج إلى مزيد من أذونات الوصول، سيطلب من المستخدم منح نطاقات جديدة، ما ينتج عنه طلب جديد للحصول على رمز دخول (الخطوات من 3 إلى 6).
الحالات التي تتطلب فيها التطبيقات في Chat المصادقة
يمكن لتطبيقات Chat إرسال الرسائل استجابةً لتفاعل المستخدم أو بشكل غير متزامن. ويمكنهم أيضًا إكمال المهام نيابةً عن المستخدم، مثل إنشاء "مساحة Chat" أو الحصول على قائمة بالمستخدمين في "مساحة Chat".
لا تتطلّب تطبيقات Chat المصادقة للاستجابة إلى تفاعل المستخدم، إلا إذا يستدعي تطبيق Chat Chat API أو واجهة برمجة تطبيقات أخرى من Google API أثناء معالجة أحد الردود.
لإرسال رسائل غير متزامنة أو تنفيذ مهام نيابةً عن المستخدم، ترسل تطبيقات Chat طلبات RESTful إلى Chat API، التي تتطلب المصادقة والتفويض.
لا تتطلب الردود على تفاعلات المستخدمين المصادقة
لا تحتاج تطبيقات Google Chat إلى المصادقة كمستخدم أو كتطبيق في Chat لتلقّي أحداث التفاعل والاستجابة لها بشكل متزامن.
تتلقّى تطبيقات Google Chat أحداث التفاعل عندما يتفاعل مستخدم مع تطبيق Chat أو استدعاه، ويشمل ذلك ما يلي:
- يُرسِل مستخدم رسالة إلى تطبيق 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 API من أجل:
- أنشئ مساحة Chat مخصّصة للتحقيق في انقطاع الخدمة وإصلاحه.
- أضِف مستخدمين إلى "مساحة Chat".
- نشر رسالة على مساحة Chat لتقديم تفاصيل حول انقطاع الخدمة
يعرض المخطّط التالي تسلسل رسائل غير متزامن بين تطبيق Chat ومساحة Chat:
- ينشئ التطبيق في Chat رسالة من خلال استدعاء
Chat API باستخدام
طريقة
spaces.messages.create، ويتضمّن بيانات اعتماد المستخدم في طلب HTTP. - يصادق Google Chat على تطبيق Chat باستخدام حساب الخدمة أو بيانات اعتماد المستخدم.
- يعرض Google Chat رسالة التطبيق في مساحة Chat محدّدة.
نطاقات واجهات برمجة تطبيقات Chat
اضبط شاشة موافقة OAuth واختيار النطاقات لتحديد المعلومات التي يتم عرضها للمستخدمين ومراجعي التطبيق، وتسجيل تطبيقك كي تتمكن من نشره لاحقًا.
لتحديد مستوى الوصول الممنوح لتطبيقك، عليك تحديد نطاقات التفويض وتعريفها. نطاق التفويض هو سلسلة معرّف موارد منتظم (URI) لبروتوكول OAuth 2.0 تحتوي على اسم تطبيق Google Workspace ونوع البيانات التي يصل إليها ومستوى الوصول.
النطاقات غير الحسّاسة
| رمز النطاق | الوصف |
|---|---|
https://www.googleapis.com/auth/chat.bot
|
يتيح نطاق يسمح هذا الإعداد للتطبيقات في Chat بعرض المحادثات وإرسال الرسائل. يمنح إمكانية الوصول إلى جميع الميزات المتاحة لتطبيقات Chat. |
النطاقات الحساسة
| رمز النطاق | الوصف |
|---|---|
https://www.googleapis.com/auth/chat.spaces
|
يمكنك إنشاء محادثات ومساحات والاطّلاع على البيانات الوصفية أو تعديلها (بما في ذلك إعدادات السجلّ وإعدادات الوصول) في Chat. |
https://www.googleapis.com/auth/chat.spaces.create
|
إنشاء محادثات جديدة في Chat |
https://www.googleapis.com/auth/chat.spaces.readonly
|
عرض المحادثات والمساحات في Chat |
https://www.googleapis.com/auth/chat.memberships
|
الاطّلاع على الأعضاء في المحادثات في Chat وإضافتهم وإزالتهم وتعديل معلوماتهم |
https://www.googleapis.com/auth/chat.memberships.app
|
إضافة نفسه إلى المحادثات في Google Chat وإزالتها |
https://www.googleapis.com/auth/chat.memberships.readonly
|
الاطّلاع على الأعضاء في محادثات Chat |
https://www.googleapis.com/auth/chat.messages.create
|
إنشاء الرسائل وإرسالها في Chat |
https://www.googleapis.com/auth/chat.messages.reactions
|
عرض وإضافة وحذف التفاعلات مع الرسائل في Chat |
https://www.googleapis.com/auth/chat.messages.reactions.create
|
إضافة تفاعلات إلى رسالة في Chat |
https://www.googleapis.com/auth/chat.messages.reactions.readonly
|
الاطّلاع على التفاعلات مع رسالة في Chat |
https://www.googleapis.com/auth/chat.users.readstate
|
الاطّلاع على وقت آخر قراءة لمحادثات Chat وتعديله |
https://www.googleapis.com/auth/chat.users.readstate.readonly
|
الاطّلاع على وقت قراءة محادثات Chat لآخر مرة |
https://www.googleapis.com/auth/chat.admin.spaces.readonly
|
عرض المحادثات والمساحات التي يمتلكها نطاق المشرف في Chat |
https://www.googleapis.com/auth/chat.admin.memberships.readonly
|
الاطّلاع على الأعضاء والمدراء في المحادثات التي يمتلكها نطاق المشرف في Chat |
https://www.googleapis.com/auth/chat.admin.memberships
|
عرض الأعضاء والمدراء في المحادثات التي يمتلكها نطاق المشرف في Chat وإضافتهم وتعديلهم وإزالتهم |
النطاقات المشروطة
| رمز النطاق | الوصف |
|---|---|
https://www.googleapis.com/auth/chat.delete
|
حذف المحادثات والمساحات وإزالة إمكانية الوصول إلى الملفات المرتبطة بها في Chat |
https://www.googleapis.com/auth/chat.import
|
استيراد المساحات والرسائل والاشتراكات إلى Chat لمزيد من المعلومات، يُرجى الاطّلاع على تفويض التطبيقات في Chat لاستيراد البيانات. |
https://www.googleapis.com/auth/chat.messages
|
عرض الرسائل وإنشاؤها وإرسالها وتعديلها وحذفها وإضافة التفاعلات مع الرسائل وعرضها وحذفها |
https://www.googleapis.com/auth/chat.messages.readonly
|
يمكنك عرض الرسائل والتفاعلات في Chat. |
https://www.googleapis.com/auth/chat.admin.delete
|
حذف المحادثات والمساحات التي يملكها نطاق المشرف، وإزالة إمكانية الوصول إلى الملفات المرتبطة في Chat |
تشير النطاقات في الجداول السابقة إلى حساسيتها، وفقًا للتعريفات التالية:
غير حساسة: توفر هذه النطاقات أصغر مجال من الوصول للتفويض ولا تتطلب سوى التحقق الأساسي من التطبيقات. للحصول على معلومات عن هذا الشرط، راجِع خطوات التحضير لإثبات الملكية.
حسّاس: توفّر هذه النطاقات لتطبيقك إمكانية الوصول إلى بيانات مستخدم معيّن على Google بعد تلقّي تفويض من المستخدم. يتطلب منك الأمر إجراء مزيد من التحقق من التطبيقات. للحصول على معلومات عن هذا الشرط، يُرجى الاطّلاع على خطوات التطبيقات التي تطلب نطاقات حساسة.
محدود: توفّر هذه النطاقات وصولاً واسع النطاق إلى بيانات مستخدمي Google وتتطلب منك إكمال عملية التحقّق من النطاق المشروط. للحصول على معلومات عن هذا الشرط، يُرجى الاطّلاع على خدمات Google API: سياسة بيانات المستخدمين والمتطلبات الإضافية لنطاقات واجهة برمجة التطبيقات المحددة. راجِع أيضًا خطوات التطبيقات التي تطلب نطاقات مقيَّدة.
إذا كان تطبيقك يتطلب الوصول إلى أيّ من واجهات Google APIs الأخرى، يمكنك إضافة هذه النطاقات أيضًا. لمزيد من المعلومات حول نطاقات واجهة Google API، يمكنك الاطّلاع على استخدام OAuth 2.0 للوصول إلى Google APIs.
لمزيد من المعلومات عن نطاقات واجهات برمجة التطبيقات في Google Workspace، يُرجى الاطّلاع على ضبط شاشة موافقة OAuth واختيار النطاقات.
أنواع المصادقة المطلوبة
هناك طريقتان يمكن للتطبيقات في Chat للمصادقة والتفويض باستخدام واجهة برمجة التطبيقات Chat API: بيانات اعتماد المستخدم أو حسابات الخدمة.
باستخدام تفويض بيانات اعتماد المستخدم، يمكن لتطبيق Chat الوصول إلى بيانات المستخدم وإكمال الإجراءات نيابةً عنه. تحدّد نطاقات OAuth البيانات والإجراءات المسموح بها.
يمكن لتطبيق Chat الوصول إلى
واجهة برمجة التطبيقات كتطبيق باستخدام بيانات اعتماد حساب الخدمة، وذلك من خلال تفويض التطبيق. تستخدم تفويض التطبيق
دائمًا نطاق تفويض chat.bot.
عند تحديد نوع بيانات الاعتماد التي سيتم استخدامها لطلب بيانات من واجهة برمجة التطبيقات، يُرجى تذكُّر أنّ بعض طرق واجهة برمجة التطبيقات لا تتوافق إلا مع نوع معيّن من بيانات الاعتماد. إذا كانت طريقة واجهة برمجة التطبيقات تتوافق مع كلا بيانات الاعتماد، سيؤثر نوع بيانات الاعتماد المستخدم في الطلب على النتيجة التي يتم عرضها:
- باستخدام تفويض التطبيق، لا تعرض الطرق سوى الموارد التي يمكن للتطبيق الوصول إليها.
- من خلال تفويض المستخدم، لا تعرض الطرق سوى الموارد التي يمكن للمستخدم الوصول إليها في واجهة مستخدم Chat.
على سبيل المثال، يؤدي استدعاء طريقة ListSpaces بتفويض التطبيق إلى عرض قائمة المساحات التي ينتمي إليها التطبيق. يؤدي استدعاء ListSpaces مع تفويض المستخدم إلى عرض قائمة المساحات التي يكون المستخدم عضوًا فيها. من الناحية العملية، قد يستخدم تطبيقك نوعَي التفويض عند طلب البيانات من واجهة Chat API، بناءً على الوظيفة التي تريدها.
لطلبات البيانات غير المتزامنة من واجهة برمجة التطبيقات في Chat
يسرد الجدول التالي طرق Chat API ونطاقات التفويض المتاحة لها:
| الطريقة | مصادقة المستخدم متاحة | مصادقة التطبيقات متاحة | نطاقات الأذونات المتاحة | |
|---|---|---|---|---|
| المساحات | ||||
| إنشاء مساحة | — |
باستخدام مصادقة المستخدم:
|
||
| إعداد مساحة | — |
باستخدام مصادقة المستخدم:
|
||
| الحصول على مساحة |
باستخدام مصادقة المستخدم:
|
|||
| مساحات العمل |
باستخدام مصادقة المستخدم:
|
|||
| البحث في المساحات |
من خلال مصادقة المستخدم باستخدام امتيازات المشرف:
|
|||
| تعديل مساحة | — |
باستخدام مصادقة المستخدم:
|
||
| حذف مساحة | — |
باستخدام مصادقة المستخدم:
|
||
| إكمال عملية استيراد مساحة | — |
باستخدام مصادقة المستخدم:
|
||
| العثور على رسالة مباشرة |
باستخدام مصادقة المستخدم:
|
|||
| الأعضاء | ||||
| إنشاء عضو | — |
باستخدام مصادقة المستخدم:
|
||
| الاشتراك في القناة |
باستخدام مصادقة المستخدم:
|
|||
| أعضاء القائمة |
باستخدام مصادقة المستخدم:
|
|||
| حذف عضو | — |
باستخدام مصادقة المستخدم:
|
||
| الرسائل | ||||
| إنشاء رسالة |
باستخدام مصادقة المستخدم:
|
|||
| تلقّي رسالة |
باستخدام مصادقة المستخدم:
|
|||
| إدراج الرسائل | — |
باستخدام مصادقة المستخدم:
|
||
| تعديل رسالة |
باستخدام مصادقة المستخدم:
|
|||
| حذف رسالة |
باستخدام مصادقة المستخدم:
|
|||
| التفاعلات | ||||
| إنشاء تفاعل | — |
باستخدام مصادقة المستخدم:
|
||
| سرد التفاعلات | — |
باستخدام مصادقة المستخدم:
|
||
| حذف تفاعل | — |
باستخدام مصادقة المستخدم:
|
||
| الوسائط والمرفقات | ||||
| تحميل الوسائط كمرفق ملف | — |
باستخدام مصادقة المستخدم:
|
||
| تنزيل الوسائط |
باستخدام مصادقة المستخدم:
|
|||
| الحصول على مرفق رسالة | — |
باستخدام مصادقة التطبيقات:
|
||
| حالات قراءة المستخدم | ||||
| الحصول على حالة قراءة مساحة المستخدم | — |
باستخدام مصادقة المستخدم:
|
||
| تعديل حالة قراءة مساحة المستخدم | — |
باستخدام مصادقة المستخدم:
|
||
| الحصول على حالة قراءة سلسلة محادثات المستخدم | — |
باستخدام مصادقة المستخدم:
|
||
| أحداث المساحة | ||||
| الحصول على أحداث المساحة | — |
باستخدام مصادقة المستخدم:
|
||
| سرد أحداث المساحة | — |
باستخدام مصادقة المستخدم:
|
||
بالنسبة إلى أحداث التفاعل مع تطبيقات Chat
يسرد الجدول التالي الطرق الشائعة التي يتفاعل بها المستخدمون مع تطبيقات Chat وما إذا كانت المصادقة مطلوبة أو متاحة:
| السيناريو | المصادقة غير مطلوبة | مصادقة المستخدم متاحة | مصادقة التطبيقات متاحة | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| تلقّي رسائل من: |
|
|||||||||||||||
| الرد على الرسائل: |
|
|||||||||||||||
| إرسال رسائل جديدة: |
|
|||||||||||||||
مواضيع ذات صلة
- لإلقاء نظرة عامة على المصادقة والتفويض في Google Workspace، يُرجى الاطّلاع على مزيد من المعلومات عن المصادقة والترخيص.
- لإلقاء نظرة عامة على المصادقة والتفويض في Google Cloud، يُرجى الاطِّلاع على نظرة عامة على المصادقة.
- لمزيد من المعلومات عن حسابات الخدمة، يُرجى الاطّلاع على حسابات الخدمة.
- لمزيد من المعلومات حول كيفية استفادة واجهات Google APIs من OAuth 2.0، يمكنك الاطّلاع على استخدام OAuth 2.0 للوصول إلى Google APIs.
- يمكنك إعداد المصادقة والتفويض باستخدام بيانات اعتماد المستخدم أو حساب خدمة.