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

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

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

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

شکل 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	آخرین زمان خواندن مکالمات چت را مشاهده و تغییر دهید. پیش‌نمایش برنامه‌نویس: به‌عنوان بخشی از برنامه پیش‌نمایش برنامه‌نویس Google Workspace موجود است که دسترسی زودهنگام به ویژگی‌های خاصی را اعطا می‌کند.
https://www.googleapis.com/auth/chat.users.readstate.readonly	آخرین زمان خواندن مکالمات چت را مشاهده کنید. پیش‌نمایش برنامه‌نویس: به‌عنوان بخشی از برنامه پیش‌نمایش برنامه‌نویس Google Workspace موجود است که دسترسی زودهنگام به ویژگی‌های خاصی را اعطا می‌کند.

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

کد محدوده	شرح
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	پیام ها و واکنش ها را در چت مشاهده کنید.

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

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

• حساس — این محدوده‌ها پس از دریافت مجوز از کاربر، دسترسی برنامه شما به داده‌های 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 و حوزه‌های مجوز پشتیبانی شده آنها را فهرست می‌کند:

روش	احراز هویت کاربر پشتیبانی می شود	تأیید اعتبار برنامه پشتیبانی می شود	دامنه مجوز پشتیبانی می شود
فضاها
یک فضا ایجاد کنید		-	با احراز هویت کاربر : 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.spaces chat.import
یک فاصله را حذف کنید		-	با احراز هویت کاربر : chat.delete chat.import
فرآیند واردات یک فضا را تکمیل کنید		-	با احراز هویت کاربر : chat.import
یک پیام مستقیم پیدا کنید			با احراز هویت کاربر : chat.spaces.readonly chat.spaces با احراز هویت برنامه : chat.bot
اعضا
یک عضو ایجاد کنید		-	با احراز هویت کاربر : chat.memberships chat.memberships.app chat.import
عضو بگیر			با احراز هویت کاربر : chat.memberships.readonly chat.memberships با احراز هویت برنامه : chat.bot
لیست اعضا			با احراز هویت کاربر : chat.memberships.readonly chat.memberships chat.import با احراز هویت برنامه : chat.bot
حذف یک عضو		-	با احراز هویت کاربر : chat.memberships chat.memberships.app chat.import
پیام ها
یک پیام ایجاد کنید			با احراز هویت کاربر : 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
وضعیت خواندن کاربر
وضعیت خواندن فضای کاربر را دریافت کنید		-	پیش‌نمایش برنامه‌نویس: به‌عنوان بخشی از برنامه پیش‌نمایش برنامه‌نویس Google Workspace موجود است که دسترسی زودهنگام به ویژگی‌های خاصی را اعطا می‌کند. با احراز هویت کاربر : chat.users.readstate chat.users.readstate.readonly
وضعیت خواندن فضای کاربر را به روز کنید		-	پیش‌نمایش برنامه‌نویس: به‌عنوان بخشی از برنامه پیش‌نمایش برنامه‌نویس Google Workspace موجود است که دسترسی زودهنگام به ویژگی‌های خاصی را اعطا می‌کند. با احراز هویت کاربر : chat.users.readstate
وضعیت خواندن موضوع یک کاربر را دریافت کنید		-	پیش‌نمایش برنامه‌نویس: به‌عنوان بخشی از برنامه پیش‌نمایش برنامه‌نویس Google Workspace موجود است که دسترسی زودهنگام به ویژگی‌های خاصی را اعطا می‌کند. با احراز هویت کاربر : 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 - -
ارسال پیام های جدید:	با وب هوک های ورودی - -

مطالب مرتبط

• برای مرور کلی احراز هویت و مجوز در Google Workspace، به اطلاعاتی درباره احراز هویت و مجوز مراجعه کنید.
• برای مرور کلی احراز هویت و مجوز در Google Cloud، به نمای کلی احراز هویت مراجعه کنید.
• برای کسب اطلاعات بیشتر درباره حساب‌های خدمات، به حساب‌های خدمات مراجعه کنید.
• برای کسب اطلاعات بیشتر در مورد اینکه چگونه API های Google از OAuth 2.0 استفاده می کنند، به استفاده از OAuth 2.0 برای دسترسی به Google API مراجعه کنید.
• احراز هویت و مجوز را با اعتبار کاربری یا یک حساب سرویس تنظیم کنید.