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 لمربّع حوار التفويض. إذا تم نشر النص البرمجي كإضافة تستخدِم عوامل تشغيل قابلة للتثبيت، يمكن استخدام هذه المعلومات للتحكّم في الوصول إلى أقسام من الرمز البرمجي لا يملك المستخدم إذنًا بالوصول إليها. بدلاً من ذلك، يمكن أن تطلب الإضافة من المستخدم فتح عنوان URL لمربّع حوار التفويض لحلّ المشكلة.

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

المعلمات

الإرجاع

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

الحصول على رمز تعريف 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: مصدر التثبيت

تحصل على رمز الوصول لبروتوكول OAuth 2.0 للمستخدم الفعلي. إذا كانت نطاقات 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

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

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();

المعلمات

الإرجاع

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

التفويض

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

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