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