این سند حاوی اطلاعات اصالت‌سنجی و صدور مجوز مختص Google Workspace Events API است. قبل‌از خواندن این سند، حتماً اطلاعات کلی اصالت‌سنجی و صدور مجوز Google Workspace را در آشنایی با اصالت‌سنجی و صدور مجوز بخوانید.
پیکربندی OAuth 2.0 برای صدور مجوز
صفحه رضایت OAuth را پیکربندی کنید و دامنه‌ها را انتخاب کنید تا مشخص کنید چه اطلاعاتی به کاربران و بازبینان برنامه نمایش داده شود، و برنامه‌تان را ثبت کنید تا بتوانید بعداً آن را منتشر کنید.
گستره‌های Google Workspace Events API
برای تعریف سطح دسترسی اعطاشده به برنامه‌تان، باید حوزه‌های مجوز را شناسایی و اعلام کنید. دامنه مجوز یک رشته URI از OAuth 2.0 است که حاوی نام برنامه Google Workspace، نوع داده‌ای که به آن دسترسی دارد، و سطح دسترسی است. گستره‌ها درخواست‌های برنامه شما برای کار با داده‌های Google Workspace، ازجمله داده‌های «حساب Google» کاربران، هستند.
وقتی برنامه‌تان نصب می‌شود، از کاربر خواسته می‌شود دامنه‌های استفاده‌شده توسط برنامه را اعتبارسنجی کند. به‌طور کلی، باید محدودترین دامنه ممکن را انتخاب کنید و از درخواست دامنه‌هایی که برنامه‌تان به آن‌ها نیاز ندارد اجتناب کنید. کاربران با تمایل بیشتری به گستره‌های محدود و به‌وضوح شرح‌داده‌شده دسترسی می‌دهند.
Google Workspace Events API از گستره‌های برنامه‌های Google Workspace که از اشتراک‌ها پشتیبانی می‌کنند استفاده می‌کند. اگر برنامه‌تان از قبل از گستره‌های لازم برای اشتراکتان استفاده می‌کند، برای استفاده از Google Workspace Events API نیازی به افزودن گستره ندارید. اگر گستره اضافه می‌کنید، کم‌حساس‌ترین گستره‌ای را انتخاب کنید که همچنان به برنامه‌تان اجازه می‌دهد کار کند. برای جزئیات درباره دسته‌های گستره، به دسته‌های گستره مراجعه کنید.
جدول زیر گستره‌های پشتیبانی‌شده برای Google Workspace Events API را فهرست می‌کند:
| کد حوزه | شرح | کاربرد | ||
|---|---|---|---|---|
| Google Chat | ||||
https://www.googleapis.com/auth/chat.bot |
به برنامه‌های Chat اجازه می‌دهد گپ‌ها را مشاهده کنند و پیام ارسال کنند. دسترسی به همه ویژگی‌های دردسترس برای برنامه‌های Chat را می‌دهد. | غیرحساس | ||
https://www.googleapis.com/auth/chat.memberships |
مشاهده، افزودن، و برداشتن اعضا از مکالمه‌های Chat. | حساس |
||
https://www.googleapis.com/auth/chat.memberships.readonly |
مشاهده اعضا در مکالمه‌های Chat. | حساس |
||
https://www.googleapis.com/auth/chat.app.memberships |
دیدن، افزودن، به‌روزرسانی، و برداشتن اعضا از مکالمه‌ها و فضاها در Chat به‌عنوان برنامه Chat. به تأیید سرپرست نیاز دارد. این گستره فقط از اصالت‌سنجی برنامه با حساب‌های سرویس پشتیبانی می‌کند. بااستفاده از این دامنه، نمی‌توانید با اعتبارنامه کاربر یا با واگذاری در سراسر دامنه اصالت‌سنجی کنید. |
حساس |
||
https://www.googleapis.com/auth/chat.app.memberships.readonly |
دیدن اعضای مکالمه‌ها و فضاها در Google Chat به‌عنوان برنامه Chat. به تأیید سرپرست نیاز دارد. این گستره فقط از اصالت‌سنجی برنامه با حساب‌های سرویس پشتیبانی می‌کند. بااستفاده از این دامنه، نمی‌توانید با اعتبارنامه کاربر یا با واگذاری در سراسر دامنه اصالت‌سنجی کنید. |
حساس |
||
https://www.googleapis.com/auth/chat.spaces |
ایجاد مکالمه و فضا و مشاهده یا به‌روزرسانی فراداده‌ها (ازجمله تنظیمات سابقه) در Chat. | حساس | ||
https://www.googleapis.com/auth/chat.spaces.readonly |
مشاهده گپ و فضاها در Chat. | حساس |
||
https://www.googleapis.com/auth/chat.app.spaces |
ایجاد مکالمه و فضا و مشاهده یا به‌روزرسانی فراداده‌ها (ازجمله تنظیمات سابقه) در Chat به‌عنوان برنامه Chat. به تأیید سرپرست نیاز دارد. این گستره فقط از اصالت‌سنجی برنامه با حساب‌های سرویس پشتیبانی می‌کند. بااستفاده از این دامنه، نمی‌توانید با اعتبارنامه کاربر یا با واگذاری در سراسر دامنه اصالت‌سنجی کنید. |
حساس |
||
https://www.googleapis.com/auth/chat.app.spaces.readonly |
مشاهده فراداده‌ها (ازجمله تنظیمات سابقه) در Google Chat به‌عنوان برنامه Chat. به تأیید سرپرست نیاز دارد. این گستره فقط از اصالت‌سنجی برنامه با حساب‌های سرویس پشتیبانی می‌کند. بااستفاده از این دامنه، نمی‌توانید با اعتبارنامه کاربر یا با واگذاری در سراسر دامنه اصالت‌سنجی کنید. |
حساس |
||
https://www.googleapis.com/auth/chat.messages.reactions |
مشاهده، افزودن، و حذف واکنش به پیام‌ها در Chat. | حساس |
||
https://www.googleapis.com/auth/chat.messages.reactions.readonly |
مشاهده واکنش‌ها به پیام در Chat. | حساس |
||
https://www.googleapis.com/auth/chat.messages |
مشاهده، نوشتن، ارسال، به‌روزرسانی، و حذف پیام‌ها و افزودن، مشاهده، و حذف واکنش به پیام‌ها. | محدود | ||
https://www.googleapis.com/auth/chat.messages.readonly |
مشاهده پیام‌ها و واکنش‌ها در Chat. | محدودشده |
||
https://www.googleapis.com/auth/chat.app.messages.readonly |
مشاهده پیام‌ها و واکنش‌ها در Chat به‌عنوان برنامه Chat. به تأیید سرپرست نیاز دارد. این گستره فقط از اصالت‌سنجی برنامه با حساب‌های سرویس پشتیبانی می‌کند. بااستفاده از این دامنه، نمی‌توانید با اعتبارنامه کاربر یا با واگذاری در سراسر دامنه اصالت‌سنجی کنید. |
محدودشده |
||
https://www.googleapis.com/auth/chat.users.readstate |
مشاهده و به‌روزرسانی وضعیت خوانده شدن کاربر در Chat. | حساس |
||
https://www.googleapis.com/auth/chat.users.readstate.readonly |
مشاهده وضعیت خواندن کاربر در Chat. | حساس |
||
https://www.googleapis.com/auth/chat.users.availability |
مشاهده و تغییر وضعیت دردسترس بودن در Chat. | حساس |
||
https://www.googleapis.com/auth/chat.users.availability.readonly |
مشاهده وضعیت دردسترس بودن در Chat. | حساس |
||
https://www.googleapis.com/auth/chat.app.all.spaces.readonly |
فراداده‌های مربوط به همه فضاها و مکالمه‌های Google Chat در سراسر سازمان Google Workspace شما را ببیند، حتی وقتی‌که برنامه Chat عضو نباشد. این گستره فقط با اشتراک‌های مشتری پشتیبانی می‌شود. به تأیید سرپرست نیاز دارد. این گستره فقط از اصالت‌سنجی برنامه با حساب‌های سرویس پشتیبانی می‌کند. بااستفاده از این دامنه نمی‌توانید با اعتبارنامه کاربر یا با واگذاری در سطح دامنه اصالت‌سنجی کنید. |
محدود | ||
https://www.googleapis.com/auth/chat.app.all.memberships.readonly |
همه اعضای مکالمه‌ها و فضاهای Google Chat را در سراسر سازمان Google Workspace شما ببیند، حتی وقتی‌که برنامه Chat عضو نباشد. این گستره فقط با اشتراک‌های مشتری پشتیبانی می‌شود. به تأیید سرپرست نیاز دارد. این گستره فقط از اصالت‌سنجی برنامه با حساب‌های سرویس پشتیبانی می‌کند. بااستفاده از این دامنه نمی‌توانید با اعتبارنامه کاربر یا با واگذاری در سطح دامنه اصالت‌سنجی کنید. |
محدود | ||
https://www.googleapis.com/auth/chat.app.all.messages.readonly |
همه پیام‌ها و واکنش‌ها را در سراسر سازمان Google Workspace شما ببیند، حتی وقتی‌که برنامه Chat عضو فضا یا مکالمه نباشد. این گستره فقط با اشتراک‌های مشتری پشتیبانی می‌شود. به تأیید سرپرست نیاز دارد. این گستره فقط از اصالت‌سنجی برنامه با حساب‌های سرویس پشتیبانی می‌کند. بااستفاده از این دامنه نمی‌توانید با اعتبارنامه کاربر یا با واگذاری در سطح دامنه اصالت‌سنجی کنید. |
محدود | ||
https://www.googleapis.com/auth/chat.app.all.users.readstate.readonly |
آخرین زمان خواندن را برای همه کاربران در همه فضاها و مکالمه‌های سراسر سازمان Google Workspace شما ببیند، حتی وقتی‌که برنامه Chat عضو نباشد. این گستره فقط با اشتراک‌های مشتری پشتیبانی می‌شود. به تأیید سرپرست نیاز دارد. این گستره فقط از اصالت‌سنجی برنامه با حساب‌های سرویس پشتیبانی می‌کند. بااستفاده از این دامنه نمی‌توانید با اعتبارنامه کاربر یا با واگذاری در سطح دامنه اصالت‌سنجی کنید. |
محدود | ||
| Google Drive | ||||
https://www.googleapis.com/auth/drive.file |
فایل‌های Drive جدید ایجاد کنید یا فایل‌های موجود را که با برنامه‌ای باز می‌کنید یا کاربر هنگام استفاده از Google Picker API یا انتخاب‌گر فایل برنامه با برنامه‌ای هم‌رسانی می‌کند اصلاح کنید. | غیرحساس | ||
https://www.googleapis.com/auth/drive |
مشاهده و مدیریت همه فایل‌های Drive شما. | محدود | ||
https://www.googleapis.com/auth/drive.readonly |
مشاهده و بارگیری همه فایل‌های Drive شما. | محدود | ||
https://www.googleapis.com/auth/drive.metadata |
مشاهده و مدیریت فراداده فایل‌های موجود در Drive شما. | محدود | ||
https://www.googleapis.com/auth/drive.metadata.readonly |
فوق داده‌های فایل‌های موجود در Drive خودتان را مشاهده کنید. | محدود | ||
| Google Meet | ||||
https://www.googleapis.com/auth/meetings.space.created |
به برنامه‌ها اجازه می‌دهد فراداده‌های مربوط به فضاهای جلسه ایجادشده توسط برنامه شما را ایجاد، اصلاح، و خواندن کنند. | حساس |
||
https://www.googleapis.com/auth/meetings.space.readonly |
به برنامه‌ها اجازه می‌دهد فراداده‌های مربوط به هر فضای جلسه‌ای را که کاربر به آن دسترسی دارد بخوانند. | حساس |
||
ستون «استفاده» در جدول بالا نشان‌دهنده حساسیت هر گستره است:
غیرحساس: این دامنه‌ها کوچک‌ترین دامنه دسترسی به مجوز را ارائه می‌دهند و فقط به درستی‌سنجی پایه برنامه نیاز دارند. برای کسب اطلاعات درباره این الزام، به الزامات درستی‌سنجی مراجعه کنید.
حساس: این دامنه‌ها دسترسی به «داده‌های کاربر Google» خاصی را فراهم می‌کنند که کاربر برای برنامه شما مجاز کرده است. این دامنه‌ها مستلزم این هستند که درستی‌سنجی برنامه اضافی را انجام دهید. برای کسب اطلاعات درباره این الزام، به الزامات گستره حساس و محدودشده مراجعه کنید.
محدودشده: این حوزه‌ها دسترسی گسترده‌ای به «داده‌های کاربر Google» ارائه می‌دهند و مستلزم این هستند که فرایند درستی‌سنجی حوزه محدودشده را طی کنید. برای کسب اطلاعات درباره این الزام، به سرویس‌های Google API: خط‌مشی داده‌های کاربر و الزامات اضافی برای دامنه‌های خاص میانای برنامه‌سازی کاربردی مراجعه کنید. اگر داده‌های با دامنه محدود را در سرورها ذخیره (یا منتقل) می‌کنید، باید ارزیابی امنیتی را انجام دهید.
اگر برنامه‌تان به دسترسی به Google API دیگری نیاز دارد، می‌توانید آن گستره‌ها را نیز اضافه کنید. برای اطلاعات بیشتر درباره دامنه‌های Google API، به استفاده از OAuth 2.0 برای دسترسی به Google API مراجعه کنید.
برای اطلاعات بیشتر درباره دامنه‌های خاص OAuth 2.0، به دامنه‌های OAuth 2.0 برای Google APIs مراجعه کنید.
درستی‌سنجی OAuth
استفاده از برخی دامنه‌های OAuth ممکن است مستلزم این باشد که برنامه‌تان ازطریق مرکز راهنمایی درستی‌سنجی برنامه OAuth ادامه دهد. پرسشگان برنامه OAuth را بخوانید تا تعیین کنید برنامه‌تان چه زمانی باید درستی‌سنجی شود و چه نوع درستی‌سنجی‌ای لازم است. شرایط خدمات Drive را نیز ببینید.
انواع اصالت‌سنجی لازم
این بخش توضیح می‌دهد که کدام نوع اصالت‌سنجی لازم است یا پشتیبانی می‌شود، و دامنه‌های پشتیبانی‌شده را برای هر روش از Google Workspace Events API ارائه می‌دهد.
برای اشتراک‌های رویدادهای Chat،
Google Workspace Events API از اصالت‌سنجی کاربر و برنامه برای فراخوانی
برخی‌از روش‌هایش پشتیبانی می‌کند. اگر روش میانای برنامه‌سازی کاربردی از هر دو اعتبارنامه پشتیبانی کند، نوع
اعتبارنامه استفاده‌شده در تماس بر نتیجه برگردانده‌شده تأثیر می‌گذارد. برای مثال، اگر
روش
subscriptions.list
را با اصالت‌سنجی کاربر فراخوانی کنید، API فهرستی از اشتراک‌هایی را برمی‌گرداند که
کاربر اصالت‌سنجی‌شده می‌تواند به آن‌ها دسترسی داشته باشد. اگر از اصالت‌سنجی برنامه استفاده می‌کنید، میانای برنامه‌سازی کاربردی
فهرستی از اشتراک‌هایی را که برنامه می‌تواند به آن‌ها دسترسی داشته باشد برمی‌گرداند. برای کسب اطلاعات بیشتر درباره
انواع اصالت‌سنجی Chat، به اصالت‌سنجی و صدور مجوز
برنامه‌های Chat و درخواست‌های Chat API مراجعه کنید.
جدول زیر نشان می‌دهد که کدام دامنه‌ها و انواع اصالت‌سنجی برای هر روش Google Workspace Events API لازم است یا پشتیبانی می‌شود:
| روش | اصالت‌سنجی کاربر لازم است یا پشتیبانی می‌شود | اصالت‌سنجی برنامه پشتیبانی می‌شود (فقط برنامه‌های Chat) | گستره‌های مجوز پشتیبانی‌شده | |
|---|---|---|---|---|
| ایجاد اشتراک | — |
با اصالت‌سنجی کاربر، به دامنه پشتیبانی‌شده برای هر نوع رویداد نیاز دارد:
با اصالت‌سنجی برنامه و تأیید سرپرست (فقط برنامه‌های Google Chat)، به دامنه پشتیبانی‌شده برای هر نوع رویداد نیاز دارد:
|
||
| دریافت اشتراک |
با اصالت‌سنجی کاربر، این روش به دامنه‌ای نیاز دارد که حداقل از یک نوع رویداد برای اشتراک پشتیبانی کند.
با اصالت‌سنجی برنامه (فقط برنامه‌های Chat):
|
|||
| فهرست کردن اشتراک‌ها |
با اصالت‌سنجی کاربر، این روش به دامنه‌ای نیاز دارد که حداقل از یک نوع رویداد برای اشتراک پشتیبانی کند.
با اصالت‌سنجی برنامه (فقط برنامه‌های Chat):
|
|||
| به‌روزرسانی اشتراک | — |
با اصالت‌سنجی کاربر، به دامنه پشتیبانی‌شده برای هر نوع رویداد نیاز دارد:
با اصالت‌سنجی برنامه و تأیید سرپرست (فقط برنامه‌های Google Chat)، به دامنه پشتیبانی‌شده برای هر نوع رویداد نیاز دارد:
|
||
| فعال کردن مجدد اشتراک | — |
با اصالت‌سنجی کاربر، به دامنه پشتیبانی‌شده برای هر نوع رویداد نیاز دارد:
با اصالت‌سنجی برنامه و تأیید سرپرست (فقط برنامه‌های Chat)، به گستره پشتیبانی‌شده برای هر نوع رویداد نیاز دارد:
|
||
| حذف اشتراک |
با اصالت‌سنجی کاربر، این روش به دامنه‌ای نیاز دارد که حداقل از یک نوع رویداد برای اشتراک پشتیبانی کند.
با اصالت‌سنجی برنامه (فقط برنامه‌های Chat):
|
|||
دامنه‌ها براساس نوع رویداد
وقتی Google Workspace Events API را بااستفاده از اصالت‌سنجی کاربر فراخوانی می‌کنید، باید یک یا چند گستره را که با انواع رویداد اشتراک مطابقت دارد مشخص کنید.
جدول زیر نشان می‌دهد که کدام دامنه‌های مجوز برای هر نوع رویداد پشتیبانی می‌شود:
| رویدادها | انواع رویداد | دامنه‌های مجوز پشتیبانی‌شده | ||||||
|---|---|---|---|---|---|---|---|---|
| گپ | ||||||||
| پیامی پست یا به‌روز شود. |
|
با اصالت‌سنجی کاربر:
|
||||||
| واکنشی اضافه یا حذف شود، یا چند واکنش تغییر کند. |
|
با اصالت‌سنجی کاربر:
|
||||||
| عضویت ایجاد، به‌روزرسانی، یا برداشته شود، یا چند عضویت تغییر کند. |
|
با اصالت‌سنجی کاربر:
|
||||||
| فضایی به‌روزرسانی یا حذف شود. |
|
با اصالت‌سنجی کاربر:
|
||||||
| وضعیت خوانده شدن فضا یا وضعیت خوانده شدن رشته کاربر به‌روز می‌شود. |
|
با اصالت‌سنجی کاربر:
|
||||||
| دردسترس بودن به‌روز شده است. |
|
با اصالت‌سنجی کاربر:
|
||||||
| Drive | ||||||||
| فایلی ایجاد، تغییر، جابه‌جا، حذف، تغییرنام، به حذف‌شده‌ها منتقل، یا از حذف‌شده‌ها برداشته شود. |
|
|
||||||
| پیشنهاد دسترسی برای فایلی ایجاد یا حل‌وفصل شود. |
|
|
||||||
| تأییدیه‌ای لغو، تکمیل، ایجاد، یا بازنشانی شود، یا بازبین‌های آن تغییر کنند، یا بازبین‌ها به فایلی پاسخ دهند. |
|
|
||||||
| نظری در فایلی ایجاد، حذف، ویرایش، بازگشایی، یا حل شود. |
|
|
||||||
| پاسخی در فایلی ایجاد، حذف، یا ویرایش شود. |
|
|
||||||
| اجازه‌ای در فایلی ایجاد، حذف، یا ویرایش شود. |
|
|
||||||
| Meet | ||||||||
| کنفرانسی شروع یا تمام می‌شود. |
|
|
||||||
| شرکت‌کننده‌ای به کنفرانس می‌پیوندد یا آن را ترک می‌کند. |
|
|
||||||
| قطعه ضبط‌شده‌ای تولید شد. |
|
|
||||||
| ترانویسی تولید شد. |
|
|
||||||