אימות כפרויקט של Google Apps Script באמצעות חשבונות שירות

במדריך הזה מוסבר איך לבצע אימות באמצעות חשבון שירות כשקוראים לממשקי API ב-Apps Script.

חשבון שירות הוא סוג מיוחד של חשבון, שאפליקציה (ולא אדם) משתמשת בו. אפשר להשתמש בחשבון שירות כדי לגשת לנתונים או לבצע פעולות באמצעות חשבון הרובוט, או כדי לגשת לנתונים בשם משתמשי Google Workspace או Cloud Identity. מידע נוסף זמין במאמר עבודה עם חשבון שירות.

לסקירה כללית על אימות עבור ממשקי API של Google Workspace, ראו יצירת פרטי כניסה.

מתי כדאי להשתמש בחשבונות שירות ב-Apps Script

כברירת מחדל, Apps Script משתמש בפרטי הכניסה של המשתמש בסקריפט כדי לקרוא לממשקי API. אם אתם קוראים ל-Google APIs באמצעות UrlFetchApp, אתם יכולים לקבל אסימון גישה למשתמש הסקריפט על ידי קריאה ל-ScriptApp.getOAuthToken.

עם זאת, שימוש בחשבונות שירות מספק כמה יתרונות על פני ScriptApp.getOAuthToken בתרחישים מסוימים. כדאי להשתמש באימות של חשבון שירות מהסיבות הבאות:

• ביצועים טובים יותר עם ממשקי API ושירותים של Google Cloud: ממשקי API רבים של Google Cloud מיועדים לאימות של חשבונות שירות. חשבונות שירות יכולים גם לספק דרך משולבת, אמינה ומאובטחת יותר ליצירת אינטראקציה עם רוב ממשקי ה-API.
• הרשאות מנותקות: לחשבונות שירות יש הרשאות משלהם, בנפרד מכל משתמש. שיטת האימות ScriptApp.getOAuthToken עלולה להיכשל כשמשתפים את הפרויקט עם משתמשים אחרים. באמצעות חשבונות שירות, אפשר לשתף סקריפטים ולפרסם אותם כתוספים ל-Google Workspace.
• סקריפטים אוטומטיים ומשימות שפועלות לאורך זמן: חשבונות שירות מאפשרים להריץ סקריפטים אוטומטיים, תהליכים של אצווה או משימות ברקע ללא קלט של משתמשים.
• אבטחה משופרת והעקרון של הרשאות מינימליות: מעניקים לחשבונות שירות הרשאות ספציפיות, וכך מספקים גישה רק למשאבים שהם צריכים. הגישה הזו מבוססת על העיקרון של הרשאות מינימליות, שמצמצם את סיכוני האבטחה. שימוש ב-ScriptApp.getOAuthToken מעניק לרוב לסקריפט את כל הרשאות המשתמש, וזה יכול להיות רחב מדי.
• ניהול גישה מרכזי: חשבונות שירות מנוהלים באמצעות ניהול הזהויות והרשאות הגישה (IAM) של Google Cloud. ‫IAM עוזר לארגונים ב-Google Workspace לנהל את הגישה לשירותים מאומתים בפרויקטים של Apps Script.

דרישות מוקדמות

• פרויקט ב-Google Cloud.
• בפרויקט ב-Cloud, מפעילים את כל ממשקי ה-API שרוצים לבצע אליהם אימות באמצעות פרטי כניסה של חשבון שירות.
• כדי להקצות תפקידים לחשבונות שירות, צריך הרשאות של סופר-אדמין.

יצירה של חשבון שירות

יוצרים חשבון שירות בפרויקט בענן:

מסוף Google Cloud

1. במסוף Google Cloud, לוחצים על סמל התפריט > IAM & Admin > Service Accounts (חשבונות שירות).

   לדף Service accounts

2. לוחצים על יצירת חשבון שירות.
3. ממלאים את פרטי חשבון השירות ולוחצים על יצירה והמשך.
   הערה: כברירת מחדל, Google יוצרת מזהה ייחודי לחשבון שירות. אם רוצים לשנות את המזהה, משנים אותו בשדה של מזהה חשבון השירות.
4. אופציונלי: מקצים תפקידים לחשבון השירות כדי לתת גישה למשאבים בפרויקט Google Cloud. פרטים נוספים זמינים במאמר הענקה, שינוי וביטול גישה למשאבים.
5. לוחצים על המשך.
6. אופציונלי: מזינים משתמשים או קבוצות שיכולים לנהל את חשבון השירות הזה ולבצע בו פעולות. פרטים נוספים מופיעים במאמר ניהול התחזות לחשבון שירות.
7. לוחצים על סיום. רושמים את כתובת האימייל של חשבון השירות.

‫CLI של gcloud

1. יוצרים את חשבון השירות:

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

2. אופציונלי: מקצים תפקידים לחשבון השירות כדי לתת גישה למשאבים בפרויקט Google Cloud. פרטים נוספים זמינים במאמר הענקה, שינוי וביטול גישה למשאבים.

הקצאת תפקיד לחשבון שירות

צריך להקצות לחשבון שירות תפקיד מוגדר מראש או תפקיד בהתאמה אישית דרך חשבון סופר-אדמין.

1. במסוף Google Admin, נכנסים לתפריט > חשבון > תפקידי אדמין.

   מעבר אל תפקידי אדמין

2. מצביעים על התפקיד שרוצים להקצות ולוחצים על הקצאת אדמין.

3. לוחצים על בחירת חשבונות שירות לתפקיד.

4. מזינים את כתובת האימייל של חשבון השירות.

5. לוחצים על הוספה > הקצאת תפקיד.

יצירת פרטי כניסה לחשבון שירות

צריך לקבל פרטי כניסה בצורה של זוג מפתחות ציבורי/פרטי. הקוד משתמש בפרטי הכניסה האלה כדי לאשר פעולות של חשבון שירות באפליקציה.

כדי לקבל פרטי כניסה לחשבון השירות:

1. במסוף Google Cloud, לוחצים על סמל התפריט > IAM & Admin > Service Accounts (חשבונות שירות).

   לדף Service accounts

2. בוחרים את חשבון השירות.
3. לוחצים על מפתחות > הוספת מפתח > יצירת מפתח חדש.
4. בוחרים באפשרות JSON ולוחצים על Create.

   זוג המפתחות הציבורי/פרטי החדש נוצר ומורד למחשב שלכם כקובץ חדש. שומרים את קובץ ה-JSON שהורדתם בשם credentials.json בספריית העבודה. הקובץ הזה הוא העותק היחיד של המפתח. מידע על אחסון מאובטח של המפתח זמין במאמר ניהול מפתחות לחשבונות שירות.

5. לוחצים על סגירה.

מעתיקים את מספר הפרויקט בענן

1. במסוף Google Cloud, לוחצים על סמל התפריט > IAM & Admin > Settings (הגדרות).

   כניסה לדף IAM & Admin Settings

2. מעתיקים את הערך בשדה מספר הפרויקט.

הגדרת אימות של חשבון שירות בפרויקט Apps Script

בקטע הזה מוסבר איך להוסיף את פרטי הכניסה של חשבון השירות מפרויקט בענן לפרויקט Apps Script.

הגדרת פרויקט בענן ב-Apps Script

1. כדי לפתוח או ליצור פרויקט, עוברים אל Apps Script:

   
   פתיחת Apps Script

2. בפרויקט Apps Script, לוחצים על הגדרות הפרויקט .

3. בקטע פרויקט ב-Google Cloud, לוחצים על שינוי הפרויקט.

4. בקטע מספר הפרויקט ב-Google Cloud, מדביקים את מספר הפרויקט בענן.

5. לוחצים על הגדרת פרויקט.

שמירת פרטי הכניסה כמאפיין סקריפט

כדי לאחסן את פרטי הכניסה של חשבון השירות בצורה מאובטחת, שומרים אותם כמאפיין סקריפט ב<פלטפורמה>הגדרות הפרויקט</פלטפורמה> של פרויקט Apps Script:

1. מעתיקים את התוכן של קובץ ה-JSON של חשבון השירות (credentials.json) שיצרתם בקטע הקודם.
2. בפרויקט Apps Script, עוברים אל הגדרות הפרויקט .
3. בדף Project Settings (הגדרות הפרויקט), עוברים אל Script Properties (מאפייני הסקריפט), לוחצים על Add script property (הוספת מאפיין סקריפט) ומזינים את הפרטים הבאים:
   • בשדה מאפיין מזינים SERVICE_ACCOUNT_KEY.
   • בשדה Value (ערך), מדביקים את התוכן של קובץ מפתח ה-JSON.
4. לוחצים על שמירת מאפייני סקריפט.

הוספת ספריית OAuth2

כדי לטפל בתהליך האימות של OAuth2, משתמשים בספריית Apps Script‏ apps-script-oauth2.

כדי להוסיף את הספרייה לפרויקט Apps Script:

1. בצד ימין של עורך Apps Script, לצד ספריות, לוחצים על הוספת ספרייה .
2. בשדה Script ID (מזהה הסקריפט), מזינים את הערך 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 שאתם קוראים לה.

נושאים קשורים

• יצירת פרטי גישה
• אימות כאפליקציית Google Chat