ربط تطبيق Chat بخدمات وأدوات أخرى

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

لمصادقة المستخدمين باستخدام خدمة تابعة لجهة خارجية أو مسار OAuth، يتّبع تطبيق Chat الخطوات التالية:

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

بنية طريقة مصادقة تطبيقات Google Chat مع خدمة تابعة لجهة خارجية

المتطلبات الأساسية

HTTP

تطبيق Google Chat يتلقّى تفاعلات المستخدمين ويردّ عليها. لإنشاء أحدها، أكمل البداية السريعة لبروتوكول HTTP.

برمجة التطبيقات

تطبيق Google Chat يتلقّى تفاعلات المستخدمين ويردّ عليها. لإنشاء تطبيق، عليك إكمال دليل البدء السريع في برمجة تطبيقات.

رصد الحاجة إلى الحصول على إذن

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

  • لم يتم إنشاء رمز دخول للربط بالخدمة التابعة لجهة خارجية بعد أو انتهت صلاحيته.
  • لا يغطي رمز الدخول المورد المطلوب.
  • لا يغطي رمز الدخول النطاقات المطلوبة للطلب.

يجب أن يرصد تطبيق Chat هذه الحالات ليتمكّن المستخدمون من تسجيل الدخول ومنح الإذن بالوصول إلى خدمتك.

إذا كنت تعمل على إنشاء تطبيق في "برمجة تطبيقات Google"، يمكنك استخدام مكتبة OAuth2 لـ "برمجة تطبيقات Google" (أو إصدار OAuth1)، حيث تتحقّق الدالة hasAccess مما إذا كان المستخدم قد منح إذن الوصول إلى إحدى الخدمات. بدلاً من ذلك، عند استخدام طلبات UrlFetchApp.fetch، يمكنك ضبط المَعلمة muteHttpExceptions على true لفحص رمز الاستجابة والمحتوى في العنصر HttpResponse المعروض.

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

عندما يرصد تطبيق Chat أنّ هناك حاجة إلى تفويض أو إعداد، يجب عرض ردّ AuthorizationError لعرض بطاقة تفويض أساسية خاصة للمستخدم.

تعرض الصورة التالية مثالاً على بطاقة التفويض الأساسية من Google:

طلب التفويض الأساسي لحساب Example Account
الشكل 1: طلب التفويض الأساسي لحساب المثال. تشير الرسالة إلى أنّ تطبيق Chat يريد عرض معلومات إضافية، ولكنّه يحتاج إلى موافقة المستخدم للوصول إلى الحساب.

لعرض بطاقة تفويض أساسية للمستخدمين، عليك عرض عنصر AuthorizationError:

HTTP

أرجِع استجابة JSON التالية:

{
  "basic_authorization_prompt": {
    "authorization_url": "<var>AUTHORIZATION_URL</var>",
    "resource": "<var>RESOURCE_DISPLAY_NAME</var>"
  }
}

برمجة التطبيقات

CardService.newAuthorizationException()
    .setAuthorizationUrl('<var>AUTHORIZATION_URL</var>')
    .setResourceDisplayName('<var>RESOURCE_DISPLAY_NAME</var>')
    .throwException();

غيِّر القيم في السلسلة على الشكل التالي:

  • ‫AUTHORIZATION_URL: عنوان URL يستخدم HTTPS لتطبيق الويب الذي يتعامل مع المصادقة أو التفويض أو الإعداد.
  • ‫RESOURCE_DISPLAY_NAME: الاسم المعروض للمورد أو الخدمة المحمية. يظهر هذا الاسم للمستخدم في طلب التفويض. على سبيل المثال، إذا كان RESOURCE_DISPLAY_NAME هو Example Account، ستشير الرسالة إلى أنّ التطبيق يحتاج إلى موافقة للوصول إلى Example Account.

إكمال طلب الإعداد

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

بالنسبة إلى هذه المشغّلات، يتلقّى تطبيق Chat معرّف الموارد المنتظم (URI) الخاص بإعادة التوجيه عند اكتمال العملية (configCompleteRedirectUri / completeRedirectUri) في حمولة الحدث:

  • الرسالة: chat.messagePayload.configCompleteRedirectUri
  • تمت الإضافة إلى المساحة: chat.addedToSpacePayload.configCompleteRedirectUri
  • أمر التطبيق: chat.appCommandPayload.configCompleteRedirectUri

يجب ترميز معرّف الموارد المنتظم لإعادة التوجيه هذا في <var>AUTHORIZATION_URL</var> وإعادة توجيه متصفّح المستخدم إليه بعد اكتمال مسار التفويض. تشير عملية إعادة التوجيه إلى عنوان URL هذا إلى Google Chat بأنّه تم تنفيذ طلب التفويض أو الإعداد.

عندما تتم إعادة توجيه المستخدم بنجاح إلى معرّف الموارد المنتظم (URI) لإعادة التوجيه عند الإكمال المقدَّم في حمولة الحدث الأصلية، يتّخذ Google Chat الخطوات التالية:

  1. يمحو طلب التفويض الخاص المعروض للمستخدم الذي بدأ العملية.
  2. يحوّل الرسالة الأصلية إلى رسالة عامة، ما يجعلها مرئية للأعضاء الآخرين في المساحة.
  3. يرسل عنصر الحدث الأصلي إلى تطبيق Chat للمرة الثانية.

إذا لم تتم إعادة التوجيه إلى معرّف الموارد المنتظم لإعادة التوجيه عند اكتمال العملية، سيظل بإمكان المستخدم إكمال عملية التفويض، ولكن لن يعيد Google Chat تلقائيًا محاولة التنفيذ السابق، وسيكون على المستخدم إعادة تشغيل تطبيق Chat يدويًا.

لا يؤثّر الانتقال إلى معرّف الموارد المنتظم (URI) لإعادة التوجيه عند اكتمال العملية إلا في تفاعل مستخدم واحد. إذا أرسل المستخدم رسائل متعددة إلى تطبيق Chat وتلقّى طلبات متعددة، ستؤدي إكمال عملية المصادقة والإعداد لطلب واحد فقط إلى إعادة محاولة هذا التفاعل المحدّد.

مصادقة مستخدم Chat خارج Chat

عند الربط بعنوان URL خارج Chat (مثل معاودة الاتصال على الويب باستخدام OAuth)، عليك غالبًا ربط جلسة الويب الخارجية بهوية المستخدم في Chat. ننصحك بحماية تطبيق الويب الوجهة باستخدام ميزة تسجيل الدخول باستخدام حساب Google.

استخدِم رمز التعريف الذي تم إصداره أثناء تسجيل الدخول للحصول على رقم تعريف المستخدم. يتضمّن الادّعاء sub معرّف Google الفريد للمستخدم، ويمكن ربطه باسم مورد المستخدم (chat.user.name) من Google Chat.

لربط مطالبة sub باسم مورد users/{user} في Google Chat، أضِف users/ قبل قيمة المطالبة sub. على سبيل المثال، تتوافق قيمة المطالبة sub التي تبلغ 123 مع users/123 في عناصر الأحداث التي يتم إرسالها إلى تطبيق Chat.

عيّنات تعليمات برمجية

توضّح نماذج الرموز البرمجية التالية كيف يمكن لتطبيق Chat طلب بيانات اعتماد OAuth2 غير متصلة بالإنترنت باستخدام بطاقة تفويض أساسية، وتخزينها في قاعدة بيانات، وإعادة التوجيه إلى معرّف الموارد المنتظم (URI) الخاص بالإكمال، وإجراء طلبات البيانات من واجهة برمجة التطبيقات مع مصادقة المستخدم:

Node.js

عرض على GitHub

Python

عرض على GitHub

جافا

عرض على GitHub

برمجة التطبيقات

عرض على GitHub

تطبيقات Chat التي ليست إضافات: ربط تطبيق Chat بخدمات وأدوات أخرى

إذا كنت تدير تطبيق Chat ليس إضافة في Google Workspace، يطلب تطبيق Chat إعدادات باستخدام actionResponse من النوع REQUEST_CONFIG ويقرأ configCompleteRedirectUrl من العنصر Event ذي المستوى الأعلى.

لترقية تطبيق Chat ليس إضافة إلى إطار عمل إضافات Google Workspace، يُرجى الاطّلاع على تحويل تطبيق Google Chat إلى إضافة Google Workspace.

طلب إعدادات من مستخدم في تطبيق Chat ليس إضافة

في تطبيق Chat ليس إضافة، أرسِل عنوان URL للإعداد إلى المستخدم بالتنسيق التالي:

{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "CONFIGURATION_URL"
  }
}

يطلب هذا الرمز من Google Chat عرض طلب خاص للمستخدم، حيث يمثّل CONFIGURATION_URL رابطًا يمكن للمستخدم الانتقال إليه للحصول على مصادقة أو تفويض أو إعدادات إضافية. لا يمكن استخدام رد REQUEST_CONFIG مع رسالة رد عادية، ويتم تجاهل أي نص أو بطاقات أو سمات أخرى.

أكمِل طلب الضبط في تطبيق Chat ليس إضافة.

يتضمّن كل تفاعل MESSAGE وADDED_TO_SPACE وAPP_COMMAND Event يتلقّاه تطبيق Chat ليس إضافة الحقل configCompleteRedirectUrl ذو المستوى الأعلى. يجب ترميز عنوان URL هذا في عنوان URL الخاص بالإعدادات وإعادة توجيه المستخدم إليه عند الانتهاء، وذلك كي يمحو Google Chat الطلب ويحوّل الرسالة الأصلية إلى رسالة عامة ويعيد إرسال حدث التفاعل الأصلي إلى تطبيق Chat.

للاطّلاع على أمثلة على عمليات التنفيذ، راجِع عيّنة تطبيق الربط Node.js وعيّنة تطبيق المصادقة Python MyProfile على GitHub.