برنامه‌های Chat و درخواست‌های Google Chat API را تأیید و تأیید کنید

احراز هویت و مجوز مکانیزم هایی هستند که به ترتیب برای تأیید هویت و دسترسی به منابع استفاده می شوند. این سند چگونگی کارکرد احراز هویت و مجوز برای برنامه‌های Chat و درخواست‌های Chat API را شرح می‌دهد.

نمای کلی فرآیند

نمودار زیر مراحل سطح بالای احراز هویت و مجوز برای Google Chat را نشان می دهد:

مراحل سطح بالا برای احراز هویت و مجوز چت Google
شکل 1. مراحل سطح بالا برای احراز هویت و مجوز چت Google.

  1. یک پروژه Google Cloud را پیکربندی کنید، Chat API را فعال کنید و برنامه Chat خود را پیکربندی کنید: در طول توسعه، یک پروژه Google Cloud ایجاد می‌کنید. در پروژه Google Cloud، Chat API را فعال می‌کنید، برنامه چت خود را پیکربندی می‌کنید و احراز هویت را تنظیم می‌کنید. برای اطلاعات بیشتر، به برنامه توسعه در Google Workspace و ساختن برنامه چت مراجعه کنید.

  2. Call Chat API: وقتی برنامه شما با Chat API تماس می گیرد، اعتبارنامه احراز هویت را به Chat API ارسال می کند. اگر برنامه شما با یک حساب سرویس احراز هویت شود، اعتبارنامه به عنوان بخشی از کد برنامه شما ارسال می شود. اگر برنامه شما نیاز به تماس با Chat API با استفاده از احراز هویت کاربر دارد که هنوز اعطا نشده است، از کاربر می‌خواهد وارد سیستم شود.

  3. درخواست منابع : برنامه شما درخواست دسترسی با محدوده هایی را می کند که هنگام تنظیم احراز هویت مشخص می کنید.

  4. درخواست رضایت: اگر برنامه شما به‌عنوان کاربر در حال احراز هویت است، Google صفحه رضایت OAuth را نشان می‌دهد تا کاربر بتواند تصمیم بگیرد که آیا برنامه شما به داده‌های درخواستی دسترسی داشته باشد یا خیر. احراز هویت با حساب سرویس نیازی به رضایت کاربر ندارد.

  5. ارسال درخواست تایید شده برای منابع: اگر کاربر با محدوده های مجوز موافقت کند، برنامه شما اعتبارنامه ها و دامنه های مورد تایید کاربر را در یک درخواست جمع می کند. درخواست برای دریافت رمز دسترسی به سرور مجوز Google ارسال می شود.

  6. گوگل یک نشانه دسترسی را برمی گرداند: نشانه دسترسی حاوی لیستی از محدوده های اعطا شده است. اگر لیست بازگردانده شده محدودتر از محدوده های درخواستی باشد، برنامه شما هر ویژگی محدود شده توسط نشانه را خاموش می کند.

  7. دسترسی به منابع درخواستی: برنامه شما از کد دسترسی Google برای فراخوانی Chat API و دسترسی به منابع Chat API استفاده می‌کند.

  8. دریافت نشانه تازه‌سازی (اختیاری): اگر برنامه شما باید بیش از طول عمر یک نشانه دسترسی به Google Chat API دسترسی داشته باشد، می‌تواند یک نشانه تازه‌سازی دریافت کند. برای اطلاعات بیشتر، به استفاده از OAuth 2.0 برای دسترسی به Google API مراجعه کنید.

  9. درخواست منابع بیشتر: اگر برنامه شما نیاز به دسترسی بیشتری داشته باشد، از کاربر می‌خواهد دامنه‌های جدیدی را اعطا کند و در نتیجه درخواست جدیدی برای دریافت نشانه دسترسی ایجاد می‌کند (مرحله 3-6).

وقتی برنامه‌های چت نیاز به احراز هویت دارند

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

برنامه‌های گپ برای پاسخ به تعامل کاربر نیازی به احراز هویت ندارند، مگر اینکه برنامه Chat هنگام پردازش پاسخ ، Chat API یا Google API دیگری را فراخوانی کند.

برای ارسال پیام‌های ناهمزمان یا انجام وظایف از طرف یک کاربر، برنامه‌های چت درخواست‌های RESTful را به Chat API ارائه می‌کنند که نیاز به احراز هویت و مجوز دارند.

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

برنامه‌های گپ Google برای دریافت و پاسخ همزمان به رویدادهای تعامل، نیازی به احراز هویت به عنوان کاربر یا برنامه چت ندارند.

برنامه‌های گپ Google هر زمان که کاربر با یک برنامه گپ تعامل یا فراخوانی می‌کند رویدادهای تعاملی را دریافت می‌کنند، از جمله موارد زیر:

  • یک کاربر به یک برنامه چت پیامی ارسال می کند.
  • یک کاربر @ از یک برنامه Chat نام می برد.
  • کاربر یکی از دستورات اسلش برنامه Chat را فراخوانی می کند.

نمودار زیر یک توالی درخواست-پاسخ بین کاربر چت و برنامه چت را نشان می دهد:

برای رویدادهای تعامل برنامه گپ نیازی به مجوز نیست
شکل 2. رویدادهای تعامل برنامه چت نیازی به احراز هویت ندارند.

  1. کاربر پیامی به برنامه چت در گپ Google ارسال می کند.
  2. Google Chat پیام را به برنامه فوروارد می کند.
  3. برنامه پیام را دریافت می‌کند، آن را پردازش می‌کند و پاسخی را به Google Chat برمی‌گرداند.
  4. Google Chat پاسخ را برای کاربر یا در یک فضا ارائه می دهد.

این دنباله برای هر رویداد تعامل برنامه چت تکرار می شود.

پیام های ناهمزمان نیاز به احراز هویت دارند

پیام‌های ناهمزمان زمانی رخ می‌دهند که یک برنامه گپ درخواستی را به Chat API ارسال می‌کند که به احراز هویت و مجوز نیاز دارد.

با تماس با Chat API، برنامه‌های چت می‌توانند پیام‌هایی را به چت Google ارسال کنند یا وظایف را تکمیل کنند و از طرف کاربر به داده‌ها دسترسی داشته باشند. به عنوان مثال، پس از تشخیص قطعی سرور، یک برنامه چت می تواند Chat API را به این موارد فراخوانی کند:

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

نمودار زیر یک توالی پیام ناهمزمان بین یک برنامه چت و یک فضای چت را نشان می دهد:

برای پیام های ناهمزمان احراز هویت لازم است
شکل 3. پیام های ناهمزمان نیاز به احراز هویت دارند.

  1. یک برنامه چت با فراخوانی Chat API با استفاده از روش spaces.messages.create پیامی ایجاد می‌کند و اطلاعات کاربری کاربر را در درخواست HTTP شامل می‌شود.
  2. Google Chat برنامه Chat را با حساب سرویس یا اطلاعات کاربری کاربر احراز هویت می کند.
  3. Google Chat پیام برنامه را در یک فضای چت مشخص ارائه می کند.

حوزه های API چت

صفحه رضایت OAuth را پیکربندی کنید و دامنه ها را انتخاب کنید تا مشخص کنید چه اطلاعاتی برای کاربران و بازبینان برنامه نمایش داده می شود و برنامه خود را ثبت کنید تا بتوانید بعداً آن را منتشر کنید.

برای تعریف سطح دسترسی اعطا شده به برنامه خود، باید محدوده های مجوز را شناسایی و اعلام کنید. محدوده مجوز یک رشته URI OAuth 2.0 است که حاوی نام برنامه Google Workspace، نوع داده‌هایی است که به آن دسترسی دارد و سطح دسترسی.

محدوده های غیر حساس

کد محدوده شرح
https://www.googleapis.com/auth/chat.bot

محدوده chat.bot فقط از حساب های سرویس پشتیبانی می کند. با استفاده از این محدوده نمی‌توانید با اعتبار کاربری یا با تفویض اختیار در سطح دامنه احراز هویت کنید.

به برنامه‌های چت اجازه می‌دهد چت‌ها را مشاهده کرده و پیام ارسال کنند. به همه ویژگی‌های موجود در برنامه‌های چت دسترسی می‌دهد.

محدوده های حساس

کد محدوده شرح
https://www.googleapis.com/auth/chat.spaces مکالمات و فضاها ایجاد کنید و متادیتا (از جمله تنظیمات سابقه و تنظیمات دسترسی) را در چت مشاهده یا ویرایش کنید.
https://www.googleapis.com/auth/chat.spaces.create مکالمات جدید در چت ایجاد کنید.
https://www.googleapis.com/auth/chat.spaces.readonly چت و فضاهای موجود در چت را مشاهده کنید.
https://www.googleapis.com/auth/chat.memberships مشاهده، افزودن، به‌روزرسانی و حذف اعضا از مکالمات در چت.
https://www.googleapis.com/auth/chat.memberships.app اضافه کردن و حذف خود از مکالمات در Google Chat.
https://www.googleapis.com/auth/chat.memberships.readonly مشاهده اعضا در مکالمات چت.
https://www.googleapis.com/auth/chat.messages.create در چت پیام بنویسید و ارسال کنید.
https://www.googleapis.com/auth/chat.messages.reactions مشاهده، افزودن و حذف واکنش‌ها به پیام‌ها در چت.
https://www.googleapis.com/auth/chat.messages.reactions.create واکنش‌ها را به یک پیام در چت اضافه کنید.
https://www.googleapis.com/auth/chat.messages.reactions.readonly مشاهده واکنش‌ها به یک پیام در چت.
https://www.googleapis.com/auth/chat.users.readstate آخرین زمان خواندن مکالمات چت را مشاهده و تغییر دهید.
https://www.googleapis.com/auth/chat.users.readstate.readonly آخرین زمان خواندن مکالمات چت را مشاهده کنید.
https://www.googleapis.com/auth/chat.admin.spaces.readonly چت و فضاهای متعلق به دامنه سرپرست را در چت مشاهده کنید.
https://www.googleapis.com/auth/chat.admin.memberships.readonly اعضا و مدیران را در گفتگوهای متعلق به دامنه سرپرست در چت مشاهده کنید.
https://www.googleapis.com/auth/chat.admin.memberships مشاهده، افزودن، به‌روزرسانی و حذف اعضا و مدیران در مکالمه‌های متعلق به دامنه سرپرست در گپ.

محدوده های محدود

کد محدوده شرح
https://www.googleapis.com/auth/chat.delete مکالمات و فضاها را حذف کنید و دسترسی به فایل‌های مرتبط را در چت حذف کنید.
https://www.googleapis.com/auth/chat.import فضاها، پیام‌ها و عضویت‌ها را به چت وارد کنید. برای اطلاعات بیشتر، به مجوز برنامه‌های چت برای وارد کردن داده‌ها مراجعه کنید
https://www.googleapis.com/auth/chat.messages مشاهده، نوشتن، ارسال، به‌روزرسانی و حذف پیام‌ها و افزودن، مشاهده و حذف واکنش‌ها به پیام‌ها.
https://www.googleapis.com/auth/chat.messages.readonly پیام ها و واکنش ها را در چت مشاهده کنید.
https://www.googleapis.com/auth/chat.admin.delete مکالمات و فضاهای متعلق به دامنه سرپرست را حذف کنید و دسترسی به فایل‌های مرتبط را در چت حذف کنید.

محدوده های موجود در جداول قبل حساسیت آنها را با توجه به تعاریف زیر نشان می دهد:

اگر برنامه شما نیاز به دسترسی به سایر APIهای Google دارد، می‌توانید آن محدوده‌ها را نیز اضافه کنید. برای اطلاعات بیشتر در مورد دامنه های Google API، به استفاده از OAuth 2.0 برای دسترسی به Google API مراجعه کنید.

برای کسب اطلاعات بیشتر درباره دامنه‌های APIهای Google Workspace، به پیکربندی صفحه رضایت OAuth مراجعه کنید و دامنه‌ها را انتخاب کنید .

انواع احراز هویت مورد نیاز

دو راه وجود دارد که برنامه‌های چت می‌توانند با Chat API احراز هویت و تأیید اعتبار کنند: اعتبار کاربر یا حساب‌های سرویس.

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

با مجوز برنامه ، یک برنامه Chat با استفاده از اعتبار حساب سرویس به عنوان یک برنامه به API دسترسی پیدا می کند. مجوز برنامه همیشه از محدوده مجوز chat.bot استفاده می کند.

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

  • با مجوز برنامه، روش‌ها فقط منابعی را برمی‌گردانند که برنامه می‌تواند به آنها دسترسی داشته باشد.
  • با مجوز کاربر، روش‌ها فقط منابعی را برمی‌گردانند که کاربر می‌تواند در رابط کاربری چت به آنها دسترسی داشته باشد.

به عنوان مثال، فراخوانی متد ListSpaces با مجوز برنامه، فهرست فضاهایی را که برنامه در آن عضو است، برمی‌گرداند. فراخوانی ListSpaces با مجوز کاربر، فهرست فضاهایی را که کاربر در آن عضو است، برمی گرداند. در عمل، بسته به عملکردی که می‌خواهید، برنامه شما ممکن است از هر دو نوع مجوز هنگام تماس با Chat API استفاده کند.

برای تماس‌های ناهمزمان Chat API

جدول زیر متدهای Chat API و حوزه‌های مجوز پشتیبانی شده آنها را فهرست می‌کند:

روش احراز هویت کاربر پشتیبانی می شود تأیید اعتبار برنامه پشتیبانی می شود دامنه مجوز پشتیبانی می شود
فضاها
یک فضا ایجاد کنید - با احراز هویت کاربر :
  • chat.spaces.create
  • chat.spaces
  • chat.import
فضایی را تنظیم کنید - با احراز هویت کاربر :
  • chat.spaces.create
  • chat.spaces
فضا بگیر با احراز هویت کاربر :
  • chat.spaces.readonly
  • chat.spaces
با احراز هویت برنامه :
  • chat.bot
فهرست فضاها با احراز هویت کاربر :
  • chat.spaces.readonly
  • chat.spaces
با احراز هویت برنامه :
  • chat.bot
فضاهای جستجو با احراز هویت کاربر با استفاده از امتیازات مدیر:
  • chat.admin.spaces.readonly
یک فضا را به روز کنید - با احراز هویت کاربر :
  • chat.spaces
  • chat.import
یک فاصله را حذف کنید - با احراز هویت کاربر :
  • 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.memberships.readonly
  • chat.memberships
  • chat.import
با احراز هویت برنامه :
  • chat.bot
با احراز هویت کاربر با استفاده از امتیازات مدیر:
  • chat.admin.memberships.readonly
حذف یک عضو - با احراز هویت کاربر :
  • chat.memberships
  • chat.memberships.app
  • 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.memberships
  • chat.memberships.readonly
  • chat.spaces
  • chat.spaces.readonly
فهرست رویدادهای فضایی - با احراز هویت کاربر :
  • chat.messages
  • chat.messages.readonly
  • chat.messages.reactions
  • chat.messages.reactions.readonly
  • chat.memberships
  • chat.memberships.readonly
  • chat.spaces
  • chat.spaces.readonly

برای رویدادهای تعامل برنامه چت

جدول زیر روش‌های متداول تعامل کاربران با برنامه‌های چت و اینکه آیا احراز هویت مورد نیاز است یا پشتیبانی می‌شود را فهرست می‌کند:

سناریو بدون نیاز به احراز هویت احراز هویت کاربر پشتیبانی می شود تأیید اعتبار برنامه پشتیبانی می شود
دریافت پیام از:
رویدادهای تعامل برنامه چت - -
تماس‌های اسکریپت برنامه‌ها - -
Google Cloud Pub/Sub - -
پاسخگویی به پیام ها:
به طور همزمان، با استفاده از رویداد تعامل برنامه چت - -
به طور همزمان، با استفاده از یک مقدار بازگشت به تماس Apps Script - -
ارسال پیام های جدید:
با وب هوک های ورودی - -