Method: scripts.run

Menjalankan fungsi dalam project Apps Script. Project skrip harus di-deploy untuk digunakan dengan Apps Script API dan aplikasi panggilan harus berbagi 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; project skrip yang tidak memerlukan otorisasi tidak dapat dijalankan melalui API ini. Untuk menemukan cakupan yang benar untuk disertakan dalam token autentikasi, buka halaman Ringkasan project skrip dan scroll ke bawah ke "Cakupan OAuth Project".

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 tertentu. Nama tidak menyertakan tanda kurung atau parameter. Fungsi ini 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); parameter hanya dapat berupa jenis primitif seperti string, number, array, object, atau boolean. Opsional.
sessionState

string

Tidak digunakan lagi. Untuk digunakan dengan add-on Android saja. 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 berjalan dengan status sesi, add-on Android mendapatkan hak istimewa dari skrip terikat—yaitu, 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 dijalankan pada versi terbaru yang disimpan, bukan versi yang di-deploy untuk digunakan dengan Apps Script API. Opsional; default-nya adalah false.

Isi respons

Jika berhasil, isi respons memuat data dengan struktur berikut:

Representasi eksekusi fungsi Apps Script dimulai dengan run. Respons eksekusi tidak muncul hingga fungsi selesai dijalankan. 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 yang ditampilkan fungsi 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 kolom response maupun error tidak ada.
  • Jika panggilan run itu sendiri gagal (misalnya, karena permintaan yang salah atau error otorisasi), metode 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 menunjukkan apakah eksekusi skrip telah selesai. Eksekusi yang telah selesai memiliki kolom response yang terisi yang 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 akan ditetapkan. Jika done == true, maka hanya satu dari error atau response yang 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 yang ditampilkan fungsi.

Objek yang berisi kolom dengan jenis arbitrer. Kolom tambahan "@type" berisi URI yang mengidentifikasi jenisnya. 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, yang 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 ke 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 dengan jenis arbitrer. Kolom tambahan "@type" berisi URI yang mengidentifikasi jenisnya. Contoh: { "id": 1234, "@type": "types.example.com/standard/id" }.