الوصول إلى نشر النص البرمجي والمشغلات والتعامل معه تتيح هذه الفئة للمستخدمين إنشاء مشغّلات النص البرمجي والتحكم في نشر النص البرمجي كخدمة.
أماكن إقامة
الموقع | Type | الوصف |
---|---|---|
AuthMode | AuthMode | يشير ذلك المصطلح إلى تعداد يحدِّد فئات الخدمات المعتمَدة التي يمكن لبرمجة التطبيقات تنفيذها من خلال دالة مُفعَّلة. |
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]); }
المَعلمات
الاسم | Type | الوصف |
---|---|---|
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();
المَعلمات
الاسم | Type | الوصف |
---|---|---|
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 أخرى والتي تتطلب عادةً تدفق 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());
المَعلمات
الاسم | Type | الوصف |
---|---|---|
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());
المَعلمات
الاسم | Type | الوصف |
---|---|---|
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());
المَعلمات
الاسم | Type | الوصف |
---|---|---|
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();
المَعلمات
الاسم | Type | الوصف |
---|---|---|
functionName | String | الدالة المطلوب استدعاءها عند تنشيط المشغِّل. يمكنك استخدام دوال من
المكتبات المضمّنة، مثل Library.libFunction1 . |
استرجاع الكرة
TriggerBuilder
: كائن يُستخدَم لمواصلة عملية إنشاء المشغِّل.
التفويض
تتطلب النصوص البرمجية التي تستخدم هذه الطريقة الحصول على تفويض باستخدام واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/script.scriptapp