نطاقات الأذونات

يجب أن يمنح المستخدمون الإذن لمشاريع النصوص البرمجية التي تصل إلى بياناتهم أو تتخذ إجراءات نيابةً عنهم. عندما ينفّذ مستخدم نصًا برمجيًا يتطلّب الحصول على إذن للمرة الأولى، تعرض واجهة المستخدم رسالة تطلب منه بدء عملية منح الإذن.

خلال هذا المسار، تخبر واجهة المستخدم المستخدمين بالأذونات التي يطلبها النص البرمجي. على سبيل المثال، قد يطلب نص برمجي الإذن بقراءة الرسائل الإلكترونية أو إنشاء أحداث في التقويم. يحدّد مشروع النص البرمجي هذه الأذونات الفردية على أنّها نطاقات OAuth.

بالنسبة إلى معظم النصوص البرمجية، ترصد خدمة برمجة تطبيقات تلقائيًا النطاقات المطلوبة. يمكنك في أي وقت الاطّلاع على النطاقات التي يستخدمها النص البرمجي. يمكنك أيضًا ضبط النطاقات بشكل صريح في البيان باستخدام سلاسل عناوين URL. يجب أن تستخدم التطبيقات المنشورة، مثل الإضافات، أضيق النطاقات الممكنة.

أثناء عملية التفويض، تعرض خدمة Apps Script أوصافًا مقروءة للنطاقات المطلوبة. على سبيل المثال، إذا كان البرنامج النصي يحتاج إلى إذن بالقراءة فقط في ما يخص جداول البيانات، قد يتضمّن ملف البيان النطاق https://www.googleapis.com/auth/spreadsheets.readonly. يطلب إذن الوصول من المستخدم "عرض جداول بيانات Google".

تتضمّن بعض النطاقات نطاقات أخرى. على سبيل المثال، يتيح الوصول المصرّح به إلى https://www.googleapis.com/auth/spreadsheets إمكانية قراءة جداول البيانات وتعديلها.

في بعض مساحات العرض، مثل بيئة التطوير المتكاملة في برمجة تطبيقات، تظهر للمستخدمين شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth الدقيقة. تتيح هذه الشاشة للمستخدمين اختيار أذونات معيّنة لمنحها بدلاً من منح جميع الأذونات في آنٍ واحد. صمِّم النص البرمجي للتعامل مع أذونات OAuth الدقيقة.

عرض النطاقات

للاطّلاع على النطاقات التي يتطلّبها مشروع النص البرمجي، اتّبِع الخطوات التالية:

1. افتح مشروع النص البرمجي.
2. على يمين الصفحة، انقر على نظرة عامة info_outline.
3. اطّلِع على النطاقات ضمن نطاقات OAuth للمشروع.

ضبط النطاقات الضمنية

تحدّد برمجة تطبيقات تلقائيًا النطاقات المطلوبة من خلال فحص الرمز بحثًا عن استدعاءات الدوال. مع أنّ هذا الإجراء كافٍ لمعظم النصوص البرمجية، عليك التحكّم بشكل مباشر أكثر في الإضافات المنشورة وتطبيقات الويب وتطبيقات Chat وعمليات استدعاء Chat API.

في بعض الأحيان، تمنح برمجة تطبيقات تلقائيًا نطاقات أذونات واسعة. قد يعني ذلك أنّ البرنامج النصي يطلب من المستخدمين منح إذن وصول أكبر من اللازم. بالنسبة إلى البرامج النصية المنشورة، استبدِل النطاقات الواسعة بمجموعة محدودة تغطي احتياجات البرنامج النصي.

يمكنك ضبط النطاقات التي يستخدمها مشروع النص البرمجي بشكل صريح من خلال تعديل ملف بيان المشروع. حقل oauthScopes في ملف البيان هو عبارة عن مصفوفة من النطاقات التي يستخدمها المشروع. لتحديد نطاقات مشروعك، اتّبِع الخطوات التالية:

1. افتح مشروع النص البرمجي.
2. على يمين الصفحة، انقر على إعدادات المشروع settings.
3. ضَع علامة في مربّع الاختيار عرض ملف البيان "appsscript.json" في المحرر.
4. على يمين الشاشة، انقر على أداة التعديل code.
5. على يمين الشاشة، انقر على ملف appsscript.json.
6. ابحث عن الحقل ذي المستوى الأعلى الذي يحمل التصنيف oauthScopes. إذا لم يكن متوفّرًا، يمكنك إضافته.
7. استبدِل محتوى مصفوفة oauthScopes بالنطاقات التي تريد أن يستخدمها المشروع. على سبيل المثال:

         {
           ...
           "oauthScopes": [
             "https://www.googleapis.com/auth/spreadsheets.readonly",
             "https://www.googleapis.com/auth/userinfo.email"
           ],
          ...
         }

8. في أعلى الشاشة، انقر على حفظ save.

التعامل مع أذونات OAuth الدقيقة

تم إطلاق شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth الدقيقة لأول مرة في بيئة التطوير المتكاملة (IDE) الخاصة بـ "برمجة تطبيقات Google" للمستخدمين الذين ينفّذون نصًا برمجيًا مباشرةً. يتم طرح شاشة طلب الموافقة تدريجيًا على مساحات عرض أخرى، مثل وحدات الماكرو والمشغّلات والإضافات، بمرور الوقت. لمزيد من المعلومات، يُرجى الاطّلاع على الموافقة التفصيلية على بروتوكول OAuth في عمليات تنفيذ بيئة التطوير المتكاملة (IDE) في "برمجة تطبيقات Google".

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

توضّح الأقسام التالية كيفية التعامل مع أذونات OAuth الدقيقة.

طلب الإذن تلقائيًا للنطاقات الضرورية

إذا كان مسار التنفيذ يتطلّب نطاقات معيّنة، يمكنك أن تطلب من المستخدمين منح هذه الأذونات. يمكن للنص البرمجي التحقّق من الأذونات وطلبها تلقائيًا إذا لم تكن متوفّرة.

تتيح الطرق التالية من فئة ScriptApp التحقّق من الأذونات وعرض طلب التفويض:

• requireScopes(authMode, oAuthScopes): استخدِم هذه الطريقة لسير العمل الذي يعتمد على نطاقات محدّدة.
• ‫requireAllScopes(authMode): استخدِم هذه الطريقة إذا كان مسار التنفيذ يعتمد على جميع نطاقات المشروع.

مثال

يوضّح المثال التالي كيفية استدعاء requireScopes() وrequireAllScopes(). يستخدم النص البرمجي نطاقات Gmail و"جداول بيانات Google" و"تقويم Google". لا تتطلّب الدالة sendEmail() سوى نطاقات Gmail و"جداول بيانات Google"، بينما تتطلّب الدالة createEventSendEmail() جميع النطاقات التي يستخدمها النص البرمجي.

// This function requires the Gmail and Sheets scopes.
function sendEmail() {
  // Validates that the user has granted permission for the Gmail and Sheets scopes.
  // If not, the execution ends and prompts the user for authorization.
  ScriptApp.requireScopes(ScriptApp.AuthMode.FULL, [
    'https://mail.google.com/',
    'https://www.googleapis.com/auth/spreadsheets'
  ]);

  // Sends an email.
  GmailApp.sendEmail("dana@example.com", "Subject", "Body");
  Logger.log("Email sent successfully!");

  // Opens a spreadsheet and sheet to track the sent email.
  const ss = SpreadsheetApp.openById("abc1234567");
  const sheet = ss.getSheetByName("Email Tracker")

  // Gets the last row of the sheet.
  const lastRow = sheet.getLastRow();

  // Adds "Sent" to column E of the last row of the spreadsheet.
  sheet.getRange(lastRow, 5).setValue("Sent");
  Logger.log("Sheet updated successfully!");
}

// This function requires all scopes used by the script (Gmail,
// Calendar, and Sheets).
function createEventSendEmail() {
  // Validates that the user has granted permission for all scopes used by the
  // script. If not, the execution ends and prompts the user for authorization.
  ScriptApp.requireAllScopes(ScriptApp.AuthMode.FULL);

  // Creates an event.
  CalendarApp.getDefaultCalendar().createEvent(
    "Meeting",
    new Date("November 28, 2024 10:00:00"),
    new Date("November 28, 2024 11:00:00")
  );
  Logger.log("Calendar event created successfully!");

  // Sends an email.
  GmailApp.sendEmail("dana@example.com", "Subject 2", "Body 2");
  Logger.log("Email sent successfully!");

  // Opens a spreadsheet and sheet to track the created meeting and sent email.
  const ss = SpreadsheetApp.openById("abc1234567");
  const sheet = ss.getSheetByName("Email and Meeting Tracker")
  // Gets the last row
  const lastRow = sheet.getLastRow();

  // Adds "Sent" to column E of the last row
  sheet.getRange(lastRow, 5).setValue("Sent");
  // Adds "Meeting created" to column F of the last row
  sheet.getRange(lastRow, 6).setValue("Meeting created");
  Logger.log("Sheet updated successfully!");
}

إنشاء تجربة مخصّصة للنطاقات غير المتوفّرة

يمكنك استرداد حالة الأذونات للمستخدمين وتصميم تجارب مخصّصة. على سبيل المثال، يمكنك إيقاف الميزات التي تتطلّب أذونات غير متوفّرة أو عرض مربّع حوار يوضّح المتطلبات. تستردّ الطرق التالية عنصرًا يتضمّن معلومات أذونات المستخدم، بما في ذلك النطاقات التي منح المستخدم الإذن بالوصول إليها وعنوان URL لطلب أي نطاقات غير متوفّرة:

• ‫getAuthorizationInfo(authMode, oAuthScopes): للتحقّق من حالة الإذن لنطاقات معيّنة.
• ‫getAuthorizationInfo(authMode): تعرض هذه السمة حالة الإذن لجميع نطاقات المشروع.

للحصول على تفاصيل الإذن من عنصر معلومات التفويض، مثل قائمة النطاقات المفوَّضة وعنوان URL لطلب الأذونات الناقصة، استخدِم الطرق من فئة AuthorizationInfo.

مثال

يوضّح المثال التالي كيفية استخدام getAuthorizationInfo() لتخطّي الميزات التي لم يمنح المستخدمون النطاقات المطلوبة لها. يتيح ذلك استمرار بقية عملية التنفيذ بدون طلب إذن بالنطاقات غير المتوفّرة.

// This function uses the Gmail scope and skips the email
// capabilities if the scope for Gmail hasn't been granted.
function myFunction() {
  const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL, ['https://mail.google.com/']);
  if (authInfo.getAuthorizationStatus() === ScriptApp.AuthorizationStatus.NOT_REQUIRED) {
    GmailApp.sendEmail("dana@example.com", "Subject", "Body");
    Logger.log("Email sent successfully!");
  } else {
    const scopesGranted = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL).getAuthorizedScopes();
    console.warn(`Authorized scopes: ${scopesGranted} not enough to send mail, skipping.`);
  }
  // Continue the rest of the execution flow...
}

التأكّد من أنّ عمليات تنفيذ المشغّلات لديها أذونات

يتم تشغيل الدوال المرتبطة بالمشغّلات تلقائيًا، وقد لا يكون المستخدمون متوفّرين لتقديم الأذونات. ننصحك باستخدام requireScopes(authMode, oAuthScopes) قبل تثبيت مشغّل. يطلب هذا الإجراء من المستخدم منح الأذونات الناقصة، ولا يسمح بتثبيت المشغّل بدونها.

مثال

// This function requires scope Sheets.
function trackFormSubmissions(e){
  // Opens a spreadsheet to track the sent email.
  const ss = SpreadsheetApp.openById("abc1234567");
  const sheet = ss.getSheetByName("Submission Tracker")

  // Gets the last row of the sheet.
  const lastRow = sheet.getLastRow();

  // Adds email address of user that submitted the form
  // to column E of the last row of the spreadsheet.
  sheet.getRange(lastRow, 5).setValue(e.name);
  Logger.log("Sheet updated successfully!");
}

function installTrigger(){
  // Validates that the user has granted permissions for trigger
  // installation and execution. If not, trigger doesn't get
  // installed and prompts the user for authorization.
  ScriptApp.requireScopes(ScriptApp.AuthMode.FULL, [
    'https://www.googleapis.com/auth/script.scriptapp',
    'https://www.googleapis.com/auth/spreadsheets',
    'https://www.googleapis.com/auth/forms.currentonly'
  ]);
  ScriptApp.newTrigger('trackFormSubmission')
    .forForm(FormApp.getActiveForm())
    .onFormSubmit()
    .create();
}

التحقّق من OAuth

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

• التحقّق من عميل OAuth في برمجة تطبيقات
• التطبيقات التي لم يتم التحقّق منها
• الأسئلة الشائعة حول التحقّق من OAuth
• سياسة بيانات المستخدمين في خدمات Google API

النطاقات المحظورة

بالإضافة إلى النطاقات الحسّاسة، يتم تصنيف بعض النطاقات على أنّها مقيدة وتخضع لقواعد إضافية تساعد في حماية بيانات المستخدمين. إذا نشرت تطبيقًا يستخدم نطاقات محظورة، يجب أن يلتزم بجميع المواصفات.

يُرجى مراجعة القائمة الكاملة للنطاقات المحظورة قبل النشر. يجب أن تلتزم التطبيقات المتوافقة بالمتطلبات الإضافية لنطاقات واجهات برمجة التطبيقات المحدّدة.

تجنَّب استخدام النطاقات المحظورة قدر الإمكان لتبسيط عملية المراجعة. يمكنك استخدام النطاقات المحظورة بحرية للتطبيقات غير العلنية.