Method: scripts.run

Menjalankan fungsi dalam 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 menyertakan 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 tepat untuk disertakan dalam token autentikasi, buka halaman Ringkasan project skrip, lalu 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 skrip yang akan dieksekusi. Temukan ID skrip di halaman Project settings 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 dijalankan dalam skrip yang diberikan. Nama tersebut tidak menyertakan tanda kurung atau parameter. Class 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. Khusus digunakan dengan add-on Android. ID yang mewakili sesi pengguna saat ini di aplikasi Android untuk Google Dokumen atau Spreadsheet, disertakan sebagai data tambahan dalam Intent yang meluncurkan add-on. Saat dijalankan dengan status sesi, add-on Android akan memperoleh hak istimewa berupa 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 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 tiba sampai fungsi selesai dieksekusi. Runtime eksekusi maksimum tercantum dalam Panduan kuota Apps Script.

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

  • 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 akan 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 baik kolom response maupun error tidak ada.
  • Jika panggilan run itu sendiri gagal (misalnya, karena permintaan yang salah format 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 menunjukkan apakah eksekusi skrip telah selesai. Eksekusi yang sudah selesai memiliki kolom response 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 ditetapkan. Jika done == true, hanya salah satu dari error atau response yang dapat ditetapkan. Beberapa layanan mungkin tidak memberikan hasilnya. 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 berupa:

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

string

Pesan error yang ditampilkan kepada developer, dalam bahasa Inggris. Setiap pesan error yang ditampilkan kepada pengguna 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" }.