Method: scripts.run

這個外掛程式能在 Apps Script 專案中執行函式。指令碼專案必須部署才能與 Apps Script API 搭配使用，而呼叫應用程式必須共用相同的 Cloud Platform 專案。

如要使用這個方法，請使用 OAuth 2.0 權杖進行授權，且該權杖至少須包含「授權」部分所列的其中一個範圍；不需要授權的指令碼專案則無法透過這個 API 執行。如要尋找驗證權杖適用的正確範圍，請開啟指令碼專案的「總覽」頁面，然後向下捲動至「專案 OAuth 範圍」。

錯誤 403, PERMISSION_DENIED: The caller does not have permission 表示用於授權要求的 Cloud Platform 專案與指令碼使用的專案不同。

HTTP 要求

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

這個網址使用 gRPC 轉碼語法。

路徑參數

參數
scriptId

string

要執行的指令碼指令碼 ID。在「專案設定」頁面的「ID」下方，找到指令碼 ID。

要求主體

要求主體的資料會採用以下結構：

JSON 表示法 
{
  "function": string,
  "parameters": [
    value
  ],
  "sessionState": string,
  "devMode": boolean
}
欄位
function

string

要在指定指令碼中執行的函式名稱。名稱不包含括號或參數。可參照 Library.libFunction1 等內含程式庫中的函式。
parameters[]

value (Value format)

要傳遞至執行中函式的參數。每個參數的物件類型都必須符合 Apps Script 的預期類型。參數不得為 Apps Script 專用的物件類型 (例如 Document 或 Calendar)，只能使用原始類型，例如 string、number、array、object 或 boolean。選用。
sessionState

string

已淘汰。僅適用於 Android 外掛程式。這個 ID 代表使用者在 Google 文件或試算表的 Android 應用程式中目前工作階段，以額外資料的形式包含在啟動外掛程式的 Intent 中。Android 外掛程式在透過工作階段狀態執行時，會取得繫結指令碼的權限，也就是說，外掛程式可存取使用者目前在 Google 文件中的遊標位置，或 Google 試算表中所選儲存格的資訊。如要擷取狀態，請呼叫 Intent.getStringExtra("com.google.android.apps.docs.addons.SessionState")。選用。
devMode

boolean

如果 true 且使用者是指令碼擁有者，則指令碼會以最近儲存的版本執行，而非部署以搭配 Apps Script API 使用的版本。選用，預設值為 false。

回應主體

如果成功，回應主體即會包含具有以下結構的資料：

以 run 啟動的 Apps Script 函式執行表示法。除非函式執行完畢，否則不會收到執行回應。您可以參閱 Apps Script 配額指南，瞭解其執行的最大執行階段數量。

執行作業開始後，可能會產生以下四種結果之一：

  • 如果指令碼函式成功傳回，response 欄位就會包含 ExecutionResponse 物件，且該物件會在物件的 result 欄位中提供函式回傳值。
  • 如果指令碼函式 (或 Apps Script 本身) 擲回例外狀況，error 欄位會包含 Status 物件。Status 物件的 details 欄位包含一個陣列，其中包含單一 ExecutionError 物件，該物件可提供錯誤性質的相關資訊。
  • 如果執行作業尚未完成，done 欄位為 false，且 response 和 error 欄位都不會顯示。
  • 如果 run 呼叫本身失敗 (例如要求格式錯誤或授權錯誤)，這個方法會在 4XX 範圍內傳回 HTTP 回應代碼，回應主體的格式也不同。用戶端程式庫會自動將 4XX 回應轉換為例外狀況類別。

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.
}
欄位
done

boolean

這個欄位會指出指令碼是否已執行完成。已完成的執行作業中會填入填入內容的 response 欄位，其中包含所執行的函式中的 ExecutionResponse。
聯集欄位 result。這是作業的執行結果，可能為 error，或是有效的 response。如果 done == false，系統不會將結果設定為 error，也不會設定為 response。如果 done == true，則可以設定 error 或 response 其中之一。部分服務可能無法提供結果。result 只能是下列其中一個設定：
error

object (Status)

如果 run 呼叫成功，但指令碼函式 (或 Apps Script 本身) 擲回例外狀況，則此欄位會包含 Status 物件。Status 物件的 details 欄位包含一個陣列，其中包含單一 ExecutionError 物件，該物件可提供錯誤性質的相關資訊。
response

object

如果指令碼函式成功傳回，這個欄位會包含含有函式回傳值的 ExecutionResponse 物件。

包含任意類型欄位的物件。額外的 "@type" 欄位則包含能辨識類型的 URI。例如：{ "id": 1234, "@type": "types.example.com/standard/id" }.

授權範圍

需要下列其中一種 OAuth 範圍：

  • 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

詳情請參閱 OAuth 2.0 總覽。

狀態

如果 run 呼叫成功，但指令碼函式 (或 Apps Script 本身) 擲回例外狀況，回應主體的 error 欄位會包含這個 Status 物件。

JSON 表示法 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
欄位
code

integer

狀態碼。如果是這個 API，這個值可能為：

  • 10，表示發生 SCRIPT_TIMEOUT 錯誤，
  • 3，表示發生 INVALID_ARGUMENT 錯誤，或
  • 1，表示 CANCELLED 執行作業。
message

string

向開發人員顯示的錯誤訊息，顯示英文內容。凡是向使用者顯示的錯誤訊息，都會經過本地化並透過 details 欄位傳送，或是由用戶端加以本地化。
details[]

object

包含單一 ExecutionError 物件，可提供錯誤性質相關資訊的陣列。

包含任意類型欄位的物件。額外的 "@type" 欄位則包含能辨識類型的 URI。例如：{ "id": 1234, "@type": "types.example.com/standard/id" }.