احراز هویت و مجوز، به ترتیب مکانیسمهایی هستند که برای تأیید هویت و دسترسی به منابع استفاده میشوند. این سند نحوه عملکرد احراز هویت و مجوز برای برنامههای چت و درخواستهای API چت را شرح میدهد.
مرور کلی فرآیند
نمودار زیر مراحل سطح بالای احراز هویت و مجوز برای گوگل چت را نشان میدهد:
پیکربندی یک پروژه Google Cloud، فعال کردن Chat API و پیکربندی برنامه چت شما: در طول توسعه، شما یک پروژه Google Cloud ایجاد میکنید. در پروژه Google Cloud، Chat API را فعال میکنید، برنامه چت خود را پیکربندی میکنید و احراز هویت را تنظیم میکنید. برای اطلاعات بیشتر، به بخش توسعه در Google Workspace و ساخت یک برنامه چت مراجعه کنید.
فراخوانی API چت: وقتی برنامه شما API چت را فراخوانی میکند، اعتبارنامههای احراز هویت را به API چت ارسال میکند. اگر برنامه شما با یک حساب کاربری سرویس احراز هویت شود، اعتبارنامهها به عنوان بخشی از کد برنامه شما ارسال میشوند. اگر برنامه شما نیاز به فراخوانی API چت با استفاده از احراز هویت کاربری که هنوز اعطا نشده است، داشته باشد، از کاربر میخواهد که وارد سیستم شود.
درخواست منابع : برنامه شما درخواست دسترسی به محدودههایی را میکند که هنگام تنظیم احراز هویت مشخص کردهاید.
درخواست رضایت: اگر برنامه شما به عنوان کاربر احراز هویت میشود، گوگل صفحه رضایت OAuth را نمایش میدهد تا کاربر بتواند تصمیم بگیرد که آیا به برنامه شما اجازه دسترسی به دادههای درخواستی را بدهد یا خیر. احراز هویت با یک حساب کاربری سرویس نیازی به رضایت کاربر ندارد.
ارسال درخواست تأیید شده برای منابع: اگر کاربر با محدودههای مجوز موافقت کند، برنامه شما اعتبارنامهها و محدودههای تأیید شده توسط کاربر را در یک درخواست قرار میدهد. این درخواست برای دریافت یک توکن دسترسی به سرور مجوز گوگل ارسال میشود.
گوگل یک توکن دسترسی برمیگرداند: توکن دسترسی شامل فهرستی از حوزههای اعطا شده است. اگر فهرست حوزههای بازگردانده شده محدودتر از حوزههای درخواستی باشد، برنامه شما هر ویژگی محدود شده توسط توکن را غیرفعال میکند.
دسترسی به منابع درخواستی: برنامه شما از توکن دسترسی گوگل برای فراخوانی API چت و دسترسی به منابع API چت استفاده میکند.
دریافت توکن بهروزرسانی (اختیاری): اگر برنامه شما باید فراتر از طول عمر یک توکن دسترسی واحد به API چت گوگل دسترسی داشته باشد، میتواند یک توکن بهروزرسانی دریافت کند. برای اطلاعات بیشتر، به بخش «استفاده از OAuth 2.0 برای دسترسی به APIهای گوگل» مراجعه کنید.
درخواست منابع بیشتر: اگر برنامه شما به دسترسی بیشتری نیاز داشته باشد، از کاربر میخواهد که محدودههای جدیدی را اعطا کند و در نتیجه درخواست جدیدی برای دریافت توکن دسترسی ارسال میشود (مراحل ۳ تا ۶).
وقتی برنامههای چت نیاز به احراز هویت دارند
برنامههای چت میتوانند پیامها را در پاسخ به تعامل کاربر یا به صورت غیرهمزمان ارسال کنند. آنها همچنین میتوانند وظایفی را از طرف کاربر انجام دهند، مانند ایجاد یک فضای چت یا دریافت لیستی از افراد در یک فضای چت.
برنامههای چت برای پاسخ به تعامل کاربر نیازی به احراز هویت ندارند، مگر اینکه برنامه چت هنگام پردازش پاسخ، API چت یا یکی دیگر از APIهای گوگل را فراخوانی کند.
برای ارسال پیامهای غیرهمزمان یا انجام وظایف از طرف کاربر، برنامههای چت درخواستهای RESTful را به API چت ارسال میکنند که نیاز به احراز هویت و مجوز دارند.
پاسخها به تعاملات کاربر نیازی به احراز هویت ندارند
برنامههای چت گوگل برای دریافت و پاسخ همزمان به رویدادهای تعاملی، نیازی به احراز هویت به عنوان کاربر یا برنامه چت ندارند.
برنامههای چت گوگل هر زمان که کاربر با یک برنامه چت تعامل داشته باشد یا آن را فراخوانی کند، رویدادهای تعاملی دریافت میکنند، از جمله موارد زیر:
- یک کاربر پیامی را به یک برنامه چت ارسال میکند.
- یک کاربر یک برنامه چت را @mention میکند.
- کاربر یکی از دستورات برنامه چت را فراخوانی میکند.
نمودار زیر توالی درخواست-پاسخ بین یک کاربر چت و برنامه چت را نشان میدهد:
- کاربر پیامی را به برنامه چت در گوگل چت ارسال میکند.
- گوگل چت پیام را به برنامه فوروارد میکند.
- برنامه پیام را دریافت میکند، آن را پردازش میکند و پاسخی را به Google Chat برمیگرداند.
- گوگل چت پاسخ را برای کاربر یا در یک فضای خالی رندر میکند.
این توالی برای هر رویداد تعامل برنامه چت تکرار میشود.
پیامهای ناهمزمان نیاز به احراز هویت دارند
پیامهای ناهمزمان زمانی رخ میدهند که یک برنامه چت درخواستی را به API چت ارسال میکند که نیاز به احراز هویت و مجوز دارد.
با فراخوانی Chat API، برنامههای چت میتوانند پیامهایی را به Google Chat ارسال کنند یا وظایف را انجام دهند و به دادهها از طرف کاربر دسترسی پیدا کنند. به عنوان مثال، پس از تشخیص قطعی سرور، یک برنامه چت میتواند Chat API را برای موارد زیر فراخوانی کند:
- یک فضای چت اختصاصی برای بررسی و رفع قطعی برق ایجاد کنید.
- افراد را به فضای چت اضافه کنید.
- برای ارائه جزئیات مربوط به قطعی، پیامی را در فضای چت ارسال کنید.
نمودار زیر یک توالی پیام ناهمزمان بین یک برنامه چت و یک فضای چت را نشان میدهد:
- یک برنامه چت با فراخوانی API چت با استفاده از متد
spaces.messages.createپیامی ایجاد میکند و اطلاعات کاربری را در درخواست HTTP لحاظ میکند. - گوگل چت، برنامه چت را با حساب کاربری یا اطلاعات کاربری سرویس، احراز هویت میکند.
- گوگل چت پیام برنامه را در یک فضای چت مشخص شده رندر میکند.
دامنههای 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 | خودش را به مکالمات در گوگل چت اضافه و حذف میکند. |
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.app.spaces | ایجاد مکالمات و فضاها و مشاهده یا بهروزرسانی فرادادهها (از جمله تنظیمات تاریخچه و تنظیمات دسترسی) در «چت به عنوان یک برنامه چت». نیاز به تأیید مدیر دارد. این محدوده فقط از احراز هویت برنامه با حسابهای سرویس پشتیبانی میکند. شما نمیتوانید با استفاده از این محدوده، با اعتبارنامههای کاربر یا با واگذاری اختیار در سطح دامنه، احراز هویت کنید. |
https://www.googleapis.com/auth/chat.app.spaces.create | ایجاد مکالمات و فضاهای جدید در «چت به عنوان برنامه چت». نیاز به تأیید مدیر دارد. این محدوده فقط از احراز هویت برنامه با حسابهای سرویس پشتیبانی میکند. شما نمیتوانید با استفاده از این محدوده، با اعتبارنامههای کاربر یا با واگذاری اختیار در سطح دامنه، احراز هویت کنید. |
https://www.googleapis.com/auth/chat.app.memberships | مشاهده، اضافه کردن، بهروزرسانی و حذف اعضا از مکالمات و فضاهای موجود در «چت به عنوان یک برنامه چت». نیاز به تأیید مدیر دارد. این محدوده فقط از احراز هویت برنامه با حسابهای سرویس پشتیبانی میکند. شما نمیتوانید با استفاده از این محدوده، با اعتبارنامههای کاربر یا با واگذاری اختیار در سطح دامنه، احراز هویت کنید. |
https://www.googleapis.com/auth/chat.customemojis | مشاهده، ایجاد و حذف ایموجیهای سفارشی در چت. |
https://www.googleapis.com/auth/chat.customemojis.readonly | مشاهده ایموجیهای سفارشی در چت. |
https://www.googleapis.com/auth/chat.users.spacesettings | تنظیمات فضای کاربری چت را مشاهده و بهروزرسانی کنید. |
دامنههای محدود
| کد محدوده | توضیحات |
|---|---|
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.app.messages.readonly | مشاهده پیامها و واکنشها در چت به عنوان یک برنامه چت. نیاز به تأیید مدیر دارد. این محدوده فقط از احراز هویت برنامه با حسابهای سرویس پشتیبانی میکند. شما نمیتوانید با استفاده از این محدوده، با اعتبارنامههای کاربر یا با واگذاری اختیار در سطح دامنه، احراز هویت کنید. |
https://www.googleapis.com/auth/chat.admin.delete | مکالمات و فضاهای متعلق به دامنه مدیر را حذف کنید و دسترسی به فایلهای مرتبط در چت را لغو کنید. |
https://www.googleapis.com/auth/chat.app.delete | مکالمات و فاصلهها را حذف کنید و دسترسی به فایلهای مرتبط را در «چت به عنوان یک برنامه چت» لغو کنید. نیاز به تأیید مدیر دارد. این محدوده فقط از احراز هویت برنامه با حسابهای سرویس پشتیبانی میکند. شما نمیتوانید با استفاده از این محدوده، با اعتبارنامههای کاربر یا با واگذاری اختیار در سطح دامنه، احراز هویت کنید. |
محدودههای موجود در جداول قبلی، حساسیت آنها را طبق تعاریف زیر نشان میدهند:
غیرحساس - این حوزهها کوچکترین حوزه دسترسی مجوز را فراهم میکنند و فقط به تأیید اولیه برنامه نیاز دارند. برای اطلاعات در مورد این الزام، به مراحل آمادهسازی برای تأیید مراجعه کنید.
حساس - این محدودهها پس از دریافت مجوز از کاربر، به برنامه شما امکان دسترسی به دادههای گوگل یک کاربر خاص را میدهند. این امر مستلزم انجام مراحل تأیید اضافی برنامه است. برای اطلاعات بیشتر در مورد این الزام، به مراحل درخواست محدودههای حساس برای برنامهها مراجعه کنید.
محدود شده - این محدودهها دسترسی گستردهای به دادههای کاربر گوگل ارائه میدهند و شما را ملزم به طی کردن فرآیند تأیید محدوده محدود میکنند. برای اطلاعات بیشتر در مورد این الزام، به خدمات API گوگل: سیاست دادههای کاربر و الزامات اضافی برای محدودههای خاص API مراجعه کنید. همچنین به مراحل مربوط به برنامههایی که درخواست محدودههای محدود دارند مراجعه کنید.
اگر برنامه شما نیاز به دسترسی به هر API گوگل دیگری دارد، میتوانید آن محدودهها را نیز اضافه کنید. برای اطلاعات بیشتر در مورد محدودههای API گوگل، به بخش «استفاده از OAuth 2.0 برای دسترسی به APIهای گوگل» مراجعه کنید.
برای کسب اطلاعات بیشتر در مورد حوزههای APIهای Google Workspace، به پیکربندی صفحه رضایت OAuth و انتخاب حوزهها مراجعه کنید.
انواع احراز هویت مورد نیاز
دو روش برای احراز هویت و مجوزدهی برنامههای چت با استفاده از Chat API وجود دارد:
- احراز هویت کاربر
- احراز هویت کاربر به یک برنامه چت اجازه میدهد تا به دادههای کاربر دسترسی پیدا کند و اقدامات را از طرف کاربر انجام دهد. حوزههای OAuth دادهها و اقدامات مجاز را مشخص میکنند. مگر اینکه برنامه چت به صورت ادمین نصب شده باشد یا به آن مجوز سراسری دامنه داده شده باشد، اولین باری که برنامه چت عملی را از طرف کاربر انجام میدهد، کاربر باید با استفاده از صفحه رضایت OAuth برنامه چت را مجاز کند.
- احراز هویت برنامه
احراز هویت برنامه به یک برنامه چت اجازه میدهد تا از اعتبارنامههای حساب سرویس استفاده کند و به دادهها دسترسی پیدا کند و اقدامات را مانند خودش انجام دهد. از آنجا که برنامه چت از اعتبارنامههای خود برای دسترسی و کار با منابع استفاده میکند، کاربران نهایی نیازی به تأیید فراخوانیهای API برنامه چت ندارند و شما نمیتوانید دامنههای مجوز OAuth را که از مجوز برنامه پشتیبانی میکنند، به صفحه رضایت OAuth اضافه کنید.
دو نوع حوزه مجوز OAuth از احراز هویت برنامه پشتیبانی میکنند:
-
https://www.googleapis.com/auth/chat.bot: برنامه چت شما میتواند متدهای Google Chat API را که از این محدوده مجوز پشتیبانی میکنند، برای ایجاد، بهروزرسانی، دریافت، فهرستبندی یا حذف منابعی که به آنها دسترسی دارد، مانند پیامهای موجود در فضاهایی که کاربران نهایی برنامه چت شما را به آنها اضافه میکنند، فراخوانی کند. برنامه چت شما میتواند این محدوده مجوز را به صورت خودکار اعطا کند، بدون نیاز به مجوز مدیر یا کاربر نهایی. -
https://www.googleapis.com/auth/chat.app.*: استفاده از این محدودهها نیاز به تأیید یکباره مدیر دارد. برای دریافت تأیید مدیر، شما حساب سرویس برنامه چت را برای دریافت تأیید مدیر با ایجاد یک کلاینت OAuth سازگار با Google Workspace Marketplace و پیکربندی برنامه در Google Workspace Marketplace SDK آماده میکنید . این محدودهها به برنامه چت شما اجازه میدهند تا متدهای خاص Google Chat API را فراخوانی کند. به عنوان مثال،chat.app.spaces.createبه برنامهها اجازه میدهد تا فضاهای چت ایجاد کنند.
-
اگر روشی از احراز هویت کاربر یا برنامه پشتیبانی کند، API چت بر اساس نوع احراز هویتی که استفاده میکنید، نتایج متفاوتی را برمیگرداند:
- با احراز هویت برنامه، متدها فقط منابعی را برمیگردانند که برنامه چت میتواند به آنها دسترسی داشته باشد.
- با احراز هویت کاربر، متدها فقط منابعی را برمیگردانند که کاربر میتواند به آنها دسترسی داشته باشد.
برای مثال، فراخوانی متد spaces.list() با مجوز app، فهرست فضاهایی را که برنامه Chat عضو آنهاست، برمیگرداند. فراخوانی spaces.list() با مجوز user، فهرست فضاهایی را که کاربر عضو آنهاست، برمیگرداند. در عمل، بسته به طراحی و ویژگیهای برنامه Chat خود، ممکن است هنگام فراخوانی Chat API از هر دو نوع احراز هویت استفاده کنید.
برای فراخوانیهای ناهمزمان API چت
جدول زیر متدهای Chat API و حوزههای مجوز پشتیبانیشدهی آنها را فهرست میکند:
| روش | احراز هویت کاربر پشتیبانی میشود | احراز هویت برنامه پشتیبانی میشود | دامنههای مجوز پشتیبانی میشوند | |
|---|---|---|---|---|
| فضاها | ||||
| ایجاد یک فضا | با احراز هویت کاربر :
| |||
| یک فضا تنظیم کنید | — | با احراز هویت کاربر :
| ||
| فضایی بدست آورید | با احراز هویت کاربر :
| |||
| فضاهای لیست | با احراز هویت کاربر :
| |||
| فضاهای جستجو | — | با احراز هویت کاربر با استفاده از امتیازات مدیر :
| ||
| بهروزرسانی یک فضا | با احراز هویت کاربر :
| |||
| حذف یک فاصله | با احراز هویت کاربر :
| |||
| فرآیند وارد کردن یک فضا را تکمیل کنید | — | با احراز هویت کاربر :
| ||
| پیدا کردن پیام مستقیم | با احراز هویت کاربر :
| |||
| اعضا | ||||
| ایجاد عضو | با احراز هویت کاربر :
| |||
| عضو بگیرید | با احراز هویت کاربر :
| |||
| اعضا را فهرست کنید | با احراز هویت کاربر :
| |||
| حذف یک عضو | با احراز هویت کاربر :
| |||
| بهروزرسانی یک عضو | با احراز هویت کاربر :
| |||
| پیامها | ||||
| ایجاد پیام | با احراز هویت کاربر :
| |||
| دریافت پیام | با احراز هویت کاربر :
| |||
| لیست کردن پیامها | با احراز هویت کاربر :
| |||
| بهروزرسانی یک پیام | با احراز هویت کاربر :
| |||
| حذف یک پیام | با احراز هویت کاربر :
| |||
| واکنشها | ||||
| ایجاد واکنش | — | با احراز هویت کاربر :
| ||
| واکنشها را فهرست کنید | — | با احراز هویت کاربر :
| ||
| حذف یک واکنش | — | با احراز هویت کاربر :
| ||
| ایموجیهای سفارشی | ||||
| ایجاد ایموجی سفارشی | — | با احراز هویت کاربر :
| ||
| حذف یک ایموجی سفارشی | — | با احراز هویت کاربر :
| ||
| یک ایموجی سفارشی دریافت کنید | — | با احراز هویت کاربر :
| ||
| فهرست کردن ایموجیهای سفارشی | — | با احراز هویت کاربر :
| ||
| رسانهها و پیوستها | ||||
| آپلود رسانه به عنوان پیوست فایل | — | با احراز هویت کاربر :
| ||
| دانلود رسانه | با احراز هویت کاربر :
| |||
| دریافت پیوست پیام | — | با احراز هویت برنامه :
| ||
| کاربر حالتهای خوانده شده را میخواند | ||||
| دریافت وضعیت خواندن فضای یک کاربر | — | با احراز هویت کاربر :
| ||
| بهروزرسانی وضعیت خواندن فضای یک کاربر | — | با احراز هویت کاربر :
| ||
| دریافت وضعیت خوانده شدن نخ توسط کاربر | — | با احراز هویت کاربر :
| ||
| تنظیمات فضای کاربری | ||||
| دریافت تنظیمات اعلان فضای کاربر | — | با احراز هویت کاربر :
| ||
| بهروزرسانی تنظیمات اعلان فضای کاربر | — | با احراز هویت کاربر :
| ||
| رویدادهای فضایی | ||||
| رویدادهای فضایی را دریافت کنید | — | با احراز هویت کاربر ، باید از یک محدوده بر اساس نوع رویداد استفاده کنید:
| ||
| فهرست رویدادهای فضایی | — | با احراز هویت کاربر ، باید برای هر نوع رویداد موجود در درخواست، از یک محدوده استفاده کنید:
| ||
برای رویدادهای تعاملی برنامه چت
جدول زیر روشهای رایج تعامل کاربران با برنامههای چت و اینکه آیا احراز هویت مورد نیاز است یا پشتیبانی میشود را فهرست میکند:
| سناریو | بدون نیاز به احراز هویت | احراز هویت کاربر پشتیبانی میشود | احراز هویت برنامه پشتیبانی میشود | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| دریافت پیام از: |
| |||||||||||||||
| پاسخ به پیامها: |
| |||||||||||||||
| ارسال پیامهای جدید: |
| |||||||||||||||
مباحث مرتبط
- برای مرور کلی در مورد احراز هویت و مجوز در Google Workspace، به «درباره احراز هویت و مجوز بیشتر بدانید» مراجعه کنید.
- برای مرور کلی در مورد احراز هویت و مجوز در Google Cloud، به مرور کلی احراز هویت مراجعه کنید.
- برای کسب اطلاعات بیشتر در مورد حسابهای سرویس، به حسابهای سرویس مراجعه کنید.
- برای کسب اطلاعات بیشتر در مورد نحوه استفاده APIهای گوگل از OAuth 2.0، به بخش «استفاده از OAuth 2.0 برای دسترسی به APIهای گوگل» مراجعه کنید.
- احراز هویت و مجوز را با اعتبارنامههای کاربر یا یک حساب سرویس تنظیم کنید.