Method: scripts.run

Menjalankan fungsi dalam project Apps Script. Project skrip harus di-deploy untuk digunakan dengan Apps Script API dan aplikasi yang memanggil harus menggunakan 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 dieksekusi 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 project yang digunakan oleh skrip.

Permintaan HTTP

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

URL ini menggunakan sintaksis gRPC Transcoding.

Parameter jalur

Parameter
deploymentId

string

ID deployment untuk deployment API yang Dapat Dieksekusi. Temukan ID deployment di bagian Deploy > Manage deployments di editor skrip.

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 tidak menyertakan tanda kurung atau parameter. Fungsi ini dapat mereferensikan fungsi di library yang disertakan seperti Library.libFunction1.
parameters[]

value (Value format)

Parameter yang akan diteruskan ke fungsi yang sedang dijalankan. 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 boleh 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, disertakan sebagai data tambahan dalam Intent yang meluncurkan add-on. Saat dijalankan dengan status sesi, add-on Android mendapatkan hak istimewa 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; default-nya 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 tiba hingga fungsi selesai dieksekusi. Runtime eksekusi maksimum tercantum dalam panduan kuota Apps Script.

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

  • Jika fungsi skrip berhasil ditampilkan, kolom response akan berisi objek ExecutionResponse dengan nilai yang ditampilkan fungsi 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 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 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 selesai memiliki kolom response yang diisi 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, hanya salah satu dari error atau response yang dapat ditetapkan. Beberapa layanan mungkin tidak memberikan hasil. result hanya dapat berupa salah satu dari hal berikut:
error

object (Status)

Jika panggilan run berhasil, tetapi fungsi skrip (atau Apps Script itu sendiri) menampilkan pengecualian, kolom ini akan 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 tipe arbitrer. Kolom tambahan "@type" berisi URI yang mengidentifikasi jenis arbitrer. 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 mendapatkan informasi selengkapnya, lihat Ringkasan OAuth 2.0.

Status

Jika panggilan run berhasil, tetapi fungsi skrip (atau Apps Script itu sendiri) memunculkan 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:

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

string

Pesan error yang ditampilkan kepada developer dan disampaikan 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 arbitrer. Contoh: { "id": 1234, "@type": "types.example.com/standard/id" }.