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]);
}

المعلّمات

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

التفويض

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

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

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

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

المعلّمات

الاسم	النوع	الوصف
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 API أخرى تتطلب عادةً تدفق 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());

المعلّمات

الاسم	النوع	الوصف
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());

المعلّمات

الاسم	النوع	الوصف
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());

المعلّمات

الاسم	النوع	الوصف
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();

المعلّمات

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

تذكرة ذهاب وعودة

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

التفويض

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

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