المصادقة كمشروع برمجة تطبيقات Google باستخدام حسابات الخدمة

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

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

حالات استخدام حسابات الخدمة في برمجة تطبيقات

تستخدم "برمجة تطبيقات Google" تلقائيًا بيانات اعتماد مستخدم البرنامج النصي لطلب بيانات من واجهات برمجة التطبيقات. إذا كنت تستدعي واجهات Google APIs باستخدام UrlFetchApp، يمكنك الحصول على رمز مميّز للوصول إلى حساب مستخدم النص البرمجي من خلال استدعاء ScriptApp.getOAuthToken.

ومع ذلك، يوفّر استخدام حسابات الخدمة العديد من المزايا مقارنةً بـ ScriptApp.getOAuthToken في بعض السيناريوهات. ننصحك باستخدام مصادقة حساب الخدمة للأسباب التالية:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

نسخ رقم مشروع على السحابة الإلكترونية

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

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

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

إعداد مصادقة حساب الخدمة في مشروعك على "برمجة تطبيقات Google"

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

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

1. انتقِل إلى برمجة تطبيقات لفتح مشروع أو إنشائه:

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

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

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

4. في رقم مشروع على السحابة الإلكترونية، الصِق رقم مشروع على السحابة الإلكترونية.

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

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

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

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

إضافة مكتبة OAuth2

للتعامل مع عملية المصادقة باستخدام OAuth2، استخدِم مكتبة برمجة تطبيقات apps-script-oauth2.

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

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

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

لاستخدام بيانات اعتماد حساب الخدمة من مشروعك على برمجة تطبيقات، يمكنك استخدام الدالة التالية 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