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: مصدر التثبيت

تحصل على رمز الوصول لبروتوكول 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

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

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

ScriptApp.requireAllScopes(ScriptApp.AuthMode.FULL);

المعلمات

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

لا تعمل هذه الطريقة إلا عندما يشغّل المستخدمون النص البرمجي من سطح عرض يتيح منح الموافقة بدقة، على سبيل المثال، من داخل بيئة تطوير البرامج (IDE) في Apps Script. عند تشغيل النص البرمجي مع عدم توفّر الموافقة من سطح عرض غير متوافق، مثل إضافة Google Workspace، يعرض النص البرمجي طلب تفويض في بداية التنفيذ لطلب جميع النطاقات.

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

المعلمات