Class ScriptApp

تزيل هذه الدالة المشغّل المحدّد حتى لا يتم تشغيله بعد الآن.

// Deletes all triggers in the current project.
const triggers = ScriptApp.getProjectTriggers();
for (let i = 0; i < triggers.length; i++) {
  ScriptApp.deleteTrigger(triggers[i]);
}

المعلمات

التفويض

تتطلّب النصوص البرمجية التي تستخدم هذه الطريقة الحصول على إذن باستخدام واحد أو أكثر من النطاقات التالية:

• https://www.googleapis.com/auth/script.scriptapp

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

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

const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);
const status = authInfo.getAuthorizationStatus();
const url = authInfo.getAuthorizationUrl();

المعلمات

الإرجاع

‫AuthorizationInfo: عنصر يمكنه تقديم معلومات عن حالة تفويض المستخدم.

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

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

const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL, [
  'https://www.googleapis.com/auth/documents',
  'https://www.googleapis.com/auth/presentations',
]);
const status = authInfo.getAuthorizationStatus();
const url = authInfo.getAuthorizationUrl();

المعلمات

الإرجاع

AuthorizationInfo: عنصر يقدّم معلومات حول حالة تفويض المستخدم وعنوان URL للتفويض في حال عدم توفّر بعض الموافقات.

يحصل على رمز مميّز لهوية OpenID Connect للمستخدم الفعّال، إذا تم منح النطاق openid. لا يتم تضمين هذا النطاق تلقائيًا، ويجب إضافته كنطاق صريح في ملف البيان لطلب استخدامه. أدرِج النطاقَين https://www.googleapis.com/auth/userinfo.email أو https://www.googleapis.com/auth/userinfo.profile لعرض معلومات إضافية عن المستخدم في الرمز المميّز.

رمز التعريف الذي يتم عرضه هو رمز JSON المميّز للويب (JWT) مرمّز، ويجب فك ترميزه لاستخراج المعلومات منه. توضّح الأمثلة التالية كيفية فك ترميز الرمز المميز واستخراج معرّف ملف المستخدم الفعلي على Google.

const idToken = ScriptApp.getIdentityToken();
const body = idToken.split('.')[1];
const decoded = Utilities
                    .newBlob(
                        Utilities.base64Decode(body),
                        )
                    .getDataAsString();
const payload = JSON.parse(decoded);

Logger.log(`Profile ID: ${payload.sub}`);

الإرجاع

‫String: الرمز المميّز للهوية إذا كان متاحًا، وإلا null.

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

الإرجاع

InstallationSource: مصدر التثبيت

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

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

الإرجاع

String: تمثيل سلسلة لرمز OAuth 2.0 المميز.

تعرض هذه الدالة جميع المشغِّلات القابلة للتثبيت المرتبطة بالمشروع الحالي والمستخدم الحالي.

Logger.log(
    `Current project has ${ScriptApp.getProjectTriggers().length} triggers.`,
);

الإرجاع

‫Trigger[]: مصفوفة من مشغّلات المستخدم الحالي المرتبطة بهذا المشروع.

التفويض

تتطلّب النصوص البرمجية التي تستخدم هذه الطريقة الحصول على إذن باستخدام واحد أو أكثر من النطاقات التالية:

• https://www.googleapis.com/auth/script.scriptapp

تعرض هذه الطريقة المعرّف الفريد لمشروع البرنامج النصي. هذه هي الطريقة المفضّلة للحصول على المعرّف الفريد لمشروع النص البرمجي بدلاً من getProjectKey(). يمكن استخدام هذا المعرّف في جميع المواضع التي تم فيها تقديم مفتاح المشروع سابقًا.

الإرجاع

استبدِل String برقم تعريف مشروع النص البرمجي.

تعرض هذه الدالة عنصرًا يُستخدَم للتحكّم في نشر النص البرمجي كتطبيق ويب.

// Get the URL of the published web app.
const url = ScriptApp.getService().getUrl();

الإرجاع

‫Service: عنصر يُستخدَم لمراقبة عملية نشر النص البرمجي كتطبيق ويب والتحكّم فيها.

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

const doc = DocumentApp.getActiveDocument();
const triggers = ScriptApp.getUserTriggers(doc);
// Log the handler function for the first trigger in the array.
Logger.log(triggers[0].getHandlerFunction());

المعلمات

الإرجاع

Trigger[]: مصفوفة من المشغّلات التي يملكها هذا المستخدم في المستند المحدّد

التفويض

تتطلّب النصوص البرمجية التي تستخدم هذه الطريقة الحصول على إذن باستخدام واحد أو أكثر من النطاقات التالية:

• https://www.googleapis.com/auth/script.scriptapp

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

const form = FormApp.getActiveForm();
const triggers = ScriptApp.getUserTriggers(form);
// Log the trigger source for the first trigger in the array.
Logger.log(triggers[0].getTriggerSource());

المعلمات

الإرجاع

Trigger[]: مصفوفة من المشغّلات التي يملكها هذا المستخدم في النموذج المحدّد

التفويض

تتطلّب النصوص البرمجية التي تستخدم هذه الطريقة الحصول على إذن باستخدام واحد أو أكثر من النطاقات التالية:

• https://www.googleapis.com/auth/script.scriptapp

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

const ss = SpreadsheetApp.getActiveSpreadsheet();
const triggers = ScriptApp.getUserTriggers(ss);
// Log the event type for the first trigger in the array.
Logger.log(triggers[0].getEventType());

المعلمات

الإرجاع

Trigger[]: مصفوفة من المشغّلات التي يملكها هذا المستخدم في جدول البيانات المحدّد.

التفويض

تتطلّب النصوص البرمجية التي تستخدم هذه الطريقة الحصول على إذن باستخدام واحد أو أكثر من النطاقات التالية:

• https://www.googleapis.com/auth/script.scriptapp

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

ScriptApp.invalidateAuth();

الرميات

Error: عند تعذّر إبطال الشهادة

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

// Generate a callback URL, given the name of a callback function. The script
// does not need to be published as a web app; the /usercallback URL suffix
// replaces /edit in any script's URL.
function getCallbackURL(callbackFunction) {
  // IMPORTANT: Replace string below with the URL from your script, minus the
  // /edit at the end.
  const scriptUrl =
      'https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz';
  const urlSuffix = '/usercallback?state=';
  const stateToken = ScriptApp.newStateToken()
                         .withMethod(callbackFunction)
                         .withTimeout(120)
                         .createToken();
  return scriptUrl + urlSuffix + stateToken;
}

في معظم عمليات OAuth2، يتم تمرير الرمز المميز state إلى نقطة نهاية التفويض مباشرةً (وليس كجزء من عنوان URL لصفحة إعادة التوجيه)، ثم تمرّره نقطة نهاية التفويض كجزء من عنوان URL لصفحة إعادة التوجيه.

على سبيل المثال:

• يعيد النص البرمجي توجيه المستخدم إلى عنوان URL الخاص بتفويض OAuth2: https://accounts.google.com/o/oauth2/auth?state=token_generated_with_this_method&callback_uri=https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz/usercallback&other_oauth2_parameters
• ينقر المستخدم على "تفويض"، وتعيد صفحة تفويض OAuth2 توجيه المستخدم إلى https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz/usercallback?state=token_generated_with_this_method&other_params_that_include_tokens_or_grants
• تؤدي عملية إعادة التوجيه المذكورة أعلاه (الرجوع إلى http://script.google.com/...) إلى أن يرسل المتصفّح طلبًا إلى /usercallback، ما يؤدي إلى استدعاء الطريقة المحدّدة بواسطة StateTokenBuilder.withMethod(method).

الإرجاع

StateTokenBuilder: عنصر يُستخدَم لمواصلة عملية إنشاء رمز الحالة.

تبدأ عملية إنشاء مشغّل قابل للتثبيت، وعندما يتم تشغيله، يتم استدعاء دالة معيّنة.

// Creates an edit trigger for a spreadsheet identified by ID.
ScriptApp.newTrigger('myFunction')
    .forSpreadsheet('1234567890abcdefghijklmnopqrstuvwxyz_a1b2c3')
    .onEdit()
    .create();

قبل إنشاء مشغّل، تأكَّد من أنّ الدالة المرتبطة به تتضمّن جميع أذونات OAuth اللازمة.

المعلمات

الإرجاع

‫TriggerBuilder: عنصر يُستخدَم لمواصلة عملية إنشاء المشغّل.

التفويض

تتطلّب النصوص البرمجية التي تستخدم هذه الطريقة الحصول على إذن باستخدام واحد أو أكثر من النطاقات التالية:

• https://www.googleapis.com/auth/script.scriptapp

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

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

ScriptApp.requireAllScopes(ScriptApp.AuthMode.FULL);

المعلمات

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

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

ScriptApp.requireScopes(ScriptApp.AuthMode.FULL, [
  'https://www.googleapis.com/auth/documents',
  'https://www.googleapis.com/auth/presentations',
]);

المعلمات