Method: scripts.run

Menjalankan fungsi di project Apps Script. Project skrip harus di-deploy untuk digunakan dengan Apps Script API dan aplikasi panggilan harus memiliki project Cloud Platform yang sama.

Metode ini memerlukan otorisasi dengan token OAuth 2.0 yang mencakup setidaknya salah satu cakupan yang tercantum di bagian Otorisasi; proyek skrip yang tidak memerlukan otorisasi tidak dapat dijalankan melalui API ini. Untuk menemukan cakupan yang tepat untuk disertakan dalam token autentikasi, buka halaman Overview project skrip, lalu scroll ke bawah ke "Project OAuth Scopes".

Error 403, PERMISSION_DENIED: The caller does not have permission menunjukkan bahwa project Cloud Platform yang digunakan untuk mengizinkan permintaan tidak sama dengan yang digunakan oleh skrip.

Permintaan HTTP

POST https://script.googleapis.com/v1/scripts/{scriptId}:run

URL menggunakan sintaksis gRPC Transcoding.

Parameter jalur

Parameter
scriptId

string

ID skrip dari skrip yang akan dieksekusi. Temukan ID skrip di halaman Setelan project di bagian "ID".

Isi permintaan

Isi permintaan memuat data dengan struktur berikut:

Representasi JSON 
{
  "function": string,
  "parameters": [
    value
  ],
  "sessionState": string,
  "devMode": boolean
}
Kolom
function

string

Nama fungsi yang akan dieksekusi dalam skrip yang diberikan. Nama tidak menyertakan tanda kurung atau parameter. Ia dapat mereferensikan fungsi dalam library yang disertakan seperti Library.libFunction1.
parameters[]

value (Value format)

Parameter yang akan diteruskan ke fungsi yang sedang dieksekusi. Jenis objek untuk setiap parameter harus cocok dengan jenis yang diharapkan di Apps Script. Parameter tidak boleh berupa jenis objek khusus Apps Script (seperti Document atau Calendar); kunci hanya dapat berupa jenis primitif seperti string, number, array, object, atau boolean. Opsional.
sessionState

string

Tidak digunakan lagi. Hanya untuk digunakan dengan add-on Android. ID yang mewakili sesi pengguna saat ini di aplikasi Android untuk Google Dokumen atau Spreadsheet, yang disertakan sebagai data tambahan dalam Intent yang meluncurkan add-on. Saat dijalankan dengan status sesi, add-on Android akan mendapatkan hak istimewa skrip terikat—yaitu, add-on dapat mengakses informasi seperti posisi kursor pengguna saat ini (di Dokumen) atau sel yang dipilih (di Spreadsheet). Untuk mengambil status, panggil Intent.getStringExtra("com.google.android.apps.docs.addons.SessionState"). Opsional.
devMode

boolean

Jika true dan pengguna adalah pemilik skrip, skrip akan berjalan pada versi yang terakhir disimpan, bukan versi yang di-deploy untuk digunakan dengan Apps Script API. Opsional; defaultnya adalah false.

Isi respons

Jika berhasil, isi respons memuat data dengan struktur berikut:

Representasi eksekusi fungsi Apps Script yang dimulai dengan run. Respons eksekusi tidak akan ditampilkan hingga fungsi selesai dieksekusi. Runtime eksekusi maksimum tercantum dalam panduan kuota Apps Script.

Setelah dimulai, eksekusi dapat memiliki salah satu dari empat hasil:

  • Jika fungsi skrip berhasil ditampilkan, kolom response berisi objek ExecutionResponse dengan nilai fungsi yang ditampilkan di kolom result objek.
  • Jika fungsi skrip (atau Apps Script itu sendiri) menampilkan pengecualian, kolom error berisi objek Status. Kolom details objek Status berisi array dengan satu objek ExecutionError yang memberikan informasi tentang sifat error.
  • Jika eksekusi belum selesai, kolom done adalah false dan tidak ada kolom response atau error.
  • Jika panggilan run itu sendiri gagal (misalnya, karena format permintaan salah atau error otorisasi), metode ini akan menampilkan kode respons HTTP dalam rentang 4XX dengan format yang berbeda untuk isi respons. Library klien secara otomatis mengonversi respons 4XX menjadi class pengecualian.

Representasi JSON 
{
  "done": boolean,

  // Union field result can be only one of the following:
  "error": {
    object (Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  }
  // End of list of possible types for union field result.
}
Kolom
done

boolean

Kolom ini akan menunjukkan apakah eksekusi skrip telah selesai. Eksekusi yang selesai memiliki kolom response yang terisi dan berisi ExecutionResponse dari fungsi yang dieksekusi.
Kolom union result. Hasil operasi, yang dapat berupa error atau response yang valid. Jika done == false, error atau response tidak ditetapkan. Jika done == true, tepat satu dari error atau response dapat ditetapkan. Beberapa layanan mungkin tidak memberikan hasil. result hanya dapat berupa salah satu dari berikut:
error

object (Status)

Jika panggilan run berhasil, tetapi fungsi skrip (atau Apps Script itu sendiri) menampilkan pengecualian, kolom ini berisi objek Status. Kolom details objek Status berisi array dengan satu objek ExecutionError yang memberikan informasi tentang sifat error.
response

object

Jika fungsi skrip berhasil ditampilkan, kolom ini berisi objek ExecutionResponse dengan nilai fungsi yang ditampilkan.

Objek yang berisi kolom tipe arbitrer. Kolom tambahan "@type" berisi URI yang mengidentifikasi jenis. Contoh: { "id": 1234, "@type": "types.example.com/standard/id" }.

Cakupan Otorisasi

Memerlukan salah satu cakupan OAuth berikut:

  • https://apps-apis.google.com/a/feeds
  • https://apps-apis.google.com/a/feeds/alias/
  • https://apps-apis.google.com/a/feeds/groups/
  • https://mail.google.com/
  • https://sites.google.com/feeds
  • https://www.google.com/calendar/feeds
  • https://www.google.com/m8/feeds
  • https://www.googleapis.com/auth/admin.directory.group
  • https://www.googleapis.com/auth/admin.directory.user
  • https://www.googleapis.com/auth/documents
  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/dynamiccreatives
  • https://www.googleapis.com/auth/forms
  • https://www.googleapis.com/auth/forms.currentonly
  • https://www.googleapis.com/auth/groups
  • https://www.googleapis.com/auth/script.cpanel
  • https://www.googleapis.com/auth/script.external_request
  • https://www.googleapis.com/auth/script.scriptapp
  • https://www.googleapis.com/auth/script.send_mail
  • https://www.googleapis.com/auth/script.storage
  • https://www.googleapis.com/auth/script.webapp.deploy
  • https://www.googleapis.com/auth/spreadsheets
  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/sqlservice
  • https://www.googleapis.com/auth/userinfo.email

Untuk informasi selengkapnya, lihat Ringkasan OAuth 2.0.

Status

Jika panggilan run berhasil, tetapi fungsi skrip (atau Apps Script itu sendiri) menampilkan pengecualian, kolom error isi respons akan berisi objek Status ini.

Representasi JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Kolom
code

integer

Kode status. Untuk API ini, nilai ini dapat:

  • 10, menunjukkan error SCRIPT_TIMEOUT.
  • 3, menunjukkan error INVALID_ARGUMENT, atau
  • 1, yang menunjukkan eksekusi CANCELLED.
message

string

Pesan error yang ditampilkan kepada developer, dalam bahasa Inggris. Pesan error yang ditampilkan kepada pengguna akan dilokalkan dan dikirim di kolom details, atau dilokalkan oleh klien.
details[]

object

Array yang berisi satu objek ExecutionError yang memberikan informasi tentang sifat error.

Objek yang berisi kolom tipe arbitrer. Kolom tambahan "@type" berisi URI yang mengidentifikasi jenis. Contoh: { "id": 1234, "@type": "types.example.com/standard/id" }.