این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

Class 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`	فرآیند ایجاد یک تریگر قابل نصب را آغاز می کند که هنگام روشن شدن، یک تابع معین را فراخوانی می کند.

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

روش	نوع برگشت	توضیح مختصر
`getProjectKey()`	`String`	کلید پروژه اسکریپت فعلی را دریافت می کند.
`getScriptTriggers()`	`Trigger[]`	همه محرک های قابل نصب مرتبط با پروژه فعلی و کاربر فعلی را دریافت می کند.

مستندات دقیق

`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

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

`getProjectKey()`

منسوخ. به جای آن از getScriptId() استفاده کنید.

کلید پروژه اسکریپت فعلی را دریافت می کند. کلید پروژه یک شناسه منحصربه‌فرد برای اسکریپت‌ها است و برای نوشتن URL برگشتی که در ارتباط با newStateToken() استفاده می‌شود.

هنگامی که در یک کتابخانه فراخوانی می شود، این کلید پروژه خارجی ترین اسکریپت در حال اجرا را برمی گرداند.

برگشت

String - کلید پروژه اسکریپت فعلی.

`getScriptTriggers()`

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

همه محرک های قابل نصب مرتبط با پروژه فعلی و کاربر فعلی را دریافت می کند.

Logger.log('Current script has ' + ScriptApp.getScriptTriggers().length + ' triggers.');

برگشت

Trigger[] - آرایه ای از محرک های کاربر فعلی مرتبط با این پروژه.

مجوز

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

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