برنامه Chat را به سرویس‌ها و ابزارهای دیگر متصل کنید

این صفحه نحوه اتصال برنامه Google Chat به سرویس یا ابزاری خارج از Google Chat را شرح می‌دهد. برنامه‌های Chat به‌تنهایی قدرتمند هستند، اما اغلب با سیستم‌های دیگر هماهنگ کار می‌کنند و برای اتصال حساب‌ها، مجاز کردن دسترسی به داده‌ها، نمایش داده‌های اضافی، یا پیکربندی اولویت‌های کاربر به برنامه‌های همراه نیاز دارند.

برای اصالت‌سنجی کاربران با سرویس طرف سوم یا جریان OAuth، برنامه Chat شما مراحل زیر را انجام می‌دهد:

  1. تشخیص اینکه چه زمانی مجوز یا پیکربندی لازم است.
  2. کارت مجوز پایه را برگردانید که از کاربر می‌خواهد به سیستم وارد شود یا سرویس را پیکربندی کند.
  3. به نشانی وب تکمیل هدایت کنید تا Google Chat پس‌از تکمیل مجوز توسط کاربر، تعامل اصلی را به‌طور خودکار دوباره امتحان کند.

معماری نحوه اصالت‌سنجی برنامه‌های Google Chat با سرویس طرف سوم.

پیش‌نیازها

HTTP

برنامه Google Chat که تعاملات کاربر را دریافت و به آن‌ها پاسخ می‌دهد. برای ساختن آن، شروع سریع HTTP را تکمیل کنید.

Apps Script

برنامه Google Chat که تعاملات کاربر را دریافت و به آن‌ها پاسخ می‌دهد. برای ساختن یکی از آن‌ها، راه‌اندازی سریع Apps Script را تکمیل کنید.

تشخیص اینکه مجوز لازم است

هنگام تعامل با برنامه Chat، ممکن است کاربران به دلایل مختلف مجاز به دسترسی به منبع محافظت‌شده نباشند، ازجمله دلایل زیر:

  • هنوز کد دسترسی برای اتصال به سرویس طرف سوم تولید نشده است یا منقضی شده است.
  • کد دسترسی منبع درخواستی را پوشش نمی‌دهد.
  • کد دسترسی دامنه‌های موردنیاز درخواست را پوشش نمی‌دهد.

برنامه Chat شما باید این موارد را تشخیص دهد تا کاربران بتوانند به سیستم وارد شوند و دسترسی به سرویس شما را مجاز کنند.

اگر در Apps Script می‌سازید، می‌توانید از کتابخانه OAuth2 برای Apps Script (یا نسخه OAuth1)، استفاده کنید، جایی که تابع hasAccess بررسی می‌کند آیا کاربر دسترسی به سرویس را مجاز کرده است یا نه. یا اینکه هنگام استفاده از درخواست‌های UrlFetchApp.fetch می‌توانید پارامتر muteHttpExceptions را روی true تنظیم کنید تا کد پاسخ و محتوا را در شیء HttpResponse برگشتی بازرسی کنید.

کاربران را با کارت مجوز پایه مطلع کنید

وقتی برنامه Chat شما تشخیص می‌دهد که مجوز یا پیکربندی لازم است، پاسخ AuthorizationError برگردانید تا کارت مجوز پایه خصوصی به کاربر نمایش داده شود.

تصویر زیر نمونه‌ای از کارت مجوز پایه Google را نشان می‌دهد:

پیام‌واره مجوز پایه برای «حساب نمونه».
شکل ۱: پیام‌واره مجوز اولیه برای «حساب نمونه». در این پیام‌واره گفته می‌شود که برنامه Chat می‌خواهد اطلاعات بیشتری را نمایش دهد اما برای دسترسی به حساب به تأیید کاربر نیاز دارد.

برای درخواست از کاربران با کارت مجوز پایه، AuthorizationError شیء را برگردانید:

HTTP

پاسخ JSON زیر را برگردانید:

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

Apps Script

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

جایگزین کردن موارد زیر:

  • ‫AUTHORIZATION_URL: نشانی وب HTTPS برای برنامه وبی که احراز هویت، صدور مجوز، یا پیکربندی را مدیریت می‌کند.
  • RESOURCE_DISPLAY_NAME: نام نمایشی برای منبع یا سرویس محافظت‌شده. این نام در پیام‌واره مجوز به کاربر نمایش داده می‌شود. برای مثال، اگر RESOURCE_DISPLAY_NAME شما Example Account باشد، پیام‌واره می‌گوید که برنامه برای دسترسی به Example Account شما به تأیید نیاز دارد.

تکمیل درخواست پیکربندی

در Chat، کاربر می‌تواند فرایند صدور مجوز را تکمیل کند و بدون نیاز به بازآوری دستی، Chat به‌طور خودکار تعامل اصلی را دوباره امتحان کند. اگر راه‌انداز پیام، افزوده‌شده به فضا، یا فرمان برنامه باشد، Chat از تلاش مجدد خودکار پشتیبانی می‌کند.

برای این راه‌اندازها، برنامه Chat شما نشانی وب هدایت تکمیل (configCompleteRedirectUri / completeRedirectUri) را در بار رویداد دریافت می‌کند:

  • پیام: chat.messagePayload.configCompleteRedirectUri
  • به فضا اضافه شد: chat.addedToSpacePayload.configCompleteRedirectUri
  • فرمان برنامه: chat.appCommandPayload.configCompleteRedirectUri

باید این نشانی وب هدایت را در <var>AUTHORIZATION_URL</var> خود کدبندی کنید و پس‌از تکمیل جریان مجوزدهی، مرورگر کاربر را به آن هدایت کنید. هدایت به این نشانی وب به Google Chat نشان می‌دهد که درخواست مجوز یا پیکربندی انجام شده است.

وقتی کاربر باموفقیت به نشانی وب هدایت تکمیل ارائه‌شده در بار اصلی رویداد هدایت می‌شود، Google Chat مراحل زیر را انجام می‌دهد:

  1. پیام‌واره مجوز خصوصی نمایش‌داده‌شده به کاربر آغازگر را پاک می‌کند.
  2. پیام اصلی را به عمومی تبدیل می‌کند و آن را برای دیگر اعضای فضا قابل‌مشاهده می‌کند.
  3. برای بار دوم شیء رویداد اصلی را به برنامه Chat شما ارسال می‌کند.

اگر به نشانی وب هدایت تکمیل هدایت نکنید، کاربر همچنان می‌تواند جریان مجوز را تکمیل کند، اما Google Chat به‌طور خودکار اجرای قبلی را دوباره امتحان نمی‌کند و کاربر باید برنامه Chat شما را دوباره به‌صورت دستی فراخوانی کند.

بازدید از نشانی وب هدایت مجدد تکمیل فقط بر تعامل یک کاربر تأثیر می‌گذارد. اگر کاربری چندین بار به برنامه Chat پیام داده باشد و چندین پیام‌واره دریافت کرده باشد، تکمیل فرایند اصالت‌سنجی و پیکربندی برای یک پیام‌واره فقط آن تعامل خاص را دوباره امتحان می‌کند.

اصالت‌سنجی کاربر Chat در خارج از Chat

هنگام پیوند دادن به نشانی وب خارج از Chat (مثل بازخوان وب OAuth)، اغلب باید جلسه وب خارجی را با هویت کاربر در Chat همبستگی دهید. توصیه می‌کنیم از برنامه وب مقصد با ورود به سیستم با Google محافظت کنید.

از توکن هویت صادرشده درحین ورود به سیستم برای دریافت شناسه کاربر استفاده کنید. ادعای sub حاوی شناسه Google یکتای کاربر است و می‌تواند با نام منبع کاربر (chat.user.name) از Google Chat همبستگی داشته باشد.

برای مرتبط کردن ادعای sub با نام منبع users/{user} در Google Chat، مقدار ادعای sub را با users/ پیشوندگذاری کنید. برای مثال، sub مقدار ادعا 123 معادل users/123 در اشیای رویداد ارسالی به برنامه Chat شما است.

نمونه‌های کد

نمونه‌های کد زیر نشان می‌دهد که چگونه برنامه Chat می‌تواند بااستفاده از کارت مجوز پایه، اعتبارنامه‌های OAuth2 آفلاین درخواست کند، آن‌ها را در پایگاه داده ذخیره کند، به نشانی وب تکمیل هدایت کند، و با اصالت‌سنجی کاربر تماس‌های API برقرار کند:

برنامه‌های گپ که برافزا نیستند: برنامه Chat را به سرویس‌ها و ابزارهای دیگر متصل کنید

اگر برنامه Chat را که برافزای Google Workspace نیست نگهداری می‌کنید، برنامه Chat شما بااستفاده از actionResponse از نوع REQUEST_CONFIG پیکربندی را درخواست می‌کند و configCompleteRedirectUrl را از شیء Event سطح بالا می‌خواند.

برای ارتقا دادن برنامه Chat که برافزا نیست به چارچوب برافزاهای Google Workspace، به تبدیل برنامه Google Chat به برافزای Google Workspace مراجعه کنید.

درخواست پیکربندی از کاربری در برنامه Chat که برافزا نیست

در برنامه Chat که برافزا نیست، نشانی وب پیکربندی را در قالب زیر به کاربر برگردانید:

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

این دستور به Google Chat می‌گوید تا پیام‌واره خصوصی‌ای به کاربر ارائه دهد که در آن CONFIGURATION_URL پیوندی برای کاربر است تا برای اصالت‌سنجی، مجوز، یا پیکربندی بیشتر از آن بازدید کند. پاسخ REQUEST_CONFIG با پیام پاسخ معمولی متقابلاً انحصاری است؛ هرگونه نوشتار، کارت، یا ویژگی‌های دیگر نادیده گرفته می‌شود.

درخواست پیکربندی را در برنامه Chat که برافزا نیست تکمیل کنید

هر تعامل MESSAGE، ADDED_TO_SPACE، و APP_COMMAND Event که «برنامه گپ» که برافزا نیست دریافت می‌کند شامل فیلد سطح بالای configCompleteRedirectUrl می‌شود. این نشانی وب را در نشانی وب پیکربندی‌تان کدبندی کنید و پس‌از تکمیل، کاربر را به آن هدایت کنید تا Google Chat پیام‌واره را پاک کند، پیام اصلی را به عمومی تبدیل کند، و رویداد تعامل اصلی را به برنامه Chat شما بازارسال کند.

برای پیاده‌سازی‌های نمونه، نمونه برنامه اتصال‌پذیری Node.js و نمونه برنامه اصالت‌سنجی Python MyProfile در GitHub را ببینید.