Class ScriptApp

ScriptApp

دسترسی و دستکاری انتشار اسکریپت و محرک ها. این کلاس به کاربران این امکان را می دهد که محرک های اسکریپت ایجاد کرده و انتشار اسکریپت را به عنوان یک سرویس کنترل کنند.

خواص

اموال تایپ کنید توضیحات
AuthMode AuthMode شمارشی که مشخص می‌کند کدام دسته از سرویس‌های مجاز Apps Script می‌تواند از طریق یک تابع راه‌اندازی شده اجرا شود.
AuthorizationStatus AuthorizationStatus شمارشی که وضعیت مجوز یک اسکریپت را نشان می دهد.
EventType EventType شمارشی که نوع رویداد راه اندازی شده را نشان می دهد.
InstallationSource InstallationSource شمارشی که نشان می دهد چگونه اسکریپت به عنوان یک افزونه برای کاربر نصب شده است.
TriggerSource TriggerSource شمارشی که نشان دهنده منبع رویدادی است که باعث شلیک ماشه می شود.
WeekDay Weekday شمارشی که بیانگر روزهای هفته است.

روش ها

روش نوع برگشت شرح مختصر
deleteTrigger(trigger) void ماشه داده شده را حذف می کند تا دیگر اجرا نشود.
getAuthorizationInfo(authMode) AuthorizationInfo برای تعیین اینکه آیا کاربر برای استفاده از یک یا چند سرویس باید به این اسکریپت مجوز دهد یا خیر و برای ارائه URL برای گفتگوی مجوز، یک شی را دریافت می کند.
getIdentityToken() String در صورتی که محدوده openid داده شده باشد، یک رمز هویت OpenID Connect برای کاربر موثر دریافت می کند.
getInstallationSource() InstallationSource یک مقدار enum را برمی‌گرداند که نشان می‌دهد چگونه اسکریپت به‌عنوان یک افزونه برای کاربر فعلی نصب شده است (برای مثال، اینکه آیا کاربر آن را شخصاً از طریق فروشگاه وب 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 سازنده ای برای یک نشانه وضعیت ایجاد می کند که می تواند در یک API برگشتی (مانند جریان 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 داده شده باشد، یک رمز هویت OpenID Connect برای کاربر موثر دریافت می کند. این محدوده به طور پیش‌فرض گنجانده نشده است و برای درخواست آن باید آن را به عنوان یک محدوده واضح در فایل مانیفست اضافه کنید. دامنه‌های https://www.googleapis.com/auth/userinfo.email یا https://www.googleapis.com/auth/userinfo.profile را برای بازگرداندن اطلاعات اضافی کاربر در توکن وارد کنید.

رمز شناسه برگشتی یک رمز وب JSON (JWT) است و باید برای استخراج اطلاعات از آن رمزگشایی شود. مثال های زیر نحوه رمزگشایی رمز و استخراج شناسه نمایه گوگل کاربر موثر را نشان می دهد.

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

یک مقدار enum را برمی‌گرداند که نشان می‌دهد چگونه اسکریپت به‌عنوان یک افزونه برای کاربر فعلی نصب شده است (برای مثال، اینکه آیا کاربر آن را شخصاً از طریق فروشگاه وب Chrome نصب کرده است یا اینکه یک سرپرست دامنه آن را برای همه کاربران نصب کرده است).

بازگشت

InstallationSource - منبع نصب.


getOAuthToken()

کد دسترسی OAuth 2.0 را برای کاربر مؤثر دریافت می کند. اگر دامنه‌های OAuth اسکریپت برای مجوز دادن به Google API دیگری که معمولاً به جریان OAuth خود نیاز دارد (مانند Google Picker )، کافی باشد، اسکریپت‌ها می‌توانند با ارسال این نشانه، دومین درخواست مجوز را دور بزنند. رمز پس از مدتی منقضی می شود (حداقل چند دقیقه). اسکریپت ها باید با خرابی های مجوز رسیدگی کنند و این روش را فراخوانی کنند تا در صورت نیاز یک توکن تازه به دست آورند.

رمزی که با این روش برگردانده می شود فقط شامل محدوده هایی است که اسکریپت در حال حاضر به آنها نیاز دارد. دامنه‌هایی که قبلاً مجاز بوده‌اند اما دیگر توسط اسکریپت استفاده نمی‌شوند در توکن بازگشتی گنجانده نشده‌اند. اگر دامنه های 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 Docs که ممکن است حاوی محرک‌های قابل نصب باشد.

بازگشت

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 Forms که ممکن است حاوی راه‌اندازهای قابل نصب باشد.

بازگشت

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 Sheets که ممکن است حاوی محرک‌های قابل نصب باشد.

بازگشت

Trigger[] - آرایه ای از محرک های متعلق به این کاربر در صفحه گسترده داده شده.

مجوز

اسکریپت هایی که از این روش استفاده می کنند نیاز به مجوز با یک یا چند مورد از حوزه های زیر دارند:

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

invalidateAuth()

مجوزی را که کاربر موثر برای اجرای اسکریپت فعلی دارد، بی اعتبار می کند. برای باطل کردن هر گونه مجوز برای اسکریپت فعلی استفاده می شود. این به ویژه برای توابعی که به عنوان مجوز تک شات برچسب گذاری شده اند مفید است. از آنجایی که توابع مجوز تک شات را فقط می توان اولین اجرا پس از دریافت مجوز از اسکریپت نامید، اگر می خواهید عملی را پس از آن انجام دهید، باید هر مجوزی را که اسکریپت داشته است لغو کنید تا کاربر بتواند دوباره گفتگوی مجوز را ببیند.

ScriptApp.invalidateAuth();

پرتاب می کند

Error - زمانی که ابطال ناموفق است


newStateToken()

سازنده ای برای یک نشانه وضعیت ایجاد می کند که می تواند در یک API برگشتی (مانند جریان 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 بازگشت به تماس ارسال می‌کند.

به عنوان مثال:

  • این اسکریپت کاربر را به نشانی اینترنتی مجوز 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

روش های منسوخ شده