احراز هویت و مجوز مکانیزم هایی هستند که به ترتیب برای تأیید هویت و دسترسی به منابع استفاده می شوند. این سند چگونگی کارکرد احراز هویت و مجوز برای برنامه‌های Chat و درخواست‌های Chat API را شرح می‌دهد.
نمای کلی فرآیند
نمودار زیر مراحل سطح بالای احراز هویت و مجوز برای Google Chat را نشان می دهد:
یک پروژه 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 را فراخوانی می کند.
نمودار زیر یک توالی درخواست-پاسخ بین کاربر چت و برنامه چت را نشان می دهد:
- کاربر پیامی به برنامه چت در گپ Google ارسال می کند.
- Google Chat پیام را به برنامه فوروارد می کند.
- برنامه پیام را دریافت می‌کند، آن را پردازش می‌کند و پاسخی را به Google Chat برمی‌گرداند.
- Google Chat پاسخ را برای کاربر یا در یک فضا ارائه می دهد.
این دنباله برای هر رویداد تعامل برنامه چت تکرار می شود.
پیام های ناهمزمان نیاز به احراز هویت دارند
پیام‌های ناهمزمان زمانی رخ می‌دهند که یک برنامه گپ درخواستی را به Chat API ارسال می‌کند که به احراز هویت و مجوز نیاز دارد.
با تماس با Chat API، برنامه‌های چت می‌توانند پیام‌هایی را به چت Google ارسال کنند یا وظایف را تکمیل کنند و از طرف کاربر به داده‌ها دسترسی داشته باشند. به عنوان مثال، پس از تشخیص قطعی سرور، یک برنامه چت می تواند Chat API را به این موارد فراخوانی کند:
- یک فضای چت اختصاص داده شده برای بررسی و رفع قطعی ایجاد کنید.
- افراد را به فضای چت اضافه کنید.
- برای ارائه جزئیات در مورد قطع، یک پیام به فضای چت ارسال کنید.
نمودار زیر یک توالی پیام ناهمزمان بین یک برنامه چت و یک فضای چت را نشان می دهد:
- یک برنامه چت با فراخوانی 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.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 | تنظیمات فضای کاربر چت را مشاهده و به روز کنید. مشاهده APIهای تنظیمات کاربر فضا: getSpaceNotificationSetting ، updateSpaceNotificationSetting |
محدوده های محدود
| کد محدوده | توضیحات |
|---|---|
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 | مکالمات و فضاهای متعلق به دامنه سرپرست را حذف کنید و دسترسی به فایل‌های مرتبط را در چت حذف کنید. |
https://www.googleapis.com/auth/chat.app.delete | مکالمات و فضاها را حذف کنید و دسترسی به فایل‌های مرتبط را در چت حذف کنید. نیاز به تایید مدیر این محدوده فقط از تأیید اعتبار برنامه با حساب های خدمات پشتیبانی می کند. با استفاده از این محدوده نمی‌توانید با اعتبار کاربری یا با تفویض اختیار در سطح دامنه احراز هویت کنید. |
محدوده های موجود در جداول قبل حساسیت آنها را با توجه به تعاریف زیر نشان می دهد:
غیر حساس - این حوزه‌ها کوچک‌ترین حوزه دسترسی مجوز را فراهم می‌کنند و فقط به تأیید اولیه برنامه نیاز دارند. برای کسب اطلاعات در مورد این الزام، به مراحل آماده شدن برای تأیید مراجعه کنید.
حساس — این محدوده‌ها پس از دریافت مجوز از کاربر، دسترسی برنامه شما به داده‌های Google یک کاربر خاص را فراهم می‌کنند. از شما می‌خواهد تا از تأیید برنامه اضافی عبور کنید. برای کسب اطلاعات در مورد این نیاز، به مراحل برنامه‌هایی که دامنه‌های حساس را درخواست می‌کنند، مراجعه کنید.
محدود — این حوزه‌ها دسترسی گسترده‌ای به داده‌های کاربر Google را فراهم می‌کنند و از شما می‌خواهند که فرآیند تأیید محدوده محدود را طی کنید. برای کسب اطلاعات در مورد این نیاز، به خدمات Google API مراجعه کنید: خط‌مشی داده‌های کاربر و الزامات اضافی برای محدوده‌های API خاص . همچنین مراحل برنامه های درخواست کننده محدوده محدود را ببینید.
اگر برنامه شما نیاز به دسترسی به سایر APIهای Google دارد، می‌توانید آن محدوده‌ها را نیز اضافه کنید. برای اطلاعات بیشتر در مورد دامنه های Google API، به استفاده از OAuth 2.0 برای دسترسی به Google API مراجعه کنید.
برای کسب اطلاعات بیشتر درباره دامنه‌های APIهای Google Workspace، به پیکربندی صفحه رضایت OAuth مراجعه کنید و دامنه‌ها را انتخاب کنید .
انواع احراز هویت مورد نیاز
دو روش وجود دارد که برنامه‌های چت می‌توانند با Chat API احراز هویت و تأیید اعتبار کنند:
- احراز هویت کاربر
- احراز هویت کاربر به برنامه چت اجازه می‌دهد به داده‌های کاربر دسترسی داشته باشد و اقدامات را از طرف یک کاربر انجام دهد. محدوده OAuth داده ها و اقدامات مجاز را مشخص می کند. مگر اینکه برنامه Chat توسط سرپرست نصب شده باشد یا به آن تفویض اختیار در سطح دامنه داده شده باشد، اولین باری که برنامه Chat اقدامی را از طرف یک کاربر انجام می‌دهد، کاربر باید برنامه Chat را با استفاده از صفحه رضایت OAuth مجوز دهد.
- احراز هویت برنامه
احراز هویت برنامه به برنامه چت اجازه می‌دهد از اعتبار حساب سرویس استفاده کند و به داده‌ها دسترسی داشته باشد و اقدامات را انجام دهد. از آنجایی که برنامه Chat از اعتبار خود برای دسترسی و کار با منابع استفاده می کند، کاربران نهایی نیازی به تأیید تماس های API برنامه Chat ندارند و نمی توانید محدوده های مجوز OAuth را که از مجوز برنامه پشتیبانی می کنند به صفحه رضایت OAuth اضافه کنید.
دو نوع دامنه مجوز OAuth از احراز هویت برنامه پشتیبانی می کند:
-
https://www.googleapis.com/auth/chat.bot: برنامه Chat شما می‌تواند با روش‌های Google Chat API که از این محدوده مجوز پشتیبانی می‌کنند برای ایجاد، به‌روزرسانی، دریافت، فهرست کردن یا حذف منابعی که به آنها دسترسی دارد، مانند پیام‌ها، فراخوانی کند. در فضاهایی که کاربران نهایی برنامه چت شما را به آن اضافه می کنند. برنامه گپ شما می‌تواند این محدوده مجوز را خود اعطا کند، بدون نیاز به مجوز سرپرست یا کاربر نهایی. -
https://www.googleapis.com/auth/chat.app.*( پیش‌نمایش توسعه‌دهنده ): استفاده از این حوزه‌ها نیاز به تأیید یک‌باره سرپرست دارد. برای دریافت تأیید سرپرست، با ایجاد یک سرویس گیرنده OAuth سازگار با Google Workspace Marketplace و پیکربندی برنامه در Google Workspace Marketplace SDK، حساب سرویس برنامه Chat را برای دریافت تأیید سرپرست آماده می‌کنید . این حوزه‌ها به برنامه چت شما اجازه می‌دهند تا با روش‌های خاص Google Chat API تماس بگیرد. برای مثال،chat.app.spaces.createبه برنامه‌ها اجازه می‌دهد فضاهای چت ایجاد کنند.
-
اگر روشی از احراز هویت کاربر یا برنامه پشتیبانی می‌کند، Chat API نتایج متفاوتی را بر اساس نوع احراز هویتی که استفاده می‌کنید برمی‌گرداند:
- با احراز هویت برنامه، روش‌ها فقط منابعی را برمی‌گردانند که برنامه چت می‌تواند به آنها دسترسی داشته باشد.
- با احراز هویت کاربر، روش‌ها فقط منابعی را برمی‌گردانند که کاربر می‌تواند به آنها دسترسی داشته باشد.
برای مثال، فراخوانی متد spaces.list() با مجوز برنامه، فهرست فضاهایی را که برنامه چت عضوی از آنها است، برمی‌گرداند. فراخوانی spaces.list() با مجوز کاربر، لیستی از فضاهایی را که کاربر در آن عضو است برمی گرداند. در عمل، بسته به طراحی و ویژگی‌های برنامه چت، ممکن است هنگام تماس با Chat API از هر دو نوع احراز هویت استفاده کنید.
برای تماس‌های ناهمزمان Chat API
جدول زیر متدهای Chat API و حوزه‌های مجوز پشتیبانی شده آنها را فهرست می‌کند:
| روش | احراز هویت کاربر پشتیبانی می شود | تأیید اعتبار برنامه پشتیبانی می شود | دامنه مجوز پشتیبانی می شود | |
|---|---|---|---|---|
| فضاها | ||||
| یک فضا ایجاد کنید | با احراز هویت کاربر :
| |||
| فضایی را تنظیم کنید | - | با احراز هویت کاربر :
| ||
| فضا بگیر | با احراز هویت کاربر :
| |||
| فهرست فضاها | با احراز هویت کاربر :
| |||
| فضاهای جستجو | - | با احراز هویت کاربر با استفاده از امتیازات مدیر :
| ||
| یک فضا را به روز کنید | با احراز هویت کاربر :
| |||
| یک فاصله را حذف کنید | با احراز هویت کاربر :
| |||
| فرآیند واردات یک فضا را کامل کنید | - | با احراز هویت کاربر :
| ||
| یک پیام مستقیم پیدا کنید | با احراز هویت کاربر :
| |||
| اعضا | ||||
| یک عضو ایجاد کنید | با احراز هویت کاربر :
| |||
| عضو بگیر | با احراز هویت کاربر :
| |||
| لیست اعضا | با احراز هویت کاربر :
| |||
| حذف یک عضو | با احراز هویت کاربر :
| |||
| یک عضو را به روز کنید | با احراز هویت کاربر :
| |||
| پیام ها | ||||
| یک پیام ایجاد کنید | با احراز هویت کاربر :
| |||
| یک پیام دریافت کنید | با احراز هویت کاربر :
| |||
| لیست پیام ها | - | با احراز هویت کاربر :
| ||
| یک پیام را به روز کنید | با احراز هویت کاربر :
| |||
| یک پیام را حذف کنید | با احراز هویت کاربر :
| |||
| واکنش ها | ||||
| واکنش ایجاد کنید | - | با احراز هویت کاربر :
| ||
| واکنش ها را فهرست کنید | - | با احراز هویت کاربر :
| ||
| یک واکنش را حذف کنید | - | با احراز هویت کاربر :
| ||
| ایموجی سفارشی | ||||
| یک ایموجی سفارشی ایجاد کنید | - | با احراز هویت کاربر :
| ||
| یک ایموجی سفارشی را حذف کنید | - | با احراز هویت کاربر :
| ||
| یک ایموجی سفارشی دریافت کنید | - | با احراز هویت کاربر :
| ||
| ایموجی های سفارشی را فهرست کنید | - | با احراز هویت کاربر :
| ||
| رسانه و پیوست | ||||
| رسانه را به عنوان پیوست فایل آپلود کنید | - | با احراز هویت کاربر :
| ||
| دانلود رسانه | با احراز هویت کاربر :
| |||
| یک پیوست پیام دریافت کنید | - | با احراز هویت برنامه :
| ||
| وضعیت خواندن کاربر | ||||
| وضعیت خواندن فضای کاربر را دریافت کنید | - | با احراز هویت کاربر :
| ||
| وضعیت خواندن فضای کاربر را به روز کنید | - | با احراز هویت کاربر :
| ||
| وضعیت خواندن موضوع یک کاربر را دریافت کنید | - | با احراز هویت کاربر :
| ||
| تنظیمات فضای کاربر | ||||
| تنظیمات اعلان فضای کاربر را دریافت کنید | - | با احراز هویت کاربر :
| ||
| تنظیمات اعلان فضای کاربر را به روز کنید | - | با احراز هویت کاربر :
| ||
| رویدادهای فضایی | ||||
| رویدادهای فضایی را دریافت کنید | - | با احراز هویت کاربر ، باید از یک محدوده بر اساس نوع رویداد استفاده کنید:
| ||
| فهرست رویدادهای فضایی | - | با احراز هویت کاربر ، باید از یک محدوده برای هر نوع رویداد موجود در درخواست استفاده کنید:
| ||
برای رویدادهای تعامل برنامه چت
جدول زیر روش‌های متداول تعامل کاربران با برنامه‌های چت و اینکه آیا احراز هویت مورد نیاز است یا پشتیبانی می‌شود را فهرست می‌کند:
| سناریو | بدون نیاز به احراز هویت | احراز هویت کاربر پشتیبانی می شود | تأیید اعتبار برنامه پشتیبانی می شود | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| دریافت پیام از: |
| |||||||||||||||
| پاسخ به پیام ها: |
| |||||||||||||||
| ارسال پیام های جدید: |
| |||||||||||||||
موضوعات مرتبط
- برای مرور کلی احراز هویت و مجوز در Google Workspace، به اطلاعاتی درباره احراز هویت و مجوز مراجعه کنید.
- برای مرور کلی احراز هویت و مجوز در Google Cloud، به نمای کلی احراز هویت مراجعه کنید.
- برای کسب اطلاعات بیشتر درباره حساب‌های خدمات، به حساب‌های خدمات مراجعه کنید.
- برای کسب اطلاعات بیشتر در مورد نحوه استفاده APIهای Google از OAuth 2.0، به استفاده از OAuth 2.0 برای دسترسی به Google API مراجعه کنید.
- احراز هویت و مجوز را با اعتبار کاربری یا یک حساب سرویس تنظیم کنید.