這個外掛程式能在 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 |
要執行的指令碼指令碼 ID。在「專案設定」頁面的「ID」下方,找到指令碼 ID。 |
要求主體
要求主體的資料會採用以下結構:
JSON 表示法 |
---|
{ "function": string, "parameters": [ value ], "sessionState": string, "devMode": boolean } |
欄位 | |
---|---|
function |
要在指定指令碼中執行的函式名稱。名稱不包含括號或參數。可參照 |
parameters[] |
要傳遞至執行中函式的參數。每個參數的物件類型都必須符合 Apps Script 的預期類型。參數不得為 Apps Script 專用的物件類型 (例如 |
sessionState |
已淘汰。僅適用於 Android 外掛程式。這個 ID 代表使用者在 Google 文件或試算表的 Android 應用程式中目前工作階段,以額外資料的形式包含在啟動外掛程式的 Intent 中。Android 外掛程式在透過工作階段狀態執行時,會取得繫結指令碼的權限,也就是說,外掛程式可存取使用者目前在 Google 文件中的遊標位置,或 Google 試算表中所選儲存格的資訊。如要擷取狀態,請呼叫 |
devMode |
如果 |
回應主體
如果成功,回應主體即會包含具有以下結構的資料:
以 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 |
欄位 | |
---|---|
done |
這個欄位會指出指令碼是否已執行完成。已完成的執行作業中會填入填入內容的 |
聯集欄位 result 。這是作業的執行結果,可能為 error ,或是有效的 response 。如果 done == false ,系統不會將結果設定為 error ,也不會設定為 response 。如果 done == true ,則可以設定 error 或 response 其中之一。部分服務可能無法提供結果。result 只能是下列其中一個設定: |
|
error |
如果 |
response |
如果指令碼函式成功傳回,這個欄位會包含含有函式回傳值的 包含任意類型欄位的物件。額外的 |
授權範圍
需要下列其中一種 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 |
狀態碼。如果是這個 API,這個值可能為:
|
message |
向開發人員顯示的錯誤訊息,顯示英文內容。凡是向使用者顯示的錯誤訊息,都會經過本地化並透過 |
details[] |
包含單一 包含任意類型欄位的物件。額外的 |