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