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