Method: scripts.run

เรียกใช้ฟังก์ชันในโปรเจ็กต์ Apps Script ต้องทําให้โปรเจ็กต์ของสคริปต์ใช้งานได้กับ Apps Script API และแอปพลิเคชันการโทรต้องใช้โปรเจ็กต์ Cloud Platform เดียวกัน

วิธีนี้ต้องมีการให้สิทธิ์ด้วยโทเค็น OAuth 2.0 ที่มีขอบเขตที่ระบุในส่วนการให้สิทธิ์อย่างน้อย 1 ขอบเขต โครงการสคริปต์ที่ไม่จําเป็นต้องให้สิทธิ์จะดําเนินการผ่าน API นี้ไม่ได้ หากต้องการค้นหาขอบเขตที่ถูกต้องที่จะรวมในโทเค็นการตรวจสอบสิทธิ์ ให้เปิดหน้าภาพรวมของโปรเจ็กต์สคริปต์ แล้วเลื่อนลงไปที่ "ขอบเขต OAuth ของโครงการ"

ข้อผิดพลาด 403, PERMISSION_DENIED: The caller does not have permission ระบุว่าโปรเจ็กต์ Cloud Platform ที่ใช้ให้สิทธิ์คําขอไม่เหมือนกับโปรเจ็กต์ที่สคริปต์ใช้

คำขอ HTTP

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

URL ใช้ไวยากรณ์การแปลง gRPC

พารามิเตอร์เส้นทาง

พารามิเตอร์
scriptId

string

รหัสสคริปต์ที่จะเรียกใช้ ค้นหารหัสสคริปต์ในหน้าการตั้งค่าโปรเจ็กต์ในส่วน "รหัส"

เนื้อหาของคำขอ

เนื้อหาของคําขอมีข้อมูลที่มีโครงสร้างต่อไปนี้

การแสดง 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 เท่านั้น รหัสที่แสดงเซสชันปัจจุบันของผู้ใช้ในแอป Android สําหรับ Google เอกสารหรือชีต ซึ่งรวมอยู่ในข้อมูลเพิ่มเติมใน Intent ที่เรียกใช้ส่วนเสริม เมื่อส่วนเสริม Android ทํางานโดยมีสถานะเซสชัน ส่วนเสริมดังกล่าวจะได้รับสิทธิ์ของสคริปต์ bound ซึ่งหมายถึงสิทธิ์ดังกล่าว เช่น ตําแหน่งเคอร์เซอร์ปัจจุบันของผู้ใช้ (ในเอกสาร) หรือเซลล์ที่เลือก (ในชีต) หากต้องการเรียกดูสถานะนี้ โปรดโทรหา Intent.getStringExtra("com.google.android.apps.docs.addons.SessionState") ไม่บังคับ

devMode

boolean

หาก true และผู้ใช้เป็นเจ้าของสคริปต์ สคริปต์จะทํางานในเวอร์ชันที่บันทึกไว้ล่าสุด ไม่ใช่เวอร์ชันที่ใช้งานกับ Apps Script API ไม่บังคับ ค่าเริ่มต้นคือ false

เนื้อหาการตอบกลับ

หากทำสำเร็จ เนื้อหาการตอบกลับจะมีข้อมูลซึ่งมีโครงสร้างดังต่อไปนี้

การนําเสนอการเรียกใช้ฟังก์ชัน Apps Script ที่เริ่มต้นด้วย run การตอบกลับปฏิบัติการจะไม่มาถึงจนกว่าฟังก์ชันจะเสร็จสิ้น รันไทม์ของการดําเนินการสูงสุดจะแสดงอยู่ในคําแนะนําเกี่ยวกับโควต้าของ Apps Script

หลังจากการดําเนินการเริ่มขึ้น อาจมีผลลัพธ์อย่างใดอย่างหนึ่งต่อไปนี้

  • หากฟังก์ชันสคริปต์แสดงผลสําเร็จ ช่อง response จะมีออบเจ็กต์ ExecutionResponse ที่มีค่าการแสดงผลของฟังก์ชันในช่อง result ของออบเจ็กต์
  • หากฟังก์ชันสคริปต์ (หรือ Apps Script เอง) ส่งข้อยกเว้น ช่อง error จะมีออบเจ็กต์ Status ช่อง details ของออบเจ็กต์ Status มีอาร์เรย์ที่มีออบเจ็กต์ ExecutionError เดียวที่ให้ข้อมูลเกี่ยวกับลักษณะของข้อผิดพลาด
  • หากการดําเนินการยังไม่เสร็จสมบูรณ์ ช่อง done จะเป็น false และยังไม่มีช่อง response และ error
  • หากการเรียก run ล้มเหลว (เช่น เนื่องจากคําขอมีรูปแบบไม่ถูกต้องหรือเกิดข้อผิดพลาดในการให้สิทธิ์) เมธอดจะแสดงโค้ดตอบกลับ HTTP ในช่วง 4XX ด้วยรูปแบบอื่นสําหรับเนื้อความการตอบกลับ ไลบรารีของไคลเอ็นต์จะแปลงการตอบกลับ 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 จากฟังก์ชันที่ดําเนินการแล้ว

ช่อง Union result ผลการดําเนินการ ซึ่งอาจเป็น error หรือ response ที่ถูกต้อง หาก done == false จะไม่มีการตั้งค่า error หรือ response หาก done == true ระบบอาจตั้งค่า error หรือ response รายการหนึ่ง บริการบางอย่างอาจไม่ได้ให้ผลการค้นหา result ต้องเป็นอย่างใดอย่างหนึ่งต่อไปนี้
error

object (Status)

หากการเรียกใช้ run สําเร็จ แต่ฟังก์ชันสคริปต์ (หรือ Apps Script เอง) ยกเว้นข้อยกเว้น ช่องนี้จะมีออบเจ็กต์ Status ช่อง details ของออบเจ็กต์ Status มีอาร์เรย์ที่มีออบเจ็กต์ 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" }