Class ScriptApp

ScriptApp

Mengakses dan memanipulasi publikasi skrip dan pemicu. Class ini memungkinkan pengguna membuat pemicu skrip dan mengontrol publikasi skrip sebagai layanan.

Properti

PropertiJenisDeskripsi
AuthModeAuthModeEnumerasi yang mengidentifikasi kategori layanan yang diizinkan Apps Script yang dapat dieksekusi melalui fungsi yang dipicu.
AuthorizationStatusAuthorizationStatusEnumerasi yang menunjukkan status otorisasi skrip.
EventTypeEventTypeEnumerasi yang menunjukkan jenis peristiwa yang dipicu.
InstallationSourceInstallationSourceEnumerasi yang menunjukkan bagaimana skrip diinstal kepada pengguna sebagai add-on.
TriggerSourceTriggerSourceEnumerasi yang menunjukkan sumber peristiwa yang menyebabkan pemicu diaktifkan.
WeekDayWeekdayEnumerasi yang mewakili hari dalam seminggu.

Metode

MetodeJenis hasil yang ditampilkanDeskripsi singkat
deleteTrigger(trigger)voidMenghapus pemicu tertentu sehingga tidak lagi berjalan.
getAuthorizationInfo(authMode)AuthorizationInfoMendapatkan objek yang digunakan untuk menentukan apakah pengguna perlu memberikan otorisasi pada skrip ini untuk menggunakan satu atau beberapa layanan, dan memberikan URL untuk dialog otorisasi.
getIdentityToken()StringMendapatkan token identitas OpenID Connect untuk pengguna efektif, jika cakupan openid telah diberikan.
getInstallationSource()InstallationSourceMenampilkan nilai enum yang menunjukkan cara skrip diinstal sebagai add-on untuk pengguna saat ini (misalnya, apakah pengguna menginstalnya secara pribadi melalui Chrome Web Store, atau apakah administrator domain menginstalnya untuk semua pengguna).
getOAuthToken()StringMendapatkan token akses OAuth 2.0 untuk pengguna yang efektif.
getProjectTriggers()Trigger[]Mendapatkan semua pemicu yang dapat diinstal yang terkait dengan project saat ini dan pengguna saat ini.
getScriptId()StringMendapatkan ID unik project skrip.
getService()ServiceMendapatkan objek yang digunakan untuk mengontrol publikasi skrip sebagai aplikasi web.
getUserTriggers(document)Trigger[]Mendapatkan semua pemicu yang dapat diinstal yang dimiliki oleh pengguna ini dalam dokumen yang ditentukan, untuk skrip ini atau add-on saja.
getUserTriggers(form)Trigger[]Mendapatkan semua pemicu yang dapat diinstal yang dimiliki oleh pengguna ini dalam bentuk tertentu, untuk skrip atau add-on ini saja.
getUserTriggers(spreadsheet)Trigger[]Mendapatkan semua pemicu penginstalan yang dimiliki oleh pengguna ini di spreadsheet yang ditentukan, untuk skrip ini atau add-on saja.
invalidateAuth()voidMembatalkan otorisasi yang dimiliki pengguna efektif untuk mengeksekusi skrip saat ini.
newStateToken()StateTokenBuilderMembuat builder untuk token status yang dapat digunakan di callback API (seperti alur OAuth).
newTrigger(functionName)TriggerBuilderMemulai proses pembuatan pemicu yang dapat diinstal yang, saat diaktifkan, akan memanggil fungsi tertentu.

Dokumentasi mendetail

deleteTrigger(trigger)

Menghapus pemicu tertentu sehingga tidak lagi berjalan. 

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

Parameter

NamaJenisDeskripsi
triggerTriggerPemicu yang akan dihapus.

Otorisasi

Skrip yang menggunakan metode ini memerlukan otorisasi dengan satu atau beberapa cakupan berikut:

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

getAuthorizationInfo(authMode)

Mendapatkan objek yang digunakan untuk menentukan apakah pengguna perlu memberikan otorisasi pada skrip ini untuk menggunakan satu atau beberapa layanan, dan memberikan URL untuk dialog otorisasi. Jika skrip dipublikasikan sebagai add-on yang menggunakan pemicu yang dapat diinstal, informasi ini dapat digunakan untuk mengontrol akses ke bagian kode yang tidak memiliki otorisasi yang diperlukan pengguna. Atau, add-on dapat meminta pengguna untuk membuka URL untuk dialog otorisasi guna menyelesaikan masalah. 

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

Parameter

NamaJenisDeskripsi
authModeAuthModemode otorisasi yang meminta informasi otorisasi; dalam hampir semua kasus, nilai untuk authMode harus ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL), karena tidak ada mode otorisasi lain yang mengharuskan pengguna memberikan otorisasi

Return

AuthorizationInfo — objek yang dapat memberikan informasi tentang status otorisasi pengguna

getIdentityToken()

Mendapatkan token identitas OpenID Connect untuk pengguna efektif, jika cakupan openid telah diberikan. Cakupan ini tidak disertakan secara default, dan Anda harus menambahkannya sebagai cakupan eksplisit dalam file manifes untuk memintanya. Sertakan cakupan https://www.googleapis.com/auth/userinfo.email atau https://www.googleapis.com/auth/userinfo.profile untuk menampilkan informasi pengguna tambahan dalam token.

Token ID yang ditampilkan adalah JSON Web Token (JWT) yang dienkode, dan harus didekode untuk mengekstrak informasi darinya. Contoh berikut menunjukkan cara mendekode token dan mengekstrak ID profil Google pengguna yang efektif. 

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);
Lihat dokumentasi OpenID Connect untuk mengetahui daftar lengkap kolom (klaim) yang ditampilkan.

Return

String — Token identitas jika tersedia; jika tidak, null.

getInstallationSource()

Menampilkan nilai enum yang menunjukkan cara skrip diinstal sebagai add-on untuk pengguna saat ini (misalnya, apakah pengguna menginstalnya secara pribadi melalui Chrome Web Store, atau apakah administrator domain menginstalnya untuk semua pengguna).

Return

InstallationSource — Sumber penginstalan.

getOAuthToken()

Mendapatkan token akses OAuth 2.0 untuk pengguna yang efektif. Jika cakupan OAuth skrip cukup untuk memberi otorisasi Google API lain yang biasanya memerlukan alur OAuth-nya sendiri (seperti Alat Pilih Google), skrip dapat mengabaikan perintah otorisasi kedua dengan meneruskan token ini. Masa berlaku token akan berakhir setelah beberapa waktu (minimal beberapa menit); skrip akan menangani kegagalan otorisasi dan memanggil metode ini untuk mendapatkan token baru jika diperlukan.

Token yang ditampilkan oleh metode ini hanya menyertakan cakupan yang saat ini diperlukan skrip. Cakupan yang sebelumnya diizinkan, tetapi tidak lagi digunakan oleh skrip tidak disertakan dalam token yang ditampilkan. Jika cakupan OAuth tambahan diperlukan melebihi yang diperlukan skrip, cakupan tersebut dapat ditentukan dalam file manifes skrip.

Return

String — Representasi string dari token OAuth 2.0.

getProjectTriggers()

Mendapatkan semua pemicu yang dapat diinstal yang terkait dengan project saat ini dan pengguna saat ini. 

Logger.log('Current project has ' + ScriptApp.getProjectTriggers().length + ' triggers.');

Return

Trigger[] — Array pemicu pengguna saat ini yang terkait dengan project ini.

Otorisasi

Skrip yang menggunakan metode ini memerlukan otorisasi dengan satu atau beberapa cakupan berikut:

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

getScriptId()

Mendapatkan ID unik project skrip. Ini adalah metode pilihan guna mendapatkan ID unik untuk project skrip, bukan getProjectKey(). ID ini dapat digunakan di semua tempat yang sebelumnya menyediakan kunci project.

Return

String — ID project skrip.

getService()

Mendapatkan objek yang digunakan untuk mengontrol publikasi skrip sebagai aplikasi web. 

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

Return

Service — Objek yang digunakan untuk mengamati dan mengontrol publikasi skrip sebagai aplikasi web.

getUserTriggers(document)

Mendapatkan semua pemicu yang dapat diinstal yang dimiliki oleh pengguna ini dalam dokumen yang ditentukan, untuk skrip ini atau add-on saja. Metode ini tidak dapat digunakan untuk melihat pemicu yang dilampirkan ke skrip lain. 

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

Parameter

NamaJenisDeskripsi
documentDocumentFile Google Dokumen yang mungkin berisi pemicu yang dapat diinstal.

Return

Trigger[] — Array pemicu yang dimiliki oleh pengguna ini dalam dokumen tertentu.

Otorisasi

Skrip yang menggunakan metode ini memerlukan otorisasi dengan satu atau beberapa cakupan berikut:

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

getUserTriggers(form)

Mendapatkan semua pemicu yang dapat diinstal yang dimiliki oleh pengguna ini dalam bentuk tertentu, untuk skrip atau add-on ini saja. Metode ini tidak dapat digunakan untuk melihat pemicu yang dilampirkan ke skrip lain. 

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

Parameter

NamaJenisDeskripsi
formFormFile Google Formulir yang mungkin berisi pemicu yang dapat diinstal.

Return

Trigger[] — Array pemicu yang dimiliki oleh pengguna ini dalam bentuk tertentu.

Otorisasi

Skrip yang menggunakan metode ini memerlukan otorisasi dengan satu atau beberapa cakupan berikut:

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

getUserTriggers(spreadsheet)

Mendapatkan semua pemicu penginstalan yang dimiliki oleh pengguna ini di spreadsheet yang ditentukan, untuk skrip ini atau add-on saja. Metode ini tidak dapat digunakan untuk melihat pemicu yang dilampirkan ke skrip lain. 

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

Parameter

NamaJenisDeskripsi
spreadsheetSpreadsheetFile Google Spreadsheet yang mungkin berisi pemicu yang dapat diinstal.

Return

Trigger[] — Array pemicu yang dimiliki oleh pengguna ini di spreadsheet yang diberikan.

Otorisasi

Skrip yang menggunakan metode ini memerlukan otorisasi dengan satu atau beberapa cakupan berikut:

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

invalidateAuth()

Membatalkan otorisasi yang dimiliki pengguna efektif untuk mengeksekusi skrip saat ini. Digunakan untuk membatalkan izin apa pun untuk skrip saat ini. Hal ini sangat berguna untuk fungsi yang ditandai sebagai otorisasi satu kali. Karena fungsi otorisasi satu kali hanya dapat dipanggil untuk pertama kali dijalankan setelah skrip mendapatkan otorisasi. Jika ingin melakukan tindakan setelahnya, Anda harus mencabut semua otorisasi yang dimiliki skrip agar pengguna dapat melihat dialog otorisasi lagi. 

ScriptApp.invalidateAuth();

Menampilkan

Error — saat pembatalan validasi gagal

newStateToken()

Membuat builder untuk token status yang dapat digunakan di callback API (seperti alur 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;
}

Di sebagian besar alur OAuth2, token state diteruskan ke endpoint otorisasi secara langsung (bukan sebagai bagian dari URL callback), dan endpoint otorisasi meneruskannya sebagai bagian dari URL callback.

Contoh:

  • Skrip mengalihkan pengguna ke URL otorisasi 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
  • Pengguna mengklik izinkan, dan halaman otorisasi OAuth2 mengalihkan pengguna kembali ke https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz/usercallback?state=token_generated_with_this_method&other_params_that_include_tokens_or_grants
  • Pengalihan di atas (kembali ke http://script.google.com/...), menyebabkan permintaan browser ke /usercallback, yang memanggil metode yang ditentukan oleh StateTokenBuilder.withMethod(method).

Return

StateTokenBuilder — Objek yang digunakan untuk melanjutkan proses pembuatan token status.

newTrigger(functionName)

Memulai proses pembuatan pemicu yang dapat diinstal yang, saat diaktifkan, akan memanggil fungsi tertentu. 

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

Parameter

NamaJenisDeskripsi
functionNameStringFungsi yang akan dipanggil saat pemicu diaktifkan. Anda dapat menggunakan fungsi dari library yang disertakan, seperti Library.libFunction1.

Return

TriggerBuilder — Objek yang digunakan untuk melanjutkan proses pembuatan pemicu.

Otorisasi

Skrip yang menggunakan metode ini memerlukan otorisasi dengan satu atau beberapa cakupan berikut:

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

Metode yang tidak digunakan lagi