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

المصادقة والترخيص هما آليتان تُستخدمان للتحقق من الهوية والوصول إلى الموارد، على التوالي. توضح هذه الوثيقة كيف يمكن أن تتم المصادقة منح الأذونات لتطبيقات Chat وطلبات واجهة برمجة التطبيقات في 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 في حال حذف يصادق تطبيقك مع حساب خدمة، يتم إرسال بيانات الاعتماد من رمز التطبيق. إذا كان تطبيقك يتطلّب الاتصال بواجهة Chat API استخدام مصادقة مستخدم لم يتم منحها بعد، ستظهر في رسالة المطالبة تسجيل الدخول للمستخدم.

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

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

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

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

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

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

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

الحالات التي تتطلب فيها التطبيقات في Chat المصادقة

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

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

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

لا تتطلب الردود على تفاعلات المستخدمين المصادقة

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

تتلقّى تطبيقات Google Chat أحداث التفاعل عندما يتفاعل أحد المستخدمين أو تطبيق Chat، بما في ذلك ما يلي:

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

يوضح الرسم التخطيطي التالي تسلسل الطلب والاستجابة بين مستخدم Google Chat وتطبيق Chat:

ما مِن تفويض مطلوب لأحداث التفاعل مع تطبيقات Chat.
الشكل 2.لا تتطلّب أحداث التفاعل مع تطبيقات Chat المصادقة.

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

يتكرر هذا التسلسل لكل تفاعل مع تطبيق Chat. فعالية.

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

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

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

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

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

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

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

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

ضبط شاشة موافقة OAuth واختيار النطاقات لتحديد المعلومات التي يتم عرضها للمستخدمين ومراجعي التطبيقات، وتسجيل في تطبيقك كي تتمكن من نشره لاحقًا.

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

النطاقات غير الحسّاسة

رمز النطاق الوصف
https://www.googleapis.com/auth/chat.bot

يتيح نطاق 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.spaces عرض المحادثات والمساحات التي يملكها نطاق المشرف في 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 APIs أخرى، يمكنك إضافة هذه النطاقات. كذلك. لمزيد من المعلومات حول نطاقات واجهة برمجة تطبيقات Google، يمكنك الاطّلاع على استخدام 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.spaces.create
  • chat.spaces
  • chat.import
إعداد مساحة باستخدام مصادقة المستخدم:
  • chat.spaces.create
  • chat.spaces
الحصول على مساحة باستخدام مصادقة المستخدم:
  • chat.spaces.readonly
  • chat.spaces
باستخدام مصادقة التطبيقات:
  • chat.bot
من خلال مصادقة المستخدم باستخدام امتيازات المشرف:
  • chat.admin.spaces.readonly
مساحات العمل باستخدام مصادقة المستخدم:
  • chat.spaces.readonly
  • chat.spaces
باستخدام مصادقة التطبيقات:
  • chat.bot
البحث في المساحات من خلال مصادقة المستخدم باستخدام امتيازات المشرف:
  • chat.admin.spaces.readonly
تعديل مساحة باستخدام مصادقة المستخدم:
  • chat.spaces
  • chat.import
من خلال مصادقة المستخدم باستخدام امتيازات المشرف:
  • chat.admin.spaces
حذف مساحة باستخدام مصادقة المستخدم:
  • chat.delete
  • chat.import
من خلال مصادقة المستخدم باستخدام امتيازات المشرف:
  • chat.admin.delete
إكمال عملية استيراد مساحة باستخدام مصادقة المستخدم:
  • chat.import
العثور على رسالة مباشرة باستخدام مصادقة المستخدم:
  • chat.spaces.readonly
  • chat.spaces
باستخدام مصادقة التطبيقات:
  • chat.bot
الأعضاء  
إنشاء عضو باستخدام مصادقة المستخدم:
  • chat.memberships
  • chat.memberships.app
  • chat.import
من خلال مصادقة المستخدم باستخدام امتيازات المشرف:
  • chat.admin.memberships
الاشتراك في القناة باستخدام مصادقة المستخدم:
  • chat.memberships.readonly
  • chat.memberships
باستخدام مصادقة التطبيقات:
  • chat.bot
من خلال مصادقة المستخدم باستخدام امتيازات المشرف:
  • chat.admin.memberships.readonly
أعضاء القائمة باستخدام مصادقة المستخدم:
  • chat.memberships.readonly
  • chat.memberships
  • chat.import
باستخدام مصادقة التطبيقات:
  • chat.bot
من خلال مصادقة المستخدم باستخدام امتيازات المشرف:
  • chat.admin.memberships.readonly
حذف عضو باستخدام مصادقة المستخدم:
  • chat.memberships
  • chat.memberships.app
  • chat.import
من خلال مصادقة المستخدم باستخدام امتيازات المشرف:
  • chat.admin.memberships
تعديل معلومات عضو باستخدام مصادقة المستخدم:
  • chat.memberships
  • chat.import
من خلال مصادقة المستخدم باستخدام امتيازات المشرف:
  • chat.admin.memberships
الرسائل  
إنشاء رسالة باستخدام مصادقة المستخدم:
  • chat.messages.create
  • chat.messages
  • chat.import
باستخدام مصادقة التطبيقات:
  • chat.bot
تلقّي رسالة باستخدام مصادقة المستخدم:
  • chat.messages.readonly
  • chat.messages
باستخدام مصادقة التطبيقات:
  • chat.bot
إدراج الرسائل باستخدام مصادقة المستخدم:
  • chat.messages.readonly
  • chat.messages
  • chat.import
تعديل رسالة باستخدام مصادقة المستخدم:
  • chat.messages
  • chat.import
باستخدام مصادقة التطبيقات:
  • chat.bot
حذف رسالة باستخدام مصادقة المستخدم:
  • chat.messages
  • chat.import
باستخدام مصادقة التطبيقات:
  • chat.bot
التفاعلات  
إنشاء تفاعل باستخدام مصادقة المستخدم:
  • chat.messages.reactions.create
  • chat.messages.reactions
  • chat.messages
  • chat.import
سرد التفاعلات باستخدام مصادقة المستخدم:
  • chat.messages.reactions.readonly
  • chat.messages.reactions
  • chat.messages.readonly
  • chat.messages
حذف تفاعل باستخدام مصادقة المستخدم:
  • chat.messages.reactions
  • chat.messages
  • chat.import
الوسائط المرفقات  
تحميل الوسائط كمرفق ملف باستخدام مصادقة المستخدم:
  • chat.messages.create
  • chat.messages
  • chat.import
تنزيل الوسائط باستخدام مصادقة المستخدم:
  • chat.messages.readonly
  • chat.messages
باستخدام مصادقة التطبيقات:
  • chat.bot
الحصول على مرفق رسالة باستخدام مصادقة التطبيقات:
  • chat.bot
حالات قراءة المستخدم
الحصول على حالة قراءة مساحة المستخدم باستخدام مصادقة المستخدم:
  • chat.users.readstate
  • chat.users.readstate.readonly
تعديل حالة قراءة مساحة المستخدم باستخدام مصادقة المستخدم:
  • chat.users.readstate
الحصول على حالة قراءة سلسلة محادثات المستخدم باستخدام مصادقة المستخدم:
  • chat.users.readstate
  • chat.users.readstate.readonly
أحداث المساحة
الحصول على أحداث المساحة باستخدام مصادقة المستخدم، يجب عليك استخدام نطاق بناءً على نوع الفعالية:
  • بالنسبة إلى الأحداث عن الرسائل:
    • chat.messages
    • chat.messages.readonly
  • بالنسبة إلى الأحداث المتعلّقة بالتفاعلات:
    • chat.messages.reactions
    • chat.messages.reactions.readonly
    • chat.messages
    • chat.messages.readonly
  • للأحداث المتعلقة بالعضويات:
    • chat.memberships
    • chat.memberships.readonly
  • بالنسبة إلى الأحداث المتعلقة بالمساحة:
    • chat.spaces
    • chat.spaces.readonly
سرد أحداث المساحة باستخدام مصادقة المستخدم، يجب عليك استخدام نطاق لكل نوع الحدث المضمّن في الطلب:
  • بالنسبة إلى الأحداث عن الرسائل:
    • chat.messages
    • chat.messages.readonly
  • بالنسبة إلى الأحداث المتعلّقة بالتفاعلات:
    • chat.messages.reactions
    • chat.messages.reactions.readonly
    • chat.messages
    • chat.messages.readonly
  • للأحداث المتعلقة بالعضويات:
    • chat.memberships
    • chat.memberships.readonly
  • بالنسبة إلى الأحداث المتعلقة بالمساحة:
    • chat.spaces
    • chat.spaces.readonly

بالنسبة إلى أحداث التفاعل مع تطبيقات Chat

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

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