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 .

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

بازگشت

Installation Source - منبع نصب.

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

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

بازگشت

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

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

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

بازگشت

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[] - آرایه ای از محرک های متعلق به این کاربر در سند داده شده.

مجوز

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

• 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[] - آرایه ای از محرک های متعلق به این کاربر در فرم داده شده.

مجوز

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

• 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[] - آرایه ای از محرک های متعلق به این کاربر در صفحه گسترده داده شده.

مجوز

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

• 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 مستقیماً به نقطه پایانی مجوز ارسال می‌شود (نه به عنوان بخشی از 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 - شیء مورد استفاده برای ادامه روند ساخت نشانه حالت.

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

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

پارامترها

بازگشت

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',
]);

پارامترها