Class ScriptApp

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

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

پارامترها

مجوز

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

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

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

برخی از اجرای اسکریپت‌ها می‌توانند بدون رضایت کاربر برای تمام حوزه‌های مورد نیاز استفاده شده توسط اسکریپت شروع شوند. اطلاعات موجود در این شیء به شما امکان می‌دهد دسترسی به بخش‌هایی از کد را که به حوزه‌های خاصی نیاز دارند کنترل کنید و برای اجراهای بعدی، مجوز آن حوزه‌ها را درخواست کنید.

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

پارامترها

بازگشت

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

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

برخی از اجرای اسکریپت‌ها می‌توانند بدون رضایت کاربر برای تمام حوزه‌های مورد نیاز استفاده شده توسط اسکریپت شروع شوند. اطلاعات موجود در این شیء به شما امکان می‌دهد دسترسی به بخش‌هایی از کد را که به حوزه‌های خاصی نیاز دارند کنترل کنید و برای اجراهای بعدی درخواست مجوز برای آن حوزه‌ها را بدهید. حوزه‌هایی که نامعتبر هستند یا توسط اسکریپت مورد نیاز نیستند، منجر به خطا می‌شوند.

const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL, [
  'https://www.googleapis.com/auth/documents',
  'https://www.googleapis.com/auth/presentations',
]);
const status = authInfo.getAuthorizationStatus();
const url = authInfo.getAuthorizationUrl();

پارامترها

بازگشت

Authorization Info - شیء‌ای که اطلاعاتی در مورد وضعیت مجوز کاربر و یک URL مجوز در صورت عدم وجود برخی از رضایت‌نامه‌ها ارائه می‌دهد.

اگر دامنه 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}`);

بازگشت

String|null — توکن هویت در صورت موجود بودن؛ در غیر این صورت null .

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

بازگشت

Installation Source — منبع نصب.

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

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

شما می‌توانید از این متد برای فراخوانی APIهای گوگل که Apps Script مستقیماً از آنها پشتیبانی نمی‌کند، استفاده کنید. توکن برگردانده شده را در هدر `Authorization` یک درخواست HTTP با استفاده از Url Fetch App.fetch(url, params) ارسال کنید.

const url = 'https://www.googleapis.com/drive/v3/files';
const method = 'GET';
const headers = {
  Authorization: 'Bearer ' + ScriptApp.getOAuthToken(),
};
const response = UrlFetchApp.fetch(url, {
  method,
  headers,
});

بازگشت

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

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

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

بازگشت

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

مجوز

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

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

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

بازگشت

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

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

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

بازگشت

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

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

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

پارامترها

بازگشت

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

مجوز

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

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

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

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

پارامترها

بازگشت

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

مجوز

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

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

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

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

پارامترها

بازگشت

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

مجوز

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

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

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

ScriptApp.invalidateAuth();

پرتاب‌ها

Error - زمانی که اعتبارسنجی ناموفق باشد

یک سازنده برای توکن وضعیت ایجاد می‌کند که می‌تواند در یک 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 مستقیماً به نقطه پایانی مجوزدهی (authentication endpoint) ارسال می‌شود (نه به عنوان بخشی از 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 - شیئی که برای ادامه فرآیند ساخت توکن وضعیت استفاده می‌شود.

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

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

قبل از ایجاد یک تریگر، بررسی کنید که تابع مرتبط تمام مجوزهای لازم OAuth را دارد.

پارامترها

بازگشت

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

مجوز

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

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

تأیید می‌کند که آیا کاربر برای همهٔ حوزه‌های درخواستی اسکریپت، رضایت داده است یا خیر. اگر جریان اجرا به همهٔ حوزه‌های درخواستی اسکریپت وابسته است، از این متد استفاده کنید. اگر هر یک از رضایت‌نامه‌ها از دست رفته باشد، این متد اجرای فعلی را پایان می‌دهد و یک اعلان مجوز برای درخواست رضایت‌نامه‌های از دست رفته نمایش می‌دهد.

این روش فقط زمانی کار می‌کند که کاربران اسکریپت را از سطحی که از رضایت جزئی پشتیبانی می‌کند، مثلاً از درون Apps Script IDE، اجرا کنند. وقتی اسکریپت با رضایت‌های از دست رفته از سطحی پشتیبانی نشده، مانند افزونه‌ی Google Workspace، اجرا شود، اسکریپت در ابتدای اجرا یک اعلان مجوز برای درخواست همه حوزه‌ها ارائه می‌دهد.

ScriptApp.requireAllScopes(ScriptApp.AuthMode.FULL);

پارامترها

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

این روش فقط زمانی کار می‌کند که کاربران اسکریپت را از سطحی که از رضایت جزئی پشتیبانی می‌کند، مثلاً از درون Apps Script IDE، اجرا کنند. وقتی اسکریپت با رضایت‌های از دست رفته از سطحی پشتیبانی نشده، مانند افزونه‌ی Google Workspace، اجرا شود، اسکریپت در ابتدای اجرا یک اعلان مجوز برای درخواست همه حوزه‌ها ارائه می‌دهد.

ScriptApp.requireScopes(ScriptApp.AuthMode.FULL, [
  'https://www.googleapis.com/auth/documents',
  'https://www.googleapis.com/auth/presentations',
]);

پارامترها