این سند حاوی اطلاعات مربوط به مجوز و احراز هویت مختص Gmail API است. قبل از مطالعه این سند، حتماً اطلاعات عمومی احراز هویت و مجوز Google Workspace را در بخش «درباره احراز هویت و مجوز بیشتر بدانید» مطالعه کنید.
پیکربندی OAuth 2.0 برای احراز هویت
صفحه رضایت OAuth را پیکربندی کنید و محدودههایی را برای تعریف اطلاعات نمایش داده شده به کاربران و بررسیکنندگان برنامه انتخاب کنید و برنامه خود را ثبت کنید تا بتوانید بعداً آن را منتشر کنید.
دامنههای API جیمیل
برای تعریف سطح دسترسی اعطا شده به برنامه خود، باید حوزههای مجوز را شناسایی و اعلام کنید. حوزه مجوز، یک رشته URI از نوع OAuth 2.0 است که شامل نام برنامه Google Workspace، نوع دادههایی که به آنها دسترسی دارد و سطح دسترسی است. حوزهها، درخواستهای برنامه شما برای کار با دادههای Google Workspace، از جمله دادههای حساب Google کاربران، هستند.
وقتی برنامه شما نصب میشود، از کاربر خواسته میشود تا محدودههای مورد استفاده برنامه را اعتبارسنجی کند. به طور کلی، شما باید محدودهای را انتخاب کنید که بیشترین تمرکز را داشته باشد و از درخواست محدودههایی که برنامه شما به آنها نیاز ندارد، خودداری کنید. کاربران راحتتر به محدودههای محدود و واضح دسترسی میدهند.
هر زمان که ممکن است، از محدودههای غیرحساس استفاده کنید تا دسترسی فقط به ویژگیهای خاص مورد نیاز یک برنامه محدود شود.
اسکوپهای غیر حساس
محدودههای API جیمیل زیر برای اکثر موارد استفاده توصیه میشوند:
| کد محدوده | توضیحات |
|---|---|
https://www.googleapis.com/auth/gmail.addons.current.action.compose | هنگام تعامل با افزونه، پیشنویسها را مدیریت کنید و ایمیل ارسال کنید. |
https://www.googleapis.com/auth/gmail.addons.current.message.action | هنگام تعامل با افزونه، پیامهای ایمیل خود را مشاهده کنید. |
https://www.googleapis.com/auth/gmail.labels | برچسبهای ایمیل خود را ببینید و ویرایش کنید. |
محدودههای حساس
| کد محدوده | توضیحات |
|---|---|
https://www.googleapis.com/auth/gmail.addons.current.message.metadata | هنگام اجرای افزونه، فرادادههای پیام ایمیل خود را مشاهده کنید. |
https://www.googleapis.com/auth/gmail.addons.current.message.readonly | وقتی افزونه در حال اجرا است، پیامهای ایمیل خود را مشاهده کنید. |
https://www.googleapis.com/auth/gmail.send | از طرف شما ایمیل ارسال کند. |
دامنههای محدود
| کد محدوده | توضیحات |
|---|---|
https://mail.google.com/ | تمام ایمیلهایتان را از Gmail بخوانید، بنویسید، ارسال کنید و برای همیشه حذف کنید. نکته: این دامنه را فقط در صورتی درخواست کنید که برنامه شما نیاز به حذف فوری و دائمی رشتهها و پیامها، بدون حذف سطل زباله، داشته باشد. میتوانید سایر اقدامات را با استفاده از دامنههای با مجوز کمتر انجام دهید. |
https://www.googleapis.com/auth/gmail.readonly | پیامها و تنظیمات ایمیل خود را مشاهده کنید. |
https://www.googleapis.com/auth/gmail.compose | مدیریت پیشنویسها و ارسال ایمیل |
https://www.googleapis.com/auth/gmail.insert | ایمیلها را به صندوق پستی Gmail خود اضافه کنید. |
https://www.googleapis.com/auth/gmail.modify | خواندن، نوشتن و ارسال ایمیل از حساب Gmail شما. این محدوده اجازه حذف فوری و دائمی موضوعات و پیامها را نمیدهد و از سطل زباله عبور میکند. |
https://www.googleapis.com/auth/gmail.metadata | ابردادههای پیام ایمیل خود مانند برچسبها و سرصفحهها را مشاهده کنید، اما متن ایمیل را نمیتوانید. |
https://www.googleapis.com/auth/gmail.settings.basic | تنظیمات و فیلترهای ایمیل خود را در Gmail ببینید، ویرایش کنید، ایجاد کنید یا تغییر دهید. |
https://www.googleapis.com/auth/gmail.settings.sharing | تنظیمات حساس ایمیل خود را مدیریت کنید، از جمله اینکه چه کسی میتواند ایمیل شما را مدیریت کند. توجه: عملیات محافظتشده توسط این محدوده فقط به استفاده مدیریتی محدود میشوند. آنها فقط برای مشتریان Google Workspace که از یک حساب سرویس با نمایندگی در سطح دامنه استفاده میکنند، در دسترس هستند. |
محدودههای موجود در جداول قبلی، حساسیت آنها را طبق تعاریف زیر نشان میدهند:
غیر حساس : این حوزهها کوچکترین حوزه مجوز را ارائه میدهند و فقط به تأیید اولیه برنامه OAuth نیاز دارند. برای اطلاعات بیشتر، به الزامات تأیید مراجعه کنید.
حساس : این محدودهها دسترسی به دادههای خاص کاربر گوگل را که کاربران برای برنامه شما مجاز میدانند، فراهم میکنند. آنها به تأیید برنامه OAuth اضافی نیاز دارند. برای اطلاعات بیشتر، به الزامات محدوده حساس و محدود مراجعه کنید.
محدود شده : این حوزهها دسترسی گستردهای به دادههای کاربر گوگل ارائه میدهند و نیاز به تأیید برنامه OAuth با دامنه محدود دارند. برای اطلاعات بیشتر، به سیاست دادههای کاربر سرویسهای API گوگل و الزامات اضافی برای حوزههای خاص API مراجعه کنید.
اگر دادههای با دامنه محدود را روی سرورها ذخیره میکنید (یا منتقل میکنید)، باید ارزیابی امنیتی را انجام دهید.
اطلاعات تکمیلی که نحوه استفاده و دسترسی شما به APIهای Gmail را هنگام درخواست دسترسی به دادههای کاربر تعیین میکند، در خطمشی توسعهدهندگان و دادههای کاربر API فضای کاری گوگل (Google Workspace API) قابل دسترسی است.
اگر برنامه شما نیاز به دسترسی به هر API گوگل دیگری دارد، میتوانید آن محدودهها را نیز اضافه کنید. برای اطلاعات بیشتر در مورد محدودههای API گوگل، به بخش «استفاده از OAuth 2.0 برای دسترسی به APIهای گوگل» مراجعه کنید.
برای اطلاعات بیشتر در مورد حوزههای خاص OAuth 2.0، به حوزههای OAuth 2.0 برای APIهای گوگل مراجعه کنید.
تأیید هویت OAuth
استفاده از برخی از حوزههای حساس OAuth ممکن است برنامه شما را ملزم به تکمیل فرآیند تأیید OAuth گوگل کند. سوالات متداول تأیید برنامه OAuth میتواند به شما در تعیین لزوم این کار و نوع تأیید مورد نیاز کمک کند.