تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

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

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

عرض النطاقات

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

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

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

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

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

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

افتح مشروع النص.
على يمين الصفحة، انقر على إعدادات المشروع .
ضَع علامة في مربّع الاختيار عرض ملف البيان "appsscript.json" في المحرِّر.
على يمين الصفحة، انقر على أداة التعديل .
على يمين الصفحة، انقر على ملف appsscript.json.
ابحث عن الحقل ذي المستوى الأعلى الذي يحمل التصنيف oauthScopes. إذا لم يكن متوفّرًا، يمكنك إضافته.
يحدّد حقل oauthScopes صفيفًا من السلاسل. لضبط النطاقات التي يستخدمها مشروعك، استبدِل محتوى هذا الصفيف بالنطاقات التي تريده استخدامها. على سبيل المثال:
```
      {
        ...
        "oauthScopes": [
          "https://www.googleapis.com/auth/spreadsheets.readonly",
          "https://www.googleapis.com/auth/userinfo.email"
        ],
       ...
      }
```
في أعلى الصفحة، انقر على رمز الحفظ .

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

تتيح شاشة طلب الموافقة الدقيقة على 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("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(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("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...
}

إثبات ملكية حساب OAuth

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

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

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

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