المصادقة كمشروع Apps Script باستخدام حسابات الخدمة

يوضّح هذا الدليل كيفية المصادقة باستخدام حساب خدمة عند استدعاء واجهات برمجة التطبيقات في Apps Script.

حساب الخدمة هو نوع خاص من الحسابات تستخدمه التطبيقات، وليس الأشخاص. يمكنك استخدام حساب خدمة للوصول إلى البيانات أو تنفيذ إجراءات من خلال حساب الروبوت، أو للوصول إلى البيانات نيابةً عن مستخدمي Google Workspace أو Cloud Identity. لمزيد من المعلومات، يُرجى الاطّلاع على التعرّف على حسابات الخدمة.

للحصول على نظرة عامة حول المصادقة في واجهات برمجة التطبيقات في Google Workspace، يُرجى الاطّلاع على إنشاء بيانات اعتماد الوصول.

حالات استخدام حسابات الخدمة في Apps Script

في ما يلي بعض الأسباب التي قد تدفعك إلى استخدام مصادقة حساب الخدمة بدلاً من طرق المصادقة الأخرى، مثل ScriptApp.getOAuthToken():

• أداء أفضل باستخدام واجهات برمجة التطبيقات والخدمات في Google Cloud: تم تصميم العديد من واجهات برمجة التطبيقات في Google Cloud للمصادقة على حسابات الخدمة. يمكن أن توفّر حسابات الخدمة أيضًا طريقة أكثر تكاملاً وموثوقية وأمانًا للتفاعل مع معظم واجهات برمجة التطبيقات.
• أذونات منفصلة: تتضمّن حسابات الخدمة أذونات خاصة بها، منفصلة عن أي مستخدم. قد تتعذّر طريقة المصادقة ScriptApp.getOAuthToken() عند مشاركة مشروع Apps Script مع مستخدمين آخرين. باستخدام حسابات الخدمة، يمكنك مشاركة البرامج النصية ونشرها كإضافات في Google Workspace.
• النصوص البرمجية المبرمَجة والمهام التي تستغرق وقتًا طويلاً: تتيح لك حسابات الخدمة تشغيل النصوص البرمجية المبرمَجة أو العمليات المجمّعة أو المهام التي تعمل في الخلفية بدون إدخال أي بيانات من المستخدم.
• أمان محسّن ومبدأ الحدّ الأدنى من الأذونات المميّزة: يمكنك منح حسابات الخدمة أذونات معيّنة، ما يتيح الوصول فقط إلى الموارد التي تحتاج إليها. ويتماشى ذلك مع مبدأ الحدّ الأدنى من الأذونات المميّزة، ما يقلّل من المخاطر الأمنية. يؤدي استخدام ScriptApp.getOAuthToken() غالبًا إلى منح النص البرمجي جميع أذونات المستخدم، ما قد يكون نطاقه واسعًا جدًا.
• إدارة الوصول المركزية: تتم إدارة حسابات الخدمة باستخدام إدارة الهوية وإمكانية الوصول (IAM) في Google Cloud. يمكن أن تساعد إدارة الهوية وإمكانية الوصول مؤسسات Google Workspace في إدارة إمكانية الوصول إلى الخدمات التي تم إثبات صحتها ضمن مشاريع "برمجة تطبيقات Google".

المتطلبات الأساسية

• مشروع Google Cloud
• في مشروعك على السحابة الإلكترونية، فعِّل أي واجهات برمجة تطبيقات تريد المصادقة عليها باستخدام بيانات اعتماد حساب الخدمة.
• لإسناد أدوار إلى حسابات الخدمة، يجب أن تتوفّر لك امتيازات المشرف المتميّز.

إنشاء حساب خدمة

في مشروعك على السحابة الإلكترونية، أنشئ حساب خدمة:

Google Cloud Console

1. في Google Cloud Console، انتقِل إلى "القائمة" > المشرف وإدارة الهوية وإمكانية الوصول > حسابات الخدمة.

   الانتقال إلى "حسابات الخدمة"

2. انقر على إنشاء حساب خدمة.
3. املأ تفاصيل حساب الخدمة، ثم انقر على إنشاء ومتابعة.
   ملاحظة: تنشئ Google تلقائيًا معرّفًا فريدًا لحساب الخدمة. إذا أردت تغيير المعرّف، عدِّله في حقل معرّف حساب الخدمة.
4. اختياري: يمكنك إسناد أدوار إلى حساب الخدمة لمنحه إذن الوصول إلى موارد مشروعك على Google Cloud. لمزيد من التفاصيل، يُرجى الرجوع إلى منح إذن الوصول إلى الموارد وتغييره وإبطاله.
5. انقر على متابعة.
6. اختياري: أدخِل المستخدمين أو المجموعات التي يمكنها إدارة حساب الخدمة هذا وتنفيذ إجراءات فيه. لمزيد من التفاصيل، يُرجى الاطّلاع على إدارة انتحال هوية حساب الخدمة.
7. انقر على تم. دوِّن عنوان البريد الإلكتروني لحساب الخدمة.

gcloud CLI

1. أنشئ حساب الخدمة:

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

2. اختياري: يمكنك إسناد أدوار إلى حساب الخدمة لمنحه إذن الوصول إلى موارد مشروعك على Google Cloud. لمزيد من التفاصيل، يُرجى الرجوع إلى منح إذن الوصول إلى الموارد وتغييره وإبطاله.

إسناد دور إلى حساب الخدمة

يجب أن يمنح حساب مشرف متميّز دورًا محددًا مسبقًا أو مخصَّصًا لحساب خدمة.

1. في "وحدة تحكّم المشرف في Google"، انتقِل إلى "القائمة" > الحساب > أدوار المشرف.

   الانتقال إلى "أدوار المشرف"

2. أشِر إلى الدور الذي تريد إسناده، ثم انقر على إسناد دور مشرف.

3. انقر على تخصيص حسابات الخدمة.

4. أدخِل عنوان البريد الإلكتروني لحساب الخدمة.

5. انقر على إضافة > تعيين الدور.

إنشاء بيانات اعتماد لحساب خدمة

يجب الحصول على بيانات اعتماد في شكل زوج مفاتيح عامة/خاصة. تستخدم التعليمات البرمجية هذه بيانات الاعتماد لتفويض إجراءات حساب الخدمة داخل تطبيقك.

للحصول على بيانات اعتماد حساب الخدمة، اتّبِع الخطوات التالية:

1. في Google Cloud Console، انتقِل إلى "القائمة" > المشرف وإدارة الهوية وإمكانية الوصول > حسابات الخدمة.

   الانتقال إلى "حسابات الخدمة"

2. اختَر حساب الخدمة.
3. انقر على المفاتيح > إضافة مفتاح > إنشاء مفتاح جديد.
4. اختَر JSON، ثمّ انقر على إنشاء.

   يتم إنشاء زوج المفتاح العام/الخاص وتنزيله على جهازك كملف جديد. احفظ ملف JSON الذي تم تنزيله باسم credentials.json في دليل العمل. هذا الملف هو النسخة الوحيدة من هذا المفتاح. للحصول على معلومات عن طريقة التخزين الآمن للمفتاح، راجِع إدارة مفاتيح حساب الخدمة.

5. انقر على إغلاق (Close).

نسخ رقم مشروع Cloud

1. في Google Cloud Console، انتقِل إلى "القائمة" > المشرف وإدارة الهوية وإمكانية الوصول > الإعدادات.

   الانتقال إلى إعدادات "إدارة الهوية وإمكانية الوصول"

2. في حقل رقم المشروع، انسخ القيمة.

إعداد مصادقة حساب الخدمة في مشروع Apps Script

يوضّح هذا القسم كيفية إضافة بيانات اعتماد حساب الخدمة من مشروعك على السحابة الإلكترونية إلى مشروع "برمجة تطبيقات Google".

ضبط مشروعك على Google Cloud في "برمجة تطبيقات Google"

1. انتقِل إلى Apps Script لفتح مشروع أو إنشائه:

   
   فتح "برمجة تطبيقات Google"

2. في مشروع "برمجة تطبيقات Google"، انقر على إعدادات المشروع .

3. ضمن مشروع Google Cloud Platform (GCP)، انقر على تغيير المشروع.

4. في رقم مشروع Google Cloud Platform، ألصِق رقم مشروع Google Cloud.

5. انقر على تحديد المشروع.

حفظ بيانات الاعتماد كسمة نص برمجي

يمكنك تخزين بيانات اعتماد حساب الخدمة بشكل آمن من خلال حفظها كخاصية نص برمجي في إعدادات مشروع Apps Script:

1. انسخ محتوى ملف JSON لحساب الخدمة (credentials.json) الذي أنشأته في القسم السابق.
2. في مشروع "برمجة تطبيقات Google"، انتقِل إلى إعدادات المشروع .
3. من صفحة إعدادات المشروع، انتقِل إلى خصائص النص البرمجي وانقر على إضافة خاصية نص برمجي وأدخِل ما يلي:
   • في حقل الموقع، أدخِل SERVICE_ACCOUNT_KEY.
   • في حقل القيمة، الصِق محتوى ملف مفتاح JSON.
4. انقر على حفظ مواقع النص البرمجي.

إضافة مكتبة OAuth2

للتعامل مع مسار مصادقة OAuth2، يمكنك استخدام مكتبة Apps Script apps-script-oauth2.

لإضافة المكتبة إلى مشروع "برمجة تطبيقات Google"، اتّبِع الخطوات التالية:

1. في محرّر Apps Script، على يمين الصفحة، انقر على إضافة مكتبة بجانب المكتبات.
2. في حقل معرّف النص البرمجي، أدخِل 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF.
3. انقر على بحث.
4. اختَر أحدث إصدار، ثمّ انقر على إضافة.

طلب بيانات من واجهة برمجة تطبيقات باستخدام بيانات اعتماد حساب الخدمة

لاستخدام بيانات اعتماد حساب الخدمة من مشروعك على "برمجة تطبيقات Google"، يمكنك استخدام الدالة التالية 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 بنطاق التفويض الذي تحتاج إليه لاستدعاء واجهة برمجة التطبيقات. يستخدم النص البرمجي بيانات اعتماد حساب الخدمة التي حفظتها كسمة نص برمجي SERVICE_ACCOUNT_KEY في الخطوة السابقة.

يمكنك بعد ذلك استخدام بيانات الاعتماد هذه لطلب بيانات من واجهة برمجة تطبيقات، كما هو موضّح في المثال التالي مع خدمة 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