این سند حاوی اطلاعات مربوط به مجوز و احراز هویت مختص API رویدادهای Google Workspace است. قبل از مطالعه این سند، حتماً اطلاعات عمومی احراز هویت و مجوز Google Workspace را در بخش «درباره احراز هویت و مجوز بیشتر بدانید» مطالعه کنید.
پیکربندی OAuth 2.0 برای احراز هویت
صفحه رضایت OAuth را پیکربندی کنید و محدودههایی را برای تعریف اطلاعات نمایش داده شده به کاربران و بررسیکنندگان برنامه انتخاب کنید و برنامه خود را ثبت کنید تا بتوانید بعداً آن را منتشر کنید.
محدودههای API رویدادهای Google Workspace
برای تعریف سطح دسترسی اعطا شده به برنامه خود، باید حوزههای مجوز را شناسایی و اعلام کنید. حوزه مجوز، یک رشته URI از نوع OAuth 2.0 است که شامل نام برنامه Google Workspace، نوع دادههایی که به آنها دسترسی دارد و سطح دسترسی است. حوزهها، درخواستهای برنامه شما برای کار با دادههای Google Workspace، از جمله دادههای حساب Google کاربران، هستند.
وقتی برنامه شما نصب میشود، از کاربر خواسته میشود تا محدودههای مورد استفاده برنامه را اعتبارسنجی کند. به طور کلی، شما باید محدودهای را انتخاب کنید که بیشترین تمرکز را داشته باشد و از درخواست محدودههایی که برنامه شما به آنها نیاز ندارد، خودداری کنید. کاربران راحتتر به محدودههای محدود و واضح دسترسی میدهند.
API رویدادهای Google Workspace از محدودههای برنامههای Google Workspace که از اشتراکها پشتیبانی میکنند، استفاده میکند. اگر برنامه شما از قبل از محدودههای مورد نیاز برای اشتراک شما استفاده میکند، نیازی به اضافه کردن محدودهها برای استفاده از API رویدادهای Google Workspace ندارید. اگر محدودههایی اضافه میکنید، محدودهای با کمترین حساسیت را انتخاب کنید که همچنان به برنامه شما اجازه عملکرد میدهد. برای جزئیات بیشتر در مورد دستههای محدوده، به دستههای محدوده مراجعه کنید.
جدول زیر محدودههای پشتیبانیشده برای Google Workspace Events API را فهرست میکند:
| کد محدوده | توضیحات | کاربرد | ||
|---|---|---|---|---|
| گوگل چت | ||||
https://www.googleapis.com/auth/chat.bot | به برنامههای چت اجازه میدهد چتها را مشاهده کرده و پیام ارسال کنند. به همه ویژگیهای موجود در برنامههای چت دسترسی میدهد. | غیر حساس | ||
https://www.googleapis.com/auth/chat.memberships | مشاهده، اضافه کردن و حذف اعضا از مکالمات در چت. | حساس | ||
https://www.googleapis.com/auth/chat.memberships.readonly | مشاهده اعضا در مکالمات چت. | حساس | ||
https://www.googleapis.com/auth/chat.app.memberships | اعضا را از مکالمات و فضاهای موجود در «چت به عنوان یک برنامه چت» ببینید، اضافه کنید، بهروزرسانی کنید و حذف کنید. نیاز به تایید مدیر دارد. این محدوده فقط از احراز هویت برنامه با حسابهای سرویس پشتیبانی میکند. شما نمیتوانید با استفاده از این محدوده، با اعتبارنامههای کاربر یا با واگذاری اختیار در سطح دامنه، احراز هویت کنید. | حساس | ||
https://www.googleapis.com/auth/chat.spaces | ایجاد گفتگوها و فضاها و مشاهده یا بهروزرسانی فرادادهها (از جمله تنظیمات تاریخچه) در چت. | حساس | ||
https://www.googleapis.com/auth/chat.spaces.readonly | مشاهده چت و فضاهای موجود در چت. | حساس | ||
https://www.googleapis.com/auth/chat.app.spaces | ایجاد مکالمات و فضاها و مشاهده یا بهروزرسانی فرادادهها (از جمله تنظیمات تاریخچه) در «چت به عنوان یک برنامه چت». نیاز به تایید مدیر دارد. این محدوده فقط از احراز هویت برنامه با حسابهای سرویس پشتیبانی میکند. شما نمیتوانید با استفاده از این محدوده، با اعتبارنامههای کاربر یا با واگذاری اختیار در سطح دامنه، احراز هویت کنید. | حساس | ||
https://www.googleapis.com/auth/chat.messages.reaction s | مشاهده، اضافه کردن و حذف واکنشها به پیامها در چت. | حساس | ||
https://www.googleapis.com/auth/chat.messages.reactions.readonly | مشاهده واکنشها به یک پیام در چت. | حساس | ||
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/drive.file | فایلهای Drive جدیدی ایجاد کنید، یا فایلهای موجود را که با یک برنامه باز میکنید یا کاربر هنگام استفاده از API انتخابگر گوگل یا انتخابگر فایل برنامه با یک برنامه به اشتراک میگذارد، تغییر دهید. | غیر حساس | ||
https://www.googleapis.com/auth/drive | تمام فایلهای Drive خود را مشاهده و مدیریت کنید. | محدود شده | ||
https://www.googleapis.com/auth/drive.readonly | تمام فایلهای Drive خود را مشاهده و دانلود کنید. | محدود شده | ||
https://www.googleapis.com/auth/drive.metadata | مشاهده و مدیریت فرادادههای فایلهای موجود در درایو شما. | محدود شده | ||
https://www.googleapis.com/auth/drive.metadata.readonly | مشاهده فراداده فایلهای موجود در درایو شما. | محدود شده | ||
| گوگل میت | ||||
https://www.googleapis.com/auth/meetings.space.created | به برنامهها اجازه دهید تا فرادادههای مربوط به فضاهای جلسه ایجاد شده توسط برنامه شما را ایجاد، اصلاح و بخوانند. | حساس | ||
https://www.googleapis.com/auth/meetings.space.readonly | به برنامهها اجازه دهید تا فرادادههای مربوط به هر فضای جلسهای که کاربر به آن دسترسی دارد را بخوانند. | حساس | ||
ستون استفاده در جدول قبلی، حساسیت هر محدوده را نشان میدهد:
غیرحساس : این محدودهها کوچکترین محدوده دسترسی مجوز را ارائه میدهند و فقط به تأیید اولیه برنامه نیاز دارند. برای اطلاعات در مورد این الزام، به الزامات تأیید مراجعه کنید.
حساس : این محدودهها دسترسی به دادههای خاص کاربر گوگل را که توسط کاربر برای برنامه شما مجاز شده است، فراهم میکنند. این امر مستلزم آن است که شما تأیید هویت برنامه را انجام دهید. برای اطلاعات بیشتر در مورد این الزام، به الزامات محدوده حساس و محدود مراجعه کنید.
محدود : این محدودهها دسترسی گستردهای به دادههای کاربر گوگل ارائه میدهند و شما را ملزم به طی کردن یک فرآیند تأیید محدوده محدود میکنند. برای اطلاعات بیشتر در مورد این الزام، به خدمات API گوگل: سیاست دادههای کاربر و الزامات اضافی برای محدودههای خاص API مراجعه کنید. اگر دادههای محدوده محدود را روی سرورها ذخیره میکنید (یا منتقل میکنید)، باید ارزیابی امنیتی را انجام دهید.
اگر برنامه شما نیاز به دسترسی به هر API گوگل دیگری دارد، میتوانید آن محدودهها را نیز اضافه کنید. برای اطلاعات بیشتر در مورد محدودههای API گوگل، به بخش «استفاده از OAuth 2.0 برای دسترسی به APIهای گوگل» مراجعه کنید.
برای اطلاعات بیشتر در مورد حوزههای خاص OAuth 2.0، به حوزههای OAuth 2.0 برای APIهای گوگل مراجعه کنید.
تأیید هویت OAuth
استفاده از برخی از محدودههای OAuth ممکن است مستلزم آن باشد که برنامه شما از طریق مرکز راهنمایی تأیید برنامه OAuth اقدام کند. برای تعیین زمان تأیید برنامه و نوع تأیید مورد نیاز، سؤالات متداول برنامه OAuth را مطالعه کنید. همچنین به شرایط خدمات Drive مراجعه کنید.
انواع احراز هویت مورد نیاز
این بخش توضیح میدهد که کدام نوع احراز هویت مورد نیاز یا پشتیبانی میشود و حوزههای پشتیبانیشده برای هر روش از Google Workspace Events API را ارائه میدهد.
برای اشتراک در رویدادهای چت، API رویدادهای Google Workspace از احراز هویت کاربر و برنامه برای فراخوانی برخی از متدهای خود پشتیبانی میکند. اگر یک متد API از هر دو اعتبارنامه پشتیبانی کند، نوع اعتبارنامه استفاده شده در فراخوانی بر نتیجهای که برگردانده میشود تأثیر میگذارد. برای مثال، اگر متد subscriptions.list را با احراز هویت کاربر فراخوانی کنید، API لیستی از اشتراکهایی را که کاربر احراز هویت شده میتواند به آنها دسترسی داشته باشد، برمیگرداند. اگر از احراز هویت برنامه استفاده کنید، API لیستی از اشتراکهایی را که برنامه میتواند به آنها دسترسی داشته باشد، برمیگرداند. برای کسب اطلاعات بیشتر در مورد انواع احراز هویت چت، به بخش احراز هویت و تأیید برنامههای چت و درخواستهای API چت مراجعه کنید.
جدول زیر نشان میدهد که کدام حوزهها و انواع احراز هویت برای هر روش Google Workspace Events API مورد نیاز یا پشتیبانی میشوند:
| روش | احراز هویت کاربر الزامی یا پشتیبانی شده | احراز هویت برنامه پشتیبانی میشود (فقط برنامههای چت) | دامنههای مجوز پشتیبانی میشوند | |
|---|---|---|---|---|
| ایجاد اشتراک | — | با احراز هویت کاربر، برای هر نوع رویداد به یک محدوده پشتیبانیشده نیاز است:
پیشنمایش توسعهدهنده : با احراز هویت برنامه و تأیید مدیر (فقط برنامههای چت)، برای هر نوع رویداد به یک محدوده پشتیبانیشده نیاز دارد:
| ||
| دریافت اشتراک | با احراز هویت کاربر، این روش به محدودهای نیاز دارد که حداقل از یک نوع رویداد برای اشتراک پشتیبانی کند . با احراز هویت برنامه (فقط برنامههای چت):
| |||
| اشتراکها را فهرست کنید | با احراز هویت کاربر، این روش به محدودهای نیاز دارد که حداقل از یک نوع رویداد برای اشتراک پشتیبانی کند . با احراز هویت برنامه (فقط برنامههای چت):
| |||
| بهروزرسانی اشتراک | — | با احراز هویت کاربر، برای هر نوع رویداد به یک محدوده پشتیبانیشده نیاز است:
پیشنمایش توسعهدهنده : با احراز هویت برنامه و تأیید مدیر (فقط برنامههای چت)، برای هر نوع رویداد به یک محدوده پشتیبانیشده نیاز دارد:
| ||
| فعالسازی مجدد اشتراک | — | با احراز هویت کاربر، برای هر نوع رویداد به یک محدوده پشتیبانیشده نیاز است:
پیشنمایش توسعهدهنده : با احراز هویت برنامه و تأیید مدیر (فقط برنامههای چت)، برای هر نوع رویداد به یک محدوده پشتیبانیشده نیاز دارد:
| ||
| حذف اشتراک | با احراز هویت کاربر، این روش به محدودهای نیاز دارد که حداقل از یک نوع رویداد برای اشتراک پشتیبانی کند . با احراز هویت برنامه (فقط برنامههای چت):
| |||
محدودهها بر اساس نوع رویداد
وقتی API رویدادهای Google Workspace را با استفاده از احراز هویت کاربر فراخوانی میکنید، باید یک یا چند محدوده (scope) را مشخص کنید که با انواع رویدادهای اشتراک مطابقت داشته باشند.
جدول زیر نشان میدهد که کدام حوزههای مجوز برای هر نوع رویداد پشتیبانی میشوند:
| رویدادها | انواع رویداد | دامنههای مجوز پشتیبانی میشوند | ||||||
|---|---|---|---|---|---|---|---|---|
| چت | ||||||||
| پیامی ارسال یا بهروزرسانی میشود. |
| با احراز هویت کاربر :
| ||||||
| یک واکنش اضافه یا حذف میشود، یا چندین واکنش تغییر میکنند. |
|
| ||||||
| یک عضویت ایجاد، بهروزرسانی یا حذف میشود، یا چندین عضویت تغییر میکنند. |
| با احراز هویت کاربر :
| ||||||
| یک فاصله بهروزرسانی یا حذف میشود. |
| با احراز هویت کاربر :
| ||||||
| رانندگی | ||||||||
| یک فایل ایجاد میشود، تغییر میکند، منتقل میشود، حذف میشود، تغییر نام میدهد، به سطل زباله انداخته میشود یا از سطل زباله حذف میشود. |
|
| ||||||
| یک پیشنهاد دسترسی روی یک فایل ایجاد یا حل میشود. |
|
| ||||||
| یک تأیید لغو، تکمیل، ایجاد، تنظیم مجدد، تغییر داوران یا پاسخ داوران به یک فایل شده است. |
|
| ||||||
| یک نظر (Comment) روی یک فایل ایجاد، حذف، ویرایش، بازگشایی یا اصلاح میشود. |
|
| ||||||
| یک پاسخ در یک فایل ایجاد، حذف یا ویرایش میشود. |
|
| ||||||
| یک مجوز روی یک فایل ایجاد، حذف یا ویرایش میشود. |
|
| ||||||
| ملاقات | ||||||||
| یک کنفرانس شروع یا پایان مییابد. |
|
| ||||||
| یک شرکتکننده به کنفرانس میپیوندد یا آن را ترک میکند. |
|
| ||||||
| یک ضبط ایجاد شد. |
|
| ||||||
| یک رونوشت تهیه شد. |
|
| ||||||