يمكنك الوصول إلى نشر النصوص البرمجية وتشغيلها. تتيح هذه الفئة للمستخدمين إنشاء أوامر تشغيل النص البرمجي والتحكُّم في نشر النص البرمجي كخدمة.
أماكن إقامة
الخاصية | النوع | الوصف |
---|---|---|
AuthMode | AuthMode | تعداد يحدد فئات خدمات "برمجة تطبيقات Google" المصرَّح بها التي يمكنها التنفيذ من خلال دالة تم تشغيلها. |
AuthorizationStatus | AuthorizationStatus | قائمة تعداد تشير إلى حالة تفويض نص برمجي |
EventType | EventType | قائمة تعداد تشير إلى نوع الحدث الذي تم تشغيله |
InstallationSource | InstallationSource | قائمة تعداد تشير إلى كيفية تثبيت النص البرمجي للمستخدم كإضافة |
TriggerSource | TriggerSource | قائمة تعداد تشير إلى مصدر الحدث الذي يؤدي إلى إطلاق المشغّل. |
WeekDay | Weekday | قائمة تعداد تمثّل أيام الأسبوع |
الطُرق
الطريقة | نوع الإرجاع | وصف قصير |
---|---|---|
deleteTrigger(trigger) | void | إزالة المشغّل المحدّد بحيث لا يتم تشغيله بعد ذلك |
getAuthorizationInfo(authMode) | AuthorizationInfo | يحصل على كائن يُستخدم لتحديد ما إذا كان المستخدم بحاجة إلى تفويض هذا النص البرمجي لاستخدام خدمة واحدة أو أكثر، ولتقديم عنوان URL لمربع حوار التفويض. |
getIdentityToken() | String | تحصل على رمز مميّز لـ OpenID Connect للمستخدم
الفعّال، إذا تم منح النطاق openid . |
getInstallationSource() | InstallationSource | تعرض قيمة تعداد تشير إلى كيفية تثبيت النص البرمجي كإضافة للمستخدم الحالي (على سبيل المثال، ما إذا كان المستخدم قد ثبّتها شخصيًا من خلال سوق Chrome الإلكتروني، أو ما إذا كان مشرف النطاق قد ثبّتها لكل المستخدمين). |
getOAuthToken() | String | تحصل على رمز دخول OAuth 2.0 للمستخدم الفعّال. |
getProjectTriggers() | Trigger[] | يحصل على جميع المشغِّلات القابلة للتثبيت المرتبطة بالمشروع الحالي والمستخدم الحالي. |
getScriptId() | String | للحصول على المعرّف الفريد لمشروع النص البرمجي. |
getService() | Service | تحصل على كائن يُستخدَم للتحكم في نشر النص البرمجي كتطبيق ويب. |
getUserTriggers(document) | Trigger[] | يحصل على جميع المشغِّلات القابلة للتثبيت التي يملكها هذا المستخدم في المستند المعيّن، لهذا النص البرمجي أو الإضافة فقط. |
getUserTriggers(form) | Trigger[] | يحصل على جميع المشغِّلات القابلة للتثبيت التي يملكها هذا المستخدم في النموذج المحدّد، لهذا النص البرمجي أو الإضافة فقط. |
getUserTriggers(spreadsheet) | Trigger[] | يحصل على جميع المشغِّلات القابلة للتثبيت التي يملكها هذا المستخدم في جدول البيانات المحدد، لهذا النص البرمجي أو الإضافة فقط. |
invalidateAuth() | void | إلغاء التفويض الذي على المستخدم الفعّال تنفيذ النص البرمجي الحالي. |
newStateToken() | StateTokenBuilder | تنشئ أداة إنشاء لرمز مميز للحالة يمكن استخدامه في واجهة برمجة تطبيقات معاودة الاتصال (مثل تدفق OAuth). |
newTrigger(functionName) | TriggerBuilder | يبدأ عملية إنشاء مشغِّل قابل للتثبيت يؤدي عند تنشيطه إلى استدعاء دالة معيّنة. |
المستندات التفصيلية
deleteTrigger(trigger)
إزالة المشغّل المحدّد بحيث لا يتم تشغيله بعد ذلك
// 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
getAuthorizationInfo(authMode)
يحصل على كائن يُستخدم لتحديد ما إذا كان المستخدم بحاجة إلى تفويض هذا النص البرمجي لاستخدام خدمة واحدة أو أكثر، ولتقديم عنوان URL لمربع حوار التفويض. إذا تم نشر النص البرمجي كإضافة تستخدم مشغّلات قابلة للتثبيت، يمكن استخدام هذه المعلومات للتحكّم في الوصول إلى أقسام الرمز التي يفتقر المستخدم إليها للتفويض اللازم. بدلاً من ذلك، يمكن أن تطلب الإضافة من المستخدم فتح عنوان URL لمربّع حوار التفويض لحل المشكلة.
var authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL); status = authInfo.getAuthorizationStatus(); url = authInfo.getAuthorizationUrl();
المعلّمات
الاسم | النوع | الوصف |
---|---|---|
authMode | AuthMode | وضع التفويض الذي يتم طلب معلومات التفويض له؛ في
كل الحالات تقريبًا، يجب أن تكون قيمة authMode ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL) ، لأنّه لا يوجد وضع تفويض آخر
يتطلب أن يمنح المستخدمون التفويض |
تذكرة ذهاب وعودة
AuthorizationInfo
: عنصر يمكن أن يقدّم معلومات عن حالة تفويض المستخدم.
getIdentityToken()
تحصل على رمز مميّز لـ 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
getInstallationSource()
تعرض قيمة تعداد تشير إلى كيفية تثبيت النص البرمجي كإضافة للمستخدم الحالي (على سبيل المثال، ما إذا كان المستخدم قد ثبّتها شخصيًا من خلال سوق Chrome الإلكتروني، أو ما إذا كان مشرف النطاق قد ثبّتها لكل المستخدمين).
تذكرة ذهاب وعودة
InstallationSource
— مصدر التثبيت.
getOAuthToken()
تحصل على رمز دخول OAuth 2.0 للمستخدم الفعّال. إذا كانت نطاقات OAuth النص البرمجي كافية لتفويض Google API أخرى تتطلب عادةً تدفق OAuth الخاص بها (مثل منتقي Google)، يمكن للنصوص البرمجية أن تتجاوز مطالبة التفويض الثانية عن طريق تمرير هذا الرمز المميز بدلاً من ذلك. تنتهي صلاحية الرمز المميّز بعد وقت معيّن (بضع دقائق على الأقل)، ويجب أن تعالج النصوص البرمجية حالات فشل التفويض وأن تطلب هذه الطريقة للحصول على رمز مميّز جديد عند الحاجة.
لا يتضمن الرمز المميز الذي تعرضه هذه الطريقة سوى النطاقات التي يحتاجها النص البرمجي حاليًا. لا يتم تضمين النطاقات التي تم تفويضها في السابق ولكن لم يعد يتم استخدامها من خلال النص البرمجي في الرمز المميز المعروض. وإذا كانت هناك حاجة إلى نطاقات OAuth إضافية بخلاف ما يتطلبه النص البرمجي نفسه، يمكن أن يتم تحديدها في ملف بيان النص البرمجي.
تذكرة ذهاب وعودة
String
: تمثيل سلسلة للرمز المميّز لـ OAuth 2.0
getProjectTriggers()
يحصل على جميع المشغِّلات القابلة للتثبيت المرتبطة بالمشروع الحالي والمستخدم الحالي.
Logger.log('Current project has ' + ScriptApp.getProjectTriggers().length + ' triggers.');
تذكرة ذهاب وعودة
Trigger[]
: مصفوفة من العوامل المُشغِّلة الحالية للمستخدمين المرتبطة بهذا المشروع.
التفويض
تتطلب النصوص البرمجية التي تستخدم هذه الطريقة تفويضًا مع واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/script.scriptapp
getScriptId()
للحصول على المعرّف الفريد لمشروع النص البرمجي. هذه هي الطريقة المفضّلة للحصول على المعرّف الفريد لمشروع النص البرمجي بدلاً من
. يمكن استخدام رقم التعريف هذا في كل الأماكن
التي تم فيها تقديم مفتاح المشروع في السابق.getProjectKey()
تذكرة ذهاب وعودة
String
— رقم تعريف المشروع للنص البرمجي.
getService()
تحصل على كائن يُستخدَم للتحكم في نشر النص البرمجي كتطبيق ويب.
// Get the URL of the published web app. var url = ScriptApp.getService().getUrl();
تذكرة ذهاب وعودة
Service
— عنصر يتم استخدامه لمراقبة النص البرمجي والتحكُّم فيه كتطبيق ويب.
getUserTriggers(document)
يحصل على جميع المشغِّلات القابلة للتثبيت التي يملكها هذا المستخدم في المستند المعيّن، لهذا النص البرمجي أو الإضافة فقط. لا يمكن استخدام هذه الطريقة للاطّلاع على العوامل المُشغِّلة للنصوص البرمجية الأخرى.
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
getUserTriggers(form)
يحصل على جميع المشغِّلات القابلة للتثبيت التي يملكها هذا المستخدم في النموذج المحدّد، لهذا النص البرمجي أو الإضافة فقط. لا يمكن استخدام هذه الطريقة للاطّلاع على العوامل المُشغِّلة للنصوص البرمجية الأخرى.
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
getUserTriggers(spreadsheet)
يحصل على جميع المشغِّلات القابلة للتثبيت التي يملكها هذا المستخدم في جدول البيانات المحدد، لهذا النص البرمجي أو الإضافة فقط. لا يمكن استخدام هذه الطريقة للاطّلاع على العوامل المُشغِّلة للنصوص البرمجية الأخرى.
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
invalidateAuth()
إلغاء التفويض الذي على المستخدم الفعّال تنفيذ النص البرمجي الحالي. يتم استخدام هذا الرمز لإلغاء صلاحية أي أذونات للنص البرمجي الحالي. ويُعدّ هذا الأمر مفيدًا على وجه الخصوص للدوال التي تم وضع علامة عليها كتفويض من لقطة واحدة. بما أن دوال التفويض لمرة واحدة لا يمكن استدعاءها إلا عند التشغيل لأول مرة بعد حصول النص البرمجي على التفويض، وإذا كنت تريد تنفيذ إجراء بعد ذلك، يجب إبطال أي تفويض يتوفر في النص البرمجي، بحيث يمكن للمستخدم رؤية مربّع حوار التفويض مرة أخرى.
ScriptApp.invalidateAuth();
طرح
Error
— عند تعذُّر الإلغاء
newStateToken()
تنشئ أداة إنشاء لرمز مميز للحالة يمكن استخدامه في واجهة برمجة تطبيقات معاودة الاتصال (مثل تدفق 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
— عنصر يُستخدم لمواصلة عملية إنشاء الرمز المميز للولاية.
newTrigger(functionName)
يبدأ عملية إنشاء مشغِّل قابل للتثبيت يؤدي عند تنشيطه إلى استدعاء دالة معيّنة.
// 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