احراز هویت و مجوز مکانیزم هایی هستند که به ترتیب برای تأیید هویت و دسترسی به منابع استفاده می شوند. این سند چگونگی کارکرد احراز هویت و مجوز برای برنامههای Chat و درخواستهای Chat API را شرح میدهد.
نمای کلی فرآیند
نمودار زیر مراحل سطح بالای احراز هویت و مجوز برای Google Chat را نشان می دهد:
![مراحل سطح بالا برای احراز هویت و مجوز چت Google](https://developers.google.com/static/workspace/chat/images/auth-process.png?hl=fa)
یک پروژه Google Cloud را پیکربندی کنید، Chat API را فعال کنید و برنامه Chat خود را پیکربندی کنید: در طول توسعه، یک پروژه Google Cloud ایجاد میکنید. در پروژه Google Cloud، Chat API را فعال میکنید، برنامه چت خود را پیکربندی میکنید و احراز هویت را تنظیم میکنید. برای اطلاعات بیشتر، به برنامه توسعه در Google Workspace و ساختن برنامه چت مراجعه کنید.
Call Chat API: وقتی برنامه شما با Chat API تماس می گیرد، اعتبارنامه احراز هویت را به Chat API ارسال می کند. اگر برنامه شما با یک حساب سرویس احراز هویت شود، اعتبارنامه به عنوان بخشی از کد برنامه شما ارسال می شود. اگر برنامه شما نیاز به تماس با Chat API با استفاده از احراز هویت کاربر دارد که هنوز اعطا نشده است، از کاربر میخواهد وارد سیستم شود.
درخواست منابع : برنامه شما درخواست دسترسی با محدوده هایی را می کند که هنگام تنظیم احراز هویت مشخص می کنید.
درخواست رضایت: اگر برنامه شما بهعنوان کاربر در حال احراز هویت است، Google صفحه رضایت OAuth را نشان میدهد تا کاربر بتواند تصمیم بگیرد که آیا برنامه شما به دادههای درخواستی دسترسی داشته باشد یا خیر. احراز هویت با حساب سرویس نیازی به رضایت کاربر ندارد.
ارسال درخواست تایید شده برای منابع: اگر کاربر با محدوده های مجوز موافقت کند، برنامه شما اعتبارنامه ها و دامنه های مورد تایید کاربر را در یک درخواست جمع می کند. درخواست برای دریافت رمز دسترسی به سرور مجوز Google ارسال می شود.
گوگل یک نشانه دسترسی را برمی گرداند: نشانه دسترسی حاوی لیستی از محدوده های اعطا شده است. اگر لیست بازگردانده شده محدودتر از محدوده های درخواستی باشد، برنامه شما هر ویژگی محدود شده توسط نشانه را خاموش می کند.
دسترسی به منابع درخواستی: برنامه شما از کد دسترسی Google برای فراخوانی Chat API و دسترسی به منابع Chat API استفاده میکند.
دریافت نشانه تازهسازی (اختیاری): اگر برنامه شما باید بیش از طول عمر یک نشانه دسترسی به Google Chat API دسترسی داشته باشد، میتواند یک نشانه تازهسازی دریافت کند. برای اطلاعات بیشتر، به استفاده از OAuth 2.0 برای دسترسی به Google API مراجعه کنید.
درخواست منابع بیشتر: اگر برنامه شما نیاز به دسترسی بیشتری داشته باشد، از کاربر میخواهد دامنههای جدیدی را اعطا کند و در نتیجه درخواست جدیدی برای دریافت نشانه دسترسی ایجاد میکند (مرحله 3-6).
وقتی برنامههای چت نیاز به احراز هویت دارند
برنامه های چت می توانند پیام هایی را در پاسخ به تعامل کاربر یا به صورت ناهمزمان ارسال کنند. آنها همچنین میتوانند وظایفی را از طرف یک کاربر انجام دهند، مانند ایجاد فضای چت یا دریافت لیستی از افراد در فضای چت.
برنامههای گپ برای پاسخ به تعامل کاربر نیازی به احراز هویت ندارند، مگر اینکه برنامه Chat هنگام پردازش پاسخ ، Chat API یا Google API دیگری را فراخوانی کند.
برای ارسال پیامهای ناهمزمان یا انجام وظایف از طرف یک کاربر، برنامههای چت درخواستهای RESTful را به Chat API ارائه میکنند که نیاز به احراز هویت و مجوز دارند.
پاسخ به تعاملات کاربر نیازی به احراز هویت ندارد
برنامههای گپ Google برای دریافت و پاسخ همزمان به رویدادهای تعامل، نیازی به احراز هویت به عنوان کاربر یا برنامه چت ندارند.
برنامههای گپ Google هر زمان که کاربر با یک برنامه گپ تعامل یا فراخوانی میکند رویدادهای تعاملی را دریافت میکنند، از جمله موارد زیر:
- یک کاربر به یک برنامه چت پیامی ارسال می کند.
- یک کاربر @ از یک برنامه Chat نام می برد.
- کاربر یکی از دستورات اسلش برنامه Chat را فراخوانی می کند.
نمودار زیر یک توالی درخواست-پاسخ بین کاربر چت و برنامه چت را نشان می دهد:
![برای رویدادهای تعامل برنامه گپ نیازی به مجوز نیست](https://developers.google.com/static/workspace/chat/images/auth-synchronous.png?hl=fa)
- کاربر پیامی به برنامه چت در گپ Google ارسال می کند.
- Google Chat پیام را به برنامه فوروارد می کند.
- برنامه پیام را دریافت میکند، آن را پردازش میکند و پاسخی را به Google Chat برمیگرداند.
- Google Chat پاسخ را برای کاربر یا در یک فضا ارائه می دهد.
این دنباله برای هر رویداد تعامل برنامه چت تکرار می شود.
پیام های ناهمزمان نیاز به احراز هویت دارند
پیامهای ناهمزمان زمانی رخ میدهند که یک برنامه گپ درخواستی را به Chat API ارسال میکند که به احراز هویت و مجوز نیاز دارد.
با تماس با Chat API، برنامههای چت میتوانند پیامهایی را به چت Google ارسال کنند یا وظایف را تکمیل کنند و از طرف کاربر به دادهها دسترسی داشته باشند. به عنوان مثال، پس از تشخیص قطعی سرور، یک برنامه چت می تواند Chat API را به این موارد فراخوانی کند:
- یک فضای چت اختصاص داده شده برای بررسی و رفع قطعی ایجاد کنید.
- افراد را به فضای چت اضافه کنید.
- برای ارائه جزئیات در مورد قطع، یک پیام به فضای چت ارسال کنید.
نمودار زیر یک توالی پیام ناهمزمان بین یک برنامه چت و یک فضای چت را نشان می دهد:
![برای پیام های ناهمزمان احراز هویت لازم است](https://developers.google.com/static/workspace/chat/images/auth-asynchronous.png?hl=fa)
- یک برنامه چت با فراخوانی Chat API با استفاده از روش
spaces.messages.create
پیامی ایجاد میکند و اطلاعات کاربری کاربر را در درخواست HTTP شامل میشود. - Google Chat برنامه Chat را با حساب سرویس یا اطلاعات کاربری کاربر احراز هویت می کند.
- Google Chat پیام برنامه را در یک فضای چت مشخص ارائه می کند.
حوزه های API چت
صفحه رضایت OAuth را پیکربندی کنید و دامنه ها را انتخاب کنید تا مشخص کنید چه اطلاعاتی برای کاربران و بازبینان برنامه نمایش داده می شود و برنامه خود را ثبت کنید تا بتوانید بعداً آن را منتشر کنید.
برای تعریف سطح دسترسی اعطا شده به برنامه خود، باید محدوده های مجوز را شناسایی و اعلام کنید. محدوده مجوز یک رشته URI OAuth 2.0 است که حاوی نام برنامه Google Workspace، نوع دادههایی است که به آن دسترسی دارد و سطح دسترسی.
محدوده های غیر حساس
کد محدوده | توضیحات |
---|---|
https://www.googleapis.com/auth/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.spaces | چت و فضاهای متعلق به دامنه سرپرست را در چت مشاهده یا ویرایش کنید. |
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 | مکالمات و فضاهای متعلق به دامنه سرپرست را حذف کنید و دسترسی به فایلهای مرتبط را در چت حذف کنید. |
محدوده های موجود در جداول قبل حساسیت آنها را با توجه به تعاریف زیر نشان می دهد:
غیر حساس - این حوزهها کوچکترین حوزه دسترسی مجوز را فراهم میکنند و فقط به تأیید اولیه برنامه نیاز دارند. برای کسب اطلاعات در مورد این الزام، به مراحل آماده شدن برای تأیید مراجعه کنید.
حساس — این محدودهها پس از دریافت مجوز از کاربر، دسترسی برنامه شما به دادههای Google یک کاربر خاص را فراهم میکنند. از شما میخواهد تا از تأیید برنامه اضافی عبور کنید. برای کسب اطلاعات در مورد این نیاز، به مراحل برنامههایی که دامنههای حساس را درخواست میکنند، مراجعه کنید.
محدود — این محدودهها دسترسی گستردهای به دادههای کاربر Google را فراهم میکنند و از شما میخواهند که فرآیند تأیید محدوده محدود را طی کنید. برای کسب اطلاعات در مورد این نیاز، به خدمات Google API مراجعه کنید: خطمشی دادههای کاربر و الزامات اضافی برای محدودههای API خاص . همچنین مراحل برنامه های درخواست کننده محدوده محدود را ببینید.
اگر برنامه شما نیاز به دسترسی به سایر 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 و حوزههای مجوز پشتیبانی شده آنها را فهرست میکند:
روش | احراز هویت کاربر پشتیبانی می شود | تأیید اعتبار برنامه پشتیبانی می شود | دامنه مجوز پشتیبانی می شود | |
---|---|---|---|---|
فضاها | ||||
یک فضا ایجاد کنید | - | با احراز هویت کاربر :
| ||
فضایی را تنظیم کنید | - | با احراز هویت کاربر :
| ||
فضا بگیر | با احراز هویت کاربر :
| |||
فهرست فضاها | با احراز هویت کاربر :
| |||
فضاهای جستجو | با احراز هویت کاربر با استفاده از امتیازات مدیر:
| |||
یک فضا را به روز کنید | - | با احراز هویت کاربر :
| ||
یک فاصله را حذف کنید | - | با احراز هویت کاربر :
| ||
فرآیند واردات یک فضا را تکمیل کنید | - | با احراز هویت کاربر :
| ||
یک پیام مستقیم پیدا کنید | با احراز هویت کاربر :
| |||
اعضا | ||||
یک عضو ایجاد کنید | - | با احراز هویت کاربر :
| ||
عضو بگیر | با احراز هویت کاربر :
| |||
لیست اعضا | با احراز هویت کاربر :
| |||
حذف یک عضو | - | با احراز هویت کاربر :
| ||
یک عضو را به روز کنید | - | با احراز هویت کاربر :
| ||
پیام ها | ||||
یک پیام ایجاد کنید | با احراز هویت کاربر :
| |||
یک پیام دریافت کنید | با احراز هویت کاربر :
| |||
لیست پیام ها | - | با احراز هویت کاربر :
| ||
یک پیام را به روز کنید | با احراز هویت کاربر :
| |||
یک پیام را حذف کنید | با احراز هویت کاربر :
| |||
واکنش ها | ||||
واکنش ایجاد کنید | - | با احراز هویت کاربر :
| ||
واکنش ها را فهرست کنید | - | با احراز هویت کاربر :
| ||
یک واکنش را حذف کنید | - | با احراز هویت کاربر :
| ||
رسانه و پیوست | ||||
رسانه را به عنوان پیوست فایل آپلود کنید | - | با احراز هویت کاربر :
| ||
دانلود رسانه | با احراز هویت کاربر :
| |||
یک پیوست پیام دریافت کنید | - | با احراز هویت برنامه :
| ||
وضعیت خواندن کاربر | ||||
وضعیت خواندن فضای کاربر را دریافت کنید | - | با احراز هویت کاربر :
| ||
وضعیت خواندن فضای کاربر را به روز کنید | - | با احراز هویت کاربر :
| ||
وضعیت خواندن موضوع یک کاربر را دریافت کنید | - | با احراز هویت کاربر :
| ||
رویدادهای فضایی | ||||
رویدادهای فضایی را دریافت کنید | - | با احراز هویت کاربر ، باید از یک محدوده بر اساس نوع رویداد استفاده کنید:
| ||
فهرست رویدادهای فضایی | - | با احراز هویت کاربر ، باید از یک محدوده برای هر نوع رویداد موجود در درخواست استفاده کنید:
|
برای رویدادهای تعامل برنامه چت
جدول زیر روشهای متداول تعامل کاربران با برنامههای چت و اینکه آیا احراز هویت مورد نیاز است یا پشتیبانی میشود را فهرست میکند:
سناریو | بدون نیاز به احراز هویت | احراز هویت کاربر پشتیبانی می شود | تأیید اعتبار برنامه پشتیبانی می شود | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
دریافت پیام از: |
| |||||||||||||||
پاسخ به پیام ها: |
| |||||||||||||||
ارسال پیام های جدید: |
|
موضوعات مرتبط
- برای مرور کلی احراز هویت و مجوز در Google Workspace، به اطلاعاتی درباره احراز هویت و مجوز مراجعه کنید.
- برای مرور کلی احراز هویت و مجوز در Google Cloud، به نمای کلی احراز هویت مراجعه کنید.
- برای کسب اطلاعات بیشتر درباره حسابهای خدمات، به حسابهای خدمات مراجعه کنید.
- برای کسب اطلاعات بیشتر در مورد اینکه چگونه API های Google از OAuth 2.0 استفاده می کنند، به استفاده از OAuth 2.0 برای دسترسی به Google API مراجعه کنید.
- احراز هویت و مجوز را با اعتبار کاربری یا یک حساب سرویس تنظیم کنید.