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

Class ScriptApp

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

خواص

اموال	تایپ کنید	توضیحات
`Auth Mode`	`Auth Mode`	شمارشی که مشخص می‌کند کدام دسته از سرویس‌های مجاز Apps Script می‌تواند از طریق یک تابع راه‌اندازی شده اجرا شود.
`Authorization Status`	`Authorization Status`	شمارشی که وضعیت مجوز یک اسکریپت را نشان می دهد.
`Event Type`	`Event Type`	شمارشی که نوع رویداد راه اندازی شده را نشان می دهد.
`Installation Source`	`Installation Source`	شمارشی که نشان می دهد چگونه اسکریپت به عنوان یک افزونه برای کاربر نصب شده است.
`Trigger Source`	`Trigger Source`	شمارشی که نشان دهنده منبع رویدادی است که باعث شلیک ماشه می شود.
`Week Day`	`Weekday`	شمارشی که بیانگر روزهای هفته است.

روش ها

روش	نوع برگشت	شرح مختصر
`delete Trigger(trigger)`	`void`	ماشه داده شده را حذف می کند تا دیگر اجرا نشود.
`get Authorization Info(authMode)`	`Authorization Info`	برای تعیین اینکه آیا کاربر برای استفاده از یک یا چند سرویس باید به این اسکریپت مجوز دهد یا خیر و برای ارائه URL برای گفتگوی مجوز، یک شی را دریافت می کند.
`get Identity Token()`	`String`	در صورتی که محدوده `openid` اعطا شده باشد، یک رمز هویت Open ID Connect برای کاربر موثر دریافت می کند.
`get Installation Source()`	`Installation Source`	یک مقدار enum را برمی‌گرداند که نشان می‌دهد چگونه اسکریپت به‌عنوان یک افزونه برای کاربر فعلی نصب شده است (برای مثال، اینکه آیا کاربر آن را شخصاً از طریق فروشگاه وب Chrome نصب کرده است یا اینکه یک سرپرست دامنه آن را برای همه کاربران نصب کرده است).
`get OAuth Token()`	`String`	کد دسترسی OAuth 2.0 را برای کاربر مؤثر دریافت می کند.
`get Project Triggers()`	`Trigger[]`	همه محرک های قابل نصب مرتبط با پروژه فعلی و کاربر فعلی را دریافت می کند.
`get Script Id()`	`String`	شناسه منحصر به فرد پروژه اسکریپت را دریافت می کند.
`get Service()`	`Service`	یک شی را برای کنترل انتشار اسکریپت به عنوان یک برنامه وب استفاده می کند.
`get User Triggers(document)`	`Trigger[]`	تمام محرک های قابل نصب متعلق به این کاربر را در سند داده شده، فقط برای این اسکریپت یا افزونه دریافت می کند.
`get User Triggers(form)`	`Trigger[]`	تمام محرک‌های قابل نصب متعلق به این کاربر را در فرم داده شده، فقط برای این اسکریپت یا افزونه دریافت می‌کند.
`get User Triggers(spreadsheet)`	`Trigger[]`	همه محرک‌های قابل نصب متعلق به این کاربر را در صفحه‌گسترده داده شده، فقط برای این اسکریپت یا افزونه دریافت می‌کند.
`invalidate Auth()`	`void`	مجوزی را که کاربر موثر برای اجرای اسکریپت فعلی دارد، بی اعتبار می کند.
`new State Token()`	`State Token Builder`	سازنده ای برای یک نشانه وضعیت ایجاد می کند که می تواند در یک API برگشتی (مانند جریان OAuth) استفاده شود.
`new Trigger(functionName)`	`Trigger Builder`	فرآیند ایجاد یک تریگر قابل نصب را آغاز می کند که هنگام روشن شدن، یک تابع معین را فراخوانی می کند.

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

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

مستندات دقیق

`delete Trigger(trigger)`

ماشه داده شده را حذف می کند تا دیگر اجرا نشود.

// Deletes all triggers in the current project.
const triggers = ScriptApp.getProjectTriggers();
for (let i = 0; i < triggers.length; i++) {
  ScriptApp.deleteTrigger(triggers[i]);
}

پارامترها

نام	تایپ کنید	توضیحات
`trigger`	`Trigger`	ماشه برای حذف.

مجوز

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

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

`get Authorization Info(authMode)`

برای تعیین اینکه آیا کاربر برای استفاده از یک یا چند سرویس باید به این اسکریپت مجوز دهد یا خیر و برای ارائه URL برای گفتگوی مجوز، یک شی را دریافت می کند. اگر اسکریپت به‌عنوان افزونه‌ای منتشر شود که از محرک‌های قابل نصب استفاده می‌کند، از این اطلاعات می‌توان برای کنترل دسترسی به بخش‌هایی از کد که کاربر مجوز لازم برای آن‌ها را ندارد، استفاده کرد. همچنین، افزونه می‌تواند از کاربر بخواهد که URL را برای گفتگوی مجوز باز کند تا مشکل حل شود.

var authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);
status = authInfo.getAuthorizationStatus();
url = authInfo.getAuthorizationUrl();

پارامترها

نام	تایپ کنید	توضیحات
`auth Mode`	`Auth Mode`	حالت مجوزی که اطلاعات مجوز برای آن درخواست می شود؛ تقریباً در همه موارد، مقدار `auth Mode` باید `Script App.getAuthorizationInfo(ScriptApp.AuthMode.FULL)` باشد، زیرا هیچ حالت مجوز دیگری نیازی به اعطای مجوز توسط کاربران ندارد.

بازگشت

Authorization Info - یک شی که می تواند اطلاعاتی در مورد وضعیت مجوز کاربر ارائه دهد

`get Identity Token()`

در صورتی که محدوده openid اعطا شده باشد، یک رمز هویت Open ID Connect برای کاربر موثر دریافت می کند. این محدوده به طور پیش‌فرض گنجانده نشده است و برای درخواست آن باید آن را به عنوان یک محدوده واضح در فایل مانیفست اضافه کنید. دامنه‌های https://www.googleapis.com/auth/userinfo.email یا https://www.googleapis.com/auth/userinfo.profile را برای بازگرداندن اطلاعات اضافی کاربر در توکن وارد کنید.

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

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}`);

برای لیست کامل فیلدها (ادعاهای) بازگردانده شده به اسناد Open ID Connect مراجعه کنید.

بازگشت

String - نشانه هویت در صورت وجود. در غیر این صورت null .

`get Installation Source()`

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

بازگشت

Installation Source - منبع نصب.

`get OAuth Token()`

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

رمزی که با این روش برگردانده می شود فقط شامل محدوده هایی است که اسکریپت در حال حاضر به آنها نیاز دارد. دامنه‌هایی که قبلاً مجاز بوده‌اند اما دیگر توسط اسکریپت استفاده نمی‌شوند در توکن بازگشتی گنجانده نشده‌اند. اگر دامنه های OAuth اضافی فراتر از آنچه خود اسکریپت نیاز دارد مورد نیاز باشد، می توان آنها را در فایل مانیفست اسکریپت مشخص کرد .

بازگشت

String - نمایش رشته ای از توکن OAuth 2.0.

`get Project Triggers()`

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

Logger.log(
    `Current project has ${ScriptApp.getProjectTriggers().length} triggers.`,
);

بازگشت

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

مجوز

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

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

`get Script Id()`

شناسه منحصر به فرد پروژه اسکریپت را دریافت می کند. این روش ترجیحی برای به دست آوردن شناسه منحصر به فرد برای پروژه اسکریپت در مقابل get Project Key() است. این شناسه را می توان در تمام مکان هایی که قبلاً کلید پروژه ارائه شده است استفاده کرد.

بازگشت

String - شناسه پروژه اسکریپت.

`get Service()`

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

// Get the URL of the published web app.
const url = ScriptApp.getService().getUrl();

بازگشت

Service - شیء مورد استفاده برای مشاهده و کنترل انتشار اسکریپت به عنوان یک برنامه وب.

`get User Triggers(document)`

تمام محرک های قابل نصب متعلق به این کاربر را در سند داده شده، فقط برای این اسکریپت یا افزونه دریافت می کند. از این روش نمی توان برای مشاهده محرک های متصل به اسکریپت های دیگر استفاده کرد.

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

پارامترها

نام	تایپ کنید	توضیحات
`document`	`Document`	یک فایل Google Docs که ممکن است حاوی محرک‌های قابل نصب باشد.

بازگشت

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

مجوز

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

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

`get User Triggers(form)`

تمام محرک‌های قابل نصب متعلق به این کاربر را در فرم داده شده، فقط برای این اسکریپت یا افزونه دریافت می‌کند. از این روش نمی توان برای مشاهده محرک های متصل به اسکریپت های دیگر استفاده کرد.

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

پارامترها

نام	تایپ کنید	توضیحات
`form`	`Form`	یک فایل Google Forms که ممکن است حاوی راه‌اندازهای قابل نصب باشد.

بازگشت

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

مجوز

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

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

`get User Triggers(spreadsheet)`

همه محرک‌های قابل نصب متعلق به این کاربر را در صفحه‌گسترده داده شده، فقط برای این اسکریپت یا افزونه دریافت می‌کند. از این روش نمی توان برای مشاهده محرک های متصل به اسکریپت های دیگر استفاده کرد.

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

پارامترها

نام	تایپ کنید	توضیحات
`spreadsheet`	`Spreadsheet`	یک فایل Google Sheets که ممکن است حاوی محرک‌های قابل نصب باشد.

بازگشت

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

مجوز

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

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

`invalidate Auth()`

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

ScriptApp.invalidateAuth();

پرتاب می کند

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

`new State Token()`

سازنده ای برای یک نشانه وضعیت ایجاد می کند که می تواند در یک 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.
  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 می‌شود، که روش مشخص‌شده توسط State Token Builder.withMethod(method) را فراخوانی می‌کند.

بازگشت

State Token Builder - شیء مورد استفاده برای ادامه روند ساخت نشانه حالت.

`new Trigger(functionName)`

فرآیند ایجاد یک تریگر قابل نصب را آغاز می کند که هنگام روشن شدن، یک تابع معین را فراخوانی می کند.

// Creates an edit trigger for a spreadsheet identified by ID.
ScriptApp.newTrigger('myFunction')
    .forSpreadsheet('1234567890abcdefghijklmnopqrstuvwxyz_a1b2c3')
    .onEdit()
    .create();

پارامترها

نام	تایپ کنید	توضیحات
`function Name`	`String`	عملکردی که باید هنگام روشن شدن ماشه فراخوانی شود. می توانید از توابع کتابخانه های موجود مانند `Library.libFunction1` استفاده کنید.

بازگشت

Trigger Builder - شیء مورد استفاده برای ادامه فرآیند ساخت ماشه.

مجوز

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

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

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

`get Project Key()`

منسوخ شده است. به جای آن از get Script Id() استفاده کنید.

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

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

بازگشت

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

`get Script Triggers()`

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

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

Logger.log(
    `Current script has ${ScriptApp.getScriptTriggers().length} triggers.`,
);

بازگشت

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

مجوز

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

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