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

devMode

boolean

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

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

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

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

หลังจากการดำเนินการเริ่มขึ้นแล้ว ผลลัพธ์จะมี 1 ใน 4 ผลลัพธ์ต่อไปนี้

  • หากฟังก์ชันสคริปต์แสดงผลสำเร็จ ช่อง response จะมีออบเจ็กต์ ExecutionResponse พร้อมค่าที่ส่งกลับของฟังก์ชันในช่อง result ของออบเจ็กต์
  • หากฟังก์ชันของสคริปต์ (หรือสคริปต์ Apps เอง) มีข้อยกเว้น ช่อง 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 from ที่เรียกใช้

ฟิลด์การรวม result ผลการดำเนินการ ซึ่งอาจเป็น error หรือ response ที่ถูกต้องก็ได้ หาก done == false ไม่ได้ตั้งค่าทั้ง error และ response หาก done == true ระบบอาจตั้งค่าเพียง error หรือ response บริการบางอย่างอาจไม่แสดงผลลัพธ์ result ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้เท่านั้น
error

object (Status)

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