از اعتبارنامهها برای دریافت توکن دسترسی از سرورهای مجوز گوگل استفاده میشود تا برنامه شما بتواند APIهای Google Workspace را فراخوانی کند. این سند نحوه انتخاب و تنظیم اعتبارنامههای مورد نیاز برنامه شما را شرح میدهد.
اعتبارنامه دسترسی مناسب خود را انتخاب کنید
اعتبارنامههای مورد نیاز به نوع داده، پلتفرم و روش دسترسی برنامه شما بستگی دارد. سه نوع اعتبارنامه در دسترس است:
| مورد استفاده | روش احراز هویت | درباره این روش احراز هویت |
|---|---|---|
| به دادههای عمومی موجود در برنامه خود به صورت ناشناس دسترسی پیدا کنید. | کلیدهای API | قبل از استفاده از این روش احراز هویت، بررسی کنید که API مورد نظر شما از کلیدهای API پشتیبانی میکند. |
| به دادههای کاربر مانند آدرس ایمیل یا سن آنها دسترسی پیدا کنید. | شناسه کلاینت OAuth | برنامه شما را ملزم به درخواست و دریافت رضایت از کاربر میکند. |
| به دادههای متعلق به برنامه خود، اسناد مشترک خاص (مانند Google Sheets) دسترسی داشته باشید، یا از طریق واگذاری اختیار در سطح دامنه، به نمایندگی از کاربران به منابع Google Workspace دسترسی پیدا کنید. | حساب کاربری خدمات | وقتی یک برنامه به عنوان یک حساب سرویس احراز هویت میشود، به تمام منابعی که حساب سرویس اجازه دسترسی به آنها را دارد، دسترسی پیدا میکند. |
برای تعاریف اصطلاحات موجود در این صفحه، به نمای کلی احراز هویت و مجوز مراجعه کنید.
اعتبارنامههای کلید API
کلید API یک رشته طولانی است که شامل حروف بزرگ و کوچک، اعداد، زیرخط و خط فاصله است، مانند AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe . این روش احراز هویت برای دسترسی ناشناس به دادههای عمومی، مانند فایلهای Google Workspace که با استفاده از تنظیم اشتراکگذاری «هر کسی در اینترنت با این لینک» به اشتراک گذاشته شده است، استفاده میشود. برای جزئیات بیشتر، به مدیریت کلیدهای API مراجعه کنید.
برای ایجاد کلید API:
- در کنسول گوگل کلود، به Menu > APIs & Services > Credentials بروید.
- روی ایجاد اعتبارنامه > کلید API کلیک کنید.
- کلید API جدید شما نمایش داده میشود.
- برای کپی کردن کلید API خود جهت استفاده در کد برنامه، روی گزینه کپی کردن کلیک کنید. کلید API را میتوانید در بخش «کلیدهای API» در اعتبارنامههای پروژه خود نیز پیدا کنید.
- برای جلوگیری از استفاده غیرمجاز، توصیه میکنیم مکان و نوع APIهایی که کلید API میتواند استفاده شود را محدود کنید. برای جزئیات بیشتر، به افزودن محدودیتهای API مراجعه کنید.
اعتبارنامههای شناسه کلاینت OAuth
برای احراز هویت کاربران نهایی و دسترسی به دادههای کاربر در برنامه خود، باید یک یا چند شناسه کلاینت OAuth 2.0 ایجاد کنید. شناسه کلاینت برای شناسایی یک برنامه واحد به سرورهای OAuth گوگل استفاده میشود. اگر برنامه شما روی چندین پلتفرم اجرا میشود، باید برای هر پلتفرم یک شناسه کلاینت جداگانه ایجاد کنید.برای دستورالعملهای خاص در مورد نحوه ایجاد شناسه کلاینت OAuth ، نوع برنامه خود را انتخاب کنید:
برنامه وب
- در کنسول ابری گوگل، به Menu > Google Auth platform > Clients بروید.
- روی ایجاد کلاینت کلیک کنید.
- روی نوع برنامه > برنامه وب کلیک کنید.
- در فیلد نام ، نامی برای اعتبارنامه تایپ کنید. این نام فقط در کنسول ابری گوگل نمایش داده میشود.
- URI های مجاز مربوط به برنامه خود را اضافه کنید:
- برنامههای سمت کلاینت (جاوااسکریپت) – در قسمت Authorized JavaScript origins ، روی Add URI کلیک کنید. سپس، یک URI برای استفاده در درخواستهای مرورگر وارد کنید. این دامنههایی را که برنامه شما میتواند از آنها درخواستهای API را به سرور OAuth 2.0 ارسال کند، مشخص میکند.
- برنامههای سمت سرور (جاوا، پایتون و موارد دیگر) – در زیر Authorized redirect URIs ، روی Add URI کلیک کنید. سپس، یک URI نقطه پایانی که سرور OAuth 2.0 میتواند به آن پاسخ ارسال کند را وارد کنید.
- روی ایجاد کلیک کنید.
اعتبارنامهی تازه ایجاد شده در زیر شناسههای کلاینت OAuth 2.0 ظاهر میشود.
توجه داشته باشید که از رمزهای کلاینت برای برنامههای وب استفاده نمیشود.
اندروید
- در کنسول ابری گوگل، به Menu > Google Auth platform > Clients بروید.
- روی ایجاد کلاینت کلیک کنید.
- روی نوع برنامه > اندروید کلیک کنید.
- در فیلد نام ، نامی برای اعتبارنامه تایپ کنید. این نام فقط در کنسول ابری گوگل نمایش داده میشود.
- در فیلد Package name ، نام پکیج را از فایل
AndroidManifest.xmlخود وارد کنید. - در فیلد اثر انگشت گواهی SHA-1 ، اثر انگشت گواهی SHA-1 تولید شده خود را وارد کنید.
- روی ایجاد کلیک کنید.
اعتبارنامهی تازه ایجاد شده در زیر «OAuth 2.0 Client IDs» ظاهر میشود.
آیاواس
- در کنسول ابری گوگل، به Menu > Google Auth platform > Clients بروید.
- روی ایجاد کلاینت کلیک کنید.
- روی نوع برنامه > iOS کلیک کنید.
- در فیلد نام ، نامی برای اعتبارنامه تایپ کنید. این نام فقط در کنسول ابری گوگل نمایش داده میشود.
- در فیلد Bundle ID ، شناسهی بستهی نرمافزاری را که در فایل
Info.plistبرنامه ذکر شده است، وارد کنید. - اختیاری: اگر برنامه شما در فروشگاه اپل اپ استور (Apple App Store) نمایش داده میشود، شناسه فروشگاه اپ (App Store ID) را وارد کنید.
- اختیاری: در فیلد شناسه تیم ، رشته ۱۰ کاراکتری منحصر به فردی را که توسط اپل تولید شده و به تیم شما اختصاص داده شده است، وارد کنید.
- روی ایجاد کلیک کنید.
اعتبارنامهی تازه ایجاد شده در زیر «OAuth 2.0 Client IDs» ظاهر میشود.
افزونه کروم
- در کنسول ابری گوگل، به Menu > Google Auth platform > Clients بروید.
- روی ایجاد کلاینت کلیک کنید.
- روی نوع برنامه > افزونه کروم کلیک کنید.
- در فیلد نام ، نامی برای اعتبارنامه تایپ کنید. این نام فقط در کنسول ابری گوگل نمایش داده میشود.
- در فیلد شناسه کالا ، رشته شناسه ۳۲ کاراکتری منحصر به فرد برنامه خود را وارد کنید. میتوانید این مقدار شناسه را در نشانی اینترنتی فروشگاه وب کروم برنامه خود و در داشبورد توسعهدهندگان فروشگاه وب کروم پیدا کنید.
- روی ایجاد کلیک کنید.
اعتبارنامهی تازه ایجاد شده در زیر «OAuth 2.0 Client IDs» ظاهر میشود.
برنامه دسکتاپ
- در کنسول ابری گوگل، به Menu > Google Auth platform > Clients بروید.
- روی ایجاد کلاینت کلیک کنید.
- روی نوع برنامه > برنامه دسکتاپ کلیک کنید.
- در فیلد نام ، نامی برای اعتبارنامه تایپ کنید. این نام فقط در کنسول ابری گوگل نمایش داده میشود.
- روی ایجاد کلیک کنید.
اعتبارنامهی تازه ایجاد شده در زیر «OAuth 2.0 Client IDs» ظاهر میشود.
تلویزیونها و دستگاههای ورودی محدود
- در کنسول ابری گوگل، به Menu > Google Auth platform > Clients بروید.
- روی ایجاد کلاینت کلیک کنید.
- روی نوع برنامه > تلویزیونها و دستگاههای ورودی محدود کلیک کنید.
- در فیلد نام ، نامی برای اعتبارنامه تایپ کنید. این نام فقط در کنسول ابری گوگل نمایش داده میشود.
- روی ایجاد کلیک کنید.
اعتبارنامهی تازه ایجاد شده در زیر «OAuth 2.0 Client IDs» ظاهر میشود.
اعتبارنامه حساب سرویس
حساب سرویس نوع خاصی از حساب است که توسط یک برنامه استفاده میشود، نه یک شخص. میتوانید از یک حساب سرویس برای دسترسی به دادهها یا انجام اقدامات توسط حساب ربات، یا برای دسترسی به دادهها از طرف کاربران Google Workspace یا Cloud Identity استفاده کنید. برای اطلاعات بیشتر، به نمای کلی حسابهای سرویس مراجعه کنید.توجه داشته باشید که نقشهای مدیریت هویت و دسترسی (IAM) که در کنسول Google Cloud پیکربندی شدهاند، به داراییهای Google Workspace (مانند Sheets یا Gmail) دسترسی نمیدهند . برای دسترسی به یک حساب کاربری سرویس به منابع Google Workspace، میتوانید از موارد زیر استفاده کنید:
| اگر برنامه شما نیاز دارد که... | از کجا باید تنظیماتش رو انجام بدم... |
|---|---|
| دسترسی به فایلهای خاص (مانند یک Google Sheet) | اشتراکگذاری مستقیم سند یک فایل یا پوشه با آدرس ایمیل حساب سرویس |
| انجام مدیریت دامنه (مانند ایجاد کاربران Google Workspace) | نقشهای مدیریتی را مستقیماً به حساب سرویس اختصاص دهید |
| دسترسی به دادههای کاربر در سراسر دامنه (مانند خواندن رویدادهای Gmail یا تقویم Google هر کاربر) | به حساب کاربری سرویس اجازه دهید تا از نمایندگی در سطح دامنه استفاده کند |
ایجاد حساب کاربری سرویس
شما میتوانید با استفاده از کنسول گوگل کلود یا ابزار خط فرمان gcloud یک حساب کاربری ایجاد کنید.
کنسول ابری گوگل
- در کنسول گوگل کلود، به Menu > IAM & Admin > Service Accounts بروید.
مراحل باقی مانده در کنسول ابری گوگل (Google Cloud Console) نمایش داده میشوند.
- یک پروژه Google Cloud انتخاب کنید.
- روی ایجاد حساب سرویس کلیک کنید.
- نام حساب سرویس را برای نمایش در کنسول Google Cloud وارد کنید.
- اگر نمیخواهید اکنون کنترلهای دسترسی را تنظیم کنید، برای پایان ایجاد حساب سرویس، روی «انجام شد» کلیک کنید. برای تنظیم کنترلهای دسترسی اکنون، روی «ایجاد و ادامه» کلیک کنید و به مرحله بعدی بروید.
- اختیاری: برای اعطای دسترسی به منابع پروژه Google Cloud خود علاوه بر منابع Google Workspace، نقشهایی را به حساب سرویس خود اختصاص دهید. برای جزئیات بیشتر، به مدیریت دسترسی به پروژهها، پوشهها و سازمانها مراجعه کنید.
- روی ادامه کلیک کنید.
- اختیاری: کاربران یا گروههایی را که میتوانند با این حساب سرویس، اقدامات را مدیریت و انجام دهند، وارد کنید. برای جزئیات بیشتر، به جعل هویت حساب سرویس مراجعه کنید.
- برای پایان ایجاد حساب کاربری سرویس، روی «انجام شد» کلیک کنید.
آدرس ایمیل مربوط به حساب سرویس را یادداشت کنید.
رابط خط فرمان جیکلاود
- ایجاد حساب کاربری سرویس:
gcloud iam service-accounts createSERVICE_ACCOUNT_NAME\ --display-name="SERVICE_ACCOUNT_NAME" - اختیاری: برای اعطای دسترسی به منابع پروژه Google Cloud خود علاوه بر منابع Google Workspace، نقشهایی را به حساب سرویس خود اختصاص دهید. برای جزئیات بیشتر، به مدیریت دسترسی به پروژهها، پوشهها و سازمانها مراجعه کنید.
دسترسی مستقیم به فایلهای Google Workspace با یک حساب کاربری سرویس
اگر برنامه شما فقط نیاز به خواندن یا نوشتن فایلهای خاص (مانند یک Google Sheet یا یک پوشه Google Drive) دارد، نیازی به اختصاص نقشهای مدیریتی یا پیکربندی واگذاری اختیارات در سطح دامنه ندارید. در عوض، میتوانید مستقیماً فایلهای جداگانه را با آدرس ایمیل حساب سرویس با استفاده از رابط کاربری استاندارد به اشتراک بگذارید. میتوانید آدرس ایمیل حساب سرویس را به عنوان یک حساب کاربری در تنظیمات اشتراکگذاری سند، بدون نیاز به امتیازات مدیریتی، در نظر بگیرید.
برای اعطای دسترسی:
- آدرس ایمیل حساب سرویس خود را کپی کنید. برای مثال،
my-service-account@my-project.iam.gserviceaccount.com. - سند Sheets یا پوشه Drive مورد نظر برای دسترسی را باز کنید.
- روی اشتراکگذاری کلیک کنید.
- آدرس ایمیل حساب سرویس را اضافه کنید و سطح دسترسی مناسب (مانند ویرایشگر یا مشاهدهگر) را تعیین کنید.
- گزینه «به افراد اطلاع دهید» را از حالت انتخاب خارج کنید (از آنجایی که حسابهای کاربری سرویس صندوق ورودی ندارند، ایمیل دعوتنامه را دریافت نمیکنند، اما مجوز همچنان اعطا میشود).
- روی اشتراکگذاری کلیک کنید.
ایجاد کلید حساب سرویس
شما باید اعتبارنامههایی را به شکل یک جفت کلید عمومی/خصوصی دریافت کنید. این اعتبارنامهها توسط کد شما برای تأیید اقدامات حساب سرویس در برنامهتان استفاده میشوند.برای ایجاد کلید حساب سرویس:
- در کنسول گوگل کلود، به Menu > IAM & Admin > Service Accounts بروید.
مراحل باقی مانده در کنسول ابری گوگل (Google Cloud Console) نمایش داده میشوند.
- یک پروژه Google Cloud انتخاب کنید.
- روی آدرس ایمیل حساب سرویسی که میخواهید برای آن کلید ایجاد کنید، کلیک کنید.
- روی برگه کلیدها کلیک کنید.
- روی منوی کشویی «افزودن کلید» کلیک کنید، سپس «ایجاد کلید جدید» را انتخاب کنید.
- نوع کلید را JSON انتخاب کنید و روی Create کلیک کنید.
جفت کلید عمومی/خصوصی جدید شما تولید و به عنوان یک فایل کلید حساب سرویس در دستگاه شما دانلود میشود. فایل JSON دانلود شده را با نام
credentials.jsonدر دایرکتوری کاری خود ذخیره کنید. این فایل تنها کپی از این کلید است. پس از دانلود فایل کلید، نمیتوانید دوباره آن را دانلود کنید. برای کسب اطلاعات در مورد نحوه ذخیره ایمن کلید خود، به بهترین شیوهها برای مدیریت کلیدهای حساب سرویس مراجعه کنید.
اختصاص نقش مدیر Google Workspace به یک حساب سرویس
شما میتوانید هر نقش از پیش ساخته شده یا سفارشی Google Workspace را به یک حساب سرویس اختصاص دهید، به استثنای نقش مدیر ارشد.
در کنسول مدیریت گوگل، به Menu > Account > Admin roles بروید.
برای این کار باید به عنوان مدیر ارشد (Super Admin) وارد سیستم شوید.
مراحل باقی مانده در کنسول مدیریت گوگل نمایش داده میشوند.
روی نقشی که میخواهید اختصاص دهید اشاره کنید، روی منوی کشویی
Actionsکلیک کنید و «اختصاص مدیر» را انتخاب کنید.روی اختصاص حسابهای سرویس کلیک کنید.
آدرس ایمیل حساب سرویس را وارد کنید.
روی افزودن > اختصاص نقش کلیک کنید.
اختیاری: تنظیم نمایندگی در سطح دامنه برای یک حساب کاربری سرویس
وقتی برنامه شما نیاز دارد که از طرف چندین کاربر در سازمان شما به دادههای Google Workspace دسترسی داشته باشد (مانند ارسال ایمیل با استفاده از Gmail API) بدون نیاز به رضایت تک تک کاربران، از واگذاری اختیارات در سطح دامنه استفاده کنید. برای فراخوانی APIها از طرف کاربران در یک سازمان Google Workspace، با استفاده از یک حساب کاربری مدیر ارشد ، به حساب کاربری سرویس خود در کنسول Google Admin، تفویض اختیارات در سطح دامنه اعطا کنید. برای اطلاعات بیشتر، به بخش واگذاری اختیارات در سطح دامنه به حساب کاربری سرویس مراجعه کنید.برای تنظیم واگذاری اختیارات در سطح دامنه برای یک حساب کاربری سرویس:
- در کنسول گوگل کلود، به Menu > IAM & Admin > Service Accounts بروید.
- یک پروژه Google Cloud انتخاب کنید.
- روی آدرس ایمیل حساب سرویسی که میخواهید برای آن نمایندگی در سطح دامنه تنظیم کنید، کلیک کنید.
- روی نمایش تنظیمات پیشرفته کلیک کنید.
- در بخش «واگذاری در سطح دامنه»، «شناسه کلاینت» حساب سرویس خود را پیدا کنید.
- برای کپی کردن مقدار شناسه کلاینت در کلیپبورد، روی کپی کردن کلیک کنید.
اگر به حساب کاربری گوگل ورکاسپیس مربوطه دسترسی مدیر ارشد (Super Admin) دارید، روی «مشاهده کنسول مدیریت گوگل ورکاسپیس» کلیک کنید، با حساب کاربری مدیر ارشد خود وارد شوید و مراحل زیر را ادامه دهید.
اگر به حساب کاربری گوگل ورکاسپیس مربوطه دسترسی مدیر ارشد ندارید، با یک مدیر ارشد برای حساب کاربری تماس بگیرید. شناسه کلاینت حساب کاربری سرویس خود و لیستی از محدودههای OAuth مورد نیاز برنامه خود را برای آنها ارسال کنید تا بتوانند مراحل زیر را در کنسول گوگل ادمین انجام دهند.
- در کنسول مدیریت گوگل، به Menu > Security > Access and data control > API controls بروید.
- روی مدیریت نمایندگی در سطح دامنه کلیک کنید.
- روی افزودن جدید کلیک کنید.
- در فیلد شناسه مشتری ، شناسه مشتری که قبلاً کپی کردهاید را جایگذاری کنید.
- در فیلد OAuth Scopes ، فهرستی از scopeهای مورد نیاز برنامه خود را که با کاما از هم جدا شدهاند، وارد کنید. این همان مجموعهای از scopeهایی است که هنگام پیکربندی صفحه رضایت OAuth تعریف کردهاید.
- روی تأیید کلیک کنید.
تغییرات میتوانند تا ۲۴ ساعت طول بکشند اما معمولاً سریعتر اتفاق میافتند. برای اطلاعات بیشتر، به بخش «کنترل دسترسی API با واگذاری اختیارات در سطح دامنه» مراجعه کنید.
مرحله بعدی
شما آماده توسعه در Google Workspace هستید! فهرست محصولات توسعهدهندگان Google Workspace و نحوه یافتن کمک را مرور کنید.