احراز هویت به عنوان یک پروژه اسکریپت برنامه‌ها با استفاده از حساب‌های سرویس

این راهنما نحوه احراز هویت با یک حساب کاربری سرویس هنگام فراخوانی APIها در Apps Script را توضیح می‌دهد.

حساب کاربری سرویس، نوع خاصی از حساب کاربری است که توسط یک برنامه کاربردی استفاده می‌شود، نه یک شخص. می‌توانید از یک حساب کاربری سرویس برای دسترسی به داده‌ها یا انجام اقدامات توسط حساب کاربری ربات، یا برای دسترسی به داده‌ها از طرف کاربران Google Workspace یا Cloud Identity استفاده کنید. برای اطلاعات بیشتر، به بخش «درک حساب‌های کاربری سرویس» مراجعه کنید.

برای مرور کلی در مورد احراز هویت برای APIهای Google Workspace، به ایجاد اعتبارنامه‌های دسترسی مراجعه کنید.

چه زمانی از حساب‌های سرویس در Apps Script استفاده کنیم؟

در اینجا چند دلیل وجود دارد که ممکن است استفاده از احراز هویت حساب سرویس را به جای سایر روش‌های احراز هویت مانند ScriptApp.getOAuthToken() در نظر بگیرید:

• عملکرد بهتر با APIها و سرویس‌های Google Cloud : بسیاری از APIهای Google Cloud برای احراز هویت حساب‌های کاربری طراحی شده‌اند. حساب‌های کاربری همچنین می‌توانند روشی یکپارچه‌تر، قابل اعتمادتر و امن‌تر برای تعامل با اکثر APIها ارائه دهند.
• مجوزهای جدا شده : حساب‌های سرویس، مجوزهای خاص خود را دارند، جدا از هر کاربری. روش احراز هویت ScriptApp.getOAuthToken() می‌تواند هنگام اشتراک‌گذاری پروژه Apps Script با سایر کاربران، با شکست مواجه شود. با استفاده از حساب‌های سرویس، می‌توانید اسکریپت‌ها را به اشتراک بگذارید و آنها را به عنوان افزونه‌های Google Workspace منتشر کنید .
• اسکریپت‌های خودکار و وظایف طولانی‌مدت : حساب‌های سرویس به شما امکان می‌دهند اسکریپت‌های خودکار، فرآیندهای دسته‌ای یا وظایف پس‌زمینه را بدون ورودی کاربر اجرا کنید.
• امنیت بهبود یافته و اصل حداقل امتیاز : شما می‌توانید به حساب‌های سرویس مجوزهای خاصی اعطا کنید و فقط به منابعی که نیاز دارند دسترسی داشته باشید. این از اصل حداقل امتیاز پیروی می‌کند که خطرات امنیتی را کاهش می‌دهد. استفاده از ScriptApp.getOAuthToken() اغلب تمام مجوزهای کاربر را به یک اسکریپت اعطا می‌کند که می‌تواند بسیار گسترده باشد.
• مدیریت دسترسی متمرکز : حساب‌های کاربری سرویس با استفاده از مدیریت هویت و دسترسی (IAM) گوگل کلود مدیریت می‌شوند. IAM می‌تواند به سازمان‌های Google Workspace کمک کند تا دسترسی به سرویس‌های احراز هویت شده را در پروژه‌های Apps Script مدیریت کنند.

پیش‌نیازها

• یک پروژه ابری گوگل .
• در پروژه ابری خود، هر API که می‌خواهید با استفاده از اعتبارنامه‌های حساب سرویس، احراز هویت کنید را فعال کنید .
• برای اختصاص نقش‌ها به حساب‌های سرویس ، باید از امتیازات فوق مدیر (super administrator) برخوردار باشید.

ایجاد حساب کاربری سرویس

در پروژه ابری خود، یک حساب کاربری سرویس ایجاد کنید:

کنسول گوگل کلود

1. در کنسول گوگل کلود، به Menu > IAM & Admin > Service Accounts بروید.

   به حساب‌های سرویس بروید

2. روی ایجاد حساب سرویس کلیک کنید.
3. جزئیات حساب سرویس را پر کنید، سپس روی ایجاد و ادامه کلیک کنید.
   توجه: به طور پیش‌فرض، گوگل یک شناسه حساب سرویس منحصر به فرد ایجاد می‌کند. اگر می‌خواهید شناسه را تغییر دهید، شناسه را در فیلد شناسه حساب سرویس تغییر دهید.
4. اختیاری: برای اعطای دسترسی به منابع پروژه Google Cloud خود، نقش‌هایی را به حساب سرویس خود اختصاص دهید. برای جزئیات بیشتر، به بخش اعطای، تغییر و لغو دسترسی به منابع مراجعه کنید.
5. روی ادامه کلیک کنید.
6. اختیاری: کاربران یا گروه‌هایی را که می‌توانند با این حساب سرویس، اقدامات را مدیریت و انجام دهند، وارد کنید. برای جزئیات بیشتر، به مدیریت جعل هویت حساب سرویس مراجعه کنید.
7. روی «انجام شد» کلیک کنید. آدرس ایمیل حساب سرویس را یادداشت کنید.

رابط خط فرمان جی‌کلاود

1. ایجاد حساب کاربری سرویس:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --display-name="SERVICE_ACCOUNT_NAME"

2. اختیاری: برای اعطای دسترسی به منابع پروژه Google Cloud خود، نقش‌هایی را به حساب سرویس خود اختصاص دهید. برای جزئیات بیشتر، به بخش اعطای، تغییر و لغو دسترسی به منابع مراجعه کنید.

اختصاص یک نقش به حساب سرویس

شما باید یک نقش از پیش ساخته شده یا سفارشی را توسط یک حساب کاربری مدیر ارشد به یک حساب کاربری سرویس اختصاص دهید.

1. در کنسول مدیریت گوگل، به Menu > Account > Admin roles بروید.

   به نقش‌های مدیریتی بروید

2. نشانگر را روی نقشی که می‌خواهید اختصاص دهید قرار دهید و سپس روی «اختصاص مدیر» کلیک کنید.

3. روی اختصاص حساب‌های سرویس کلیک کنید.

4. آدرس ایمیل حساب سرویس را وارد کنید.

5. روی افزودن > اختصاص نقش کلیک کنید.

ایجاد اعتبارنامه برای یک حساب کاربری سرویس

شما باید اعتبارنامه‌هایی را به شکل یک جفت کلید عمومی/خصوصی دریافت کنید. این اعتبارنامه‌ها توسط کد شما برای تأیید اقدامات حساب سرویس در برنامه‌تان استفاده می‌شوند.

برای دریافت اعتبارنامه برای حساب سرویس خود:

1. در کنسول گوگل کلود، به Menu > IAM & Admin > Service Accounts بروید.

   به حساب‌های سرویس بروید

2. حساب کاربری سرویس خود را انتخاب کنید.
3. روی کلیدها > افزودن کلید > ایجاد کلید جدید کلیک کنید.
4. JSON را انتخاب کنید، سپس روی ایجاد کلیک کنید.

   جفت کلید عمومی/خصوصی جدید شما ایجاد و به عنوان یک فایل جدید در دستگاه شما دانلود می‌شود. فایل JSON دانلود شده را با نام credentials.json در دایرکتوری کاری خود ذخیره کنید. این فایل تنها کپی از این کلید است. برای اطلاعات بیشتر در مورد نحوه ذخیره ایمن کلید خود، به مدیریت کلیدهای حساب سرویس مراجعه کنید.

5. روی بستن کلیک کنید.

شماره پروژه ابری را کپی کنید

1. در کنسول گوگل کلود، به Menu > IAM & Admin > Settings بروید.

   به تنظیمات IAM و مدیریت بروید

2. در فیلد شماره پروژه ، مقدار را کپی کنید.

احراز هویت حساب سرویس را در پروژه Apps Script خود تنظیم کنید

این بخش نحوه اضافه کردن اعتبارنامه‌های حساب سرویس شما از پروژه Cloud به یک پروژه Apps Script را توضیح می‌دهد.

پروژه ابری خود را در Apps Script تنظیم کنید

1. برای باز کردن یا ایجاد یک پروژه به Apps Script بروید:

   
   اسکریپت برنامه‌ها را باز کنید

2. در پروژه Apps Script خود، روی تنظیمات پروژه کلیک کنید. .

3. در زیر پروژه پلتفرم ابری گوگل (GCP) ، روی تغییر پروژه کلیک کنید.

4. در قسمت شماره پروژه GCP ، شماره پروژه Google Cloud را وارد کنید.

5. روی تنظیم پروژه کلیک کنید.

اعتبارنامه‌ها را به عنوان یک ویژگی اسکریپت ذخیره کنید

با ذخیره کردن اعتبارنامه‌های حساب سرویس خود به عنوان یک ویژگی اسکریپت در تنظیمات پروژه Apps Script خود، آنها را به طور ایمن ذخیره کنید:

1. محتویات فایل JSON حساب سرویس خود ( credentials.json ) را که در بخش قبل ایجاد کردید، کپی کنید.
2. در پروژه Apps Script خود، به Project Settings بروید.
3. از صفحه تنظیمات پروژه ، به Script Properties بروید و روی Add script property کلیک کنید و موارد زیر را وارد کنید:
   • در فیلد Property ، SERVICE_ACCOUNT_KEY را وارد کنید.
   • در فیلد Value ، محتوای فایل کلید JSON خود را وارد کنید.
4. روی ذخیره ویژگی‌های اسکریپت کلیک کنید.

کتابخانه OAuth2 را اضافه کنید

برای مدیریت جریان احراز هویت OAuth2، می‌توانید از کتابخانه Apps Script apps-script-oauth2 استفاده کنید.

برای افزودن کتابخانه به پروژه Apps Script خود:

1. در ویرایشگر اسکریپت برنامه‌ها، در سمت چپ، کنار کتابخانه‌ها ، روی کتابخانه کلیک کنید.
2. در فیلد شناسه اسکریپت ، 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF را وارد کنید.
3. روی «جستجو» کلیک کنید.
4. آخرین نسخه را انتخاب کنید و سپس روی افزودن کلیک کنید.

فراخوانی یک API با استفاده از اعتبارنامه‌های حساب سرویس

برای استفاده از اعتبارنامه‌های حساب سرویس از پروژه Apps Script خود، می‌توانید از تابع getServiceAccountService() زیر استفاده کنید:

/**
 * Get a new OAuth2 service for a given service account.
 */
function getServiceAccountService() {
  const serviceAccountKeyString = PropertiesService.getScriptProperties()
      .getProperty('SERVICE_ACCOUNT_KEY');

  if (!serviceAccountKeyString) {
    throw new Error('SERVICE_ACCOUNT_KEY property is not set. ' +
        'Please follow the setup instructions.');
  }

  const serviceAccountKey = JSON.parse(serviceAccountKeyString);

  const CLIENT_EMAIL = serviceAccountKey.client_email;
  const PRIVATE_KEY = serviceAccountKey.private_key;

  // Replace with the specific scopes required for your API.
  const SCOPES = ['SCOPE'];

  return OAuth2.createService('ServiceAccount')
      .setTokenUrl('https://oauth2.googleapis.com/token')
      .setPrivateKey(PRIVATE_KEY)
      .setIssuer(CLIENT_EMAIL)
      .setPropertyStore(PropertiesService.getScriptProperties())
      .setScope(SCOPES);
}

SCOPE با محدوده مجوزی که برای فراخوانی API نیاز دارید، جایگزین کنید. این اسکریپت از اعتبارنامه‌های حساب سرویس که در مرحله قبل به عنوان ویژگی اسکریپت SERVICE_ACCOUNT_KEY ذخیره کرده‌اید، استفاده می‌کند.

سپس می‌توانید از این اعتبارنامه‌ها برای فراخوانی یک API استفاده کنید، همانطور که در مثال زیر با سرویس UrlFetch نشان داده شده است:

function callApi() {
  const service = getServiceAccountService();

  // TODO(developer): Replace with the payload
  const payload = {};

  // TODO(developer): Replace with the API endpoint
  const response = UrlFetchApp.fetch('API_URL', {
    method: 'post',
    headers: {
      'Authorization': `Bearer ${service.getAccessToken()}`,
      'Content-Type': 'application/json',
    },
    payload: payload,
  });

  const result = JSON.parse(response.getContentText());

  return result;
}

API_URL با نقطه پایانی HTTP که فراخوانی می‌کنید جایگزین کنید.

مباحث مرتبط

• ایجاد اعتبارنامه‌های دسترسی
• احراز هویت به عنوان یک برنامه چت گوگل