Class ScriptApp

يزيل المشغِّل المحدد بحيث لا يتم تشغيله مرة أخرى.

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

المَعلمات

الاسم	Type	الوصف
trigger	Trigger	العامل المشغِّل المطلوب حذفه

التفويض

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

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

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

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

المَعلمات

الاسم	Type	الوصف
authMode	AuthMode	وضع التفويض الذي يتم طلب معلومات التفويض فيه، في جميع الحالات تقريبًا، يجب أن تكون قيمة authMode هي ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL)، لأنّ أي وضع تفويض آخر لا يتطلّب من المستخدم منح المستخدم الإذن

استرجاع الكرة

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

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

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

var idToken = ScriptApp.getIdentityToken();
var body = idToken.split('.')[1];
var decoded = Utilities.newBlob(Utilities.base64Decode(body)).getDataAsString();
var payload = JSON.parse(decoded);
var profileId = payload.sub;
Logger.log('Profile ID: ' + profileId);

راجِع وثائق OpenID Connect للاطّلاع على القائمة الكاملة للحقول (المطالبات) التي تم عرضها.

استرجاع الكرة

String: الرمز المميّز للهوية في حال توفّره، وبخلاف ذلك: null

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

استرجاع الكرة

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

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

لا يتضمن الرمز المميز الذي تعرضه هذه الطريقة سوى النطاقات التي يحتاجها النص البرمجي حاليًا. لا يتم تضمين النطاقات التي تم تفويضها من قبل ولكن لم يعد يتم استخدامها بواسطة النص البرمجي في الرمز المميّز المعروض. إذا كانت هناك حاجة إلى نطاقات 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.
var url = ScriptApp.getService().getUrl();

استرجاع الكرة

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

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

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

المَعلمات

الاسم	Type	الوصف
document	Document	ملف "مستندات Google" قد يحتوي على مشغِّلات قابلة للتثبيت

استرجاع الكرة

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

التفويض

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

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

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

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

المَعلمات

الاسم	Type	الوصف
form	Form	ملف "نماذج Google" قد يحتوي على مشغِّلات قابلة للتثبيت

استرجاع الكرة

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

التفويض

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

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

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

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

المَعلمات

الاسم	Type	الوصف
spreadsheet	Spreadsheet	ملف في "جداول بيانات Google" قد يحتوي على مشغّلات قابلة للتثبيت

استرجاع الكرة

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.
  var scriptUrl = 'https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz';
  var urlSuffix = '/usercallback?state=';
  var 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();

المَعلمات

الاسم	Type	الوصف
functionName	String	الدالة المطلوب استدعاءها عند تنشيط المشغِّل. يمكنك استخدام دوال من المكتبات المضمّنة، مثل Library.libFunction1.

استرجاع الكرة

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

التفويض

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

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