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

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

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

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

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

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

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

عرض النطاقات

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

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

ضبط النطاقات الصريحة

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

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

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

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

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

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

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

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

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

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

توضّح الأقسام التالية الطرق الرئيسية للتعامل مع أذونات OAuth الدقيقة.

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

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

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

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

مثال

يوضّح المثال التالي كيفية استدعاء الطريقتَين requireScopes(authMode, oAuthScopes) وrequireAllScopes(authMode). يستخدم النص البرمجي نطاقات 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("[e-mail]", "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("[e-mail]", "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(authMode, oAuthScopes) لتخطّي ميزات معيّنة ضمن مسار تنفيذ لم يتم منح النطاقات المطلوبة فيه. يسمح ذلك بمواصلة بقية عملية التنفيذ بدون الحاجة إلى طلب إذن بالنطاقات غير المتوفّرة.

// 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("[e-mail]", "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 APIs: سياسة بيانات المستخدمين

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

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

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

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