คู่มือนี้จะแนะนำแนวคิดต่างๆ เช่น วิธีการหลักในการสร้าง Google Docs API, วิธีเข้าถึงเอกสาร และเวิร์กโฟลว์เมื่อสร้างเอกสาร
เมธอดของ API
ทรัพยากร documents
จะมีเมธอดที่คุณใช้เพื่อเรียกใช้ Docs API วิธีการต่อไปนี้ช่วยให้คุณสร้าง อ่าน และอัปเดตเอกสารของเอกสาร
- ใช้วิธีการ
documents.create
เพื่อสร้างเอกสาร - ใช้เมธอด
documents.get
เพื่อเรียกข้อมูลเนื้อหาของเอกสารที่ระบุ - ใช้เมธอด
documents.batchUpdate
เพื่อดำเนินการชุดการอัปเดตในเอกสารที่ระบุในระดับอะตอม
เมธอด documents.get
และ documents.batchUpdate
ต้องใช้ documentId
เป็นพารามิเตอร์เพื่อระบุเอกสารเป้าหมาย เมธอด documents.create
จะแสดงผลอินสแตนซ์ของเอกสารที่สร้างขึ้น ซึ่งคุณจะอ่าน documentId
ได้ โปรดดูข้อมูลเพิ่มเติมเกี่ยวกับคำขอ Docs API และวิธีการตอบกลับที่คำขอและการตอบกลับ
รหัสเอกสาร
documentId
เป็นตัวระบุที่ไม่ซ้ำกันสำหรับเอกสาร ซึ่งดึงมาจาก URL ของเอกสารได้ สตริงนี้มีตัวอักษร ตัวเลข และสัญลักษณ์พิเศษบางตัว รหัสเอกสารจะคงที่ แม้ว่าชื่อเอกสารจะมีการเปลี่ยนแปลงก็ตาม
https://docs.google.com/document/d/DOCUMENT_ID/edit
คุณใช้นิพจน์ทั่วไปต่อไปนี้เพื่อดึง documentId
จาก URL ของ Google เอกสารได้
/document/d/([a-zA-Z0-9-_]+)
หากคุณคุ้นเคยกับ Google Drive API อยู่แล้ว documentId
จะสอดคล้องกับ id
ในทรัพยากรของ files
จัดการเอกสารใน Google ไดรฟ์
ไฟล์เอกสารจะเก็บอยู่ใน Google ไดรฟ์ ซึ่งเป็นบริการจัดเก็บข้อมูลในระบบคลาวด์ของเรา แม้ว่า Docs API จะมีเมธอดแยกต่างหากของตัวเอง แต่ก็มักจะจำเป็นต้องใช้เมธอด Google Drive API เพื่อโต้ตอบกับไฟล์เอกสารของผู้ใช้ด้วย เช่น หากต้องการคัดลอกไฟล์เอกสาร ให้ใช้เมธอด files.copy
ของ Drive API ดูข้อมูลเพิ่มเติมได้ที่คัดลอกเอกสารที่มีอยู่
โดยค่าเริ่มต้น เมื่อใช้ Docs API เอกสารใหม่จะบันทึกลงในโฟลเดอร์รากของผู้ใช้ในไดรฟ์ มีตัวเลือกสำหรับการบันทึกไฟล์ ไปยังโฟลเดอร์ไดรฟ์ ดูข้อมูลเพิ่มเติมได้ที่ทำงานกับโฟลเดอร์ Google ไดรฟ์
ทำงานกับไฟล์เอกสาร
หากต้องการเรียกเอกสารจาก "ไดรฟ์ของฉัน" ของผู้ใช้ คุณมักจะต้องใช้เมธอด files.list
ของไดรฟ์เพื่อเรียกข้อมูลรหัสสำหรับไฟล์ก่อน การเรียกใช้เมธอดที่ไม่มีพารามิเตอร์ใดๆ จะแสดงรายการไฟล์และโฟลเดอร์ทั้งหมด รวมถึงรหัสของผู้ใช้
ประเภท MIME ของเอกสารจะระบุประเภทและรูปแบบข้อมูล รูปแบบประเภท MIME สำหรับเอกสารคือ application/vnd.google-apps.document
ดูรายการประเภท MIME ได้ที่ประเภท MIME ที่ Google Workspace และ Google ไดรฟ์รองรับ
หากต้องการค้นหาเฉพาะไฟล์เอกสารภายในไดรฟ์ของฉันตามประเภท MIME ให้เพิ่มตัวกรองสตริงข้อความค้นหาต่อไปนี้
q: mimeType = 'application/vnd.google-apps.document'
ดูข้อมูลเพิ่มเติมเกี่ยวกับตัวกรองสตริงการค้นหาได้ที่ค้นหาไฟล์และโฟลเดอร์
เมื่อทราบ documentId
แล้ว ให้ใช้เมธอด documents.get
เพื่อเรียกข้อมูลอินสแตนซ์ที่สมบูรณ์ของเอกสารที่ระบุ ดูข้อมูลเพิ่มเติมได้ที่คําขอและการตอบกลับ
หากต้องการส่งออกเนื้อหาไบต์ของเอกสารของ Google Workspace ให้ใช้เมธอด files.export
ของไดรฟ์กับไฟล์ documentId
เพื่อส่งออก และส่งออกประเภท MIME ที่ถูกต้อง โปรดดูข้อมูลเพิ่มเติมที่หัวข้อส่งออกเนื้อหาเอกสารใน Google Workspace
เปรียบเทียบเมธอด Get
และ List
ตารางต่อไปนี้อธิบายความแตกต่างระหว่างเมธอดต่างๆ ของไดรฟ์และเอกสาร และข้อมูลที่แสดงผลกับแต่ละวิธี
ผู้ประกอบธุรกิจ | คำอธิบาย | การใช้งาน |
---|---|---|
drive.files.get |
ดูข้อมูลเมตาของไฟล์ตามรหัส แสดงผลอินสแตนซ์ของทรัพยากร files |
ดูข้อมูลเมตาสำหรับไฟล์ที่ต้องการ |
drive.files.list |
รับไฟล์ของผู้ใช้ แสดงรายการไฟล์ | ดูรายการไฟล์ของผู้ใช้เมื่อไม่แน่ใจว่าต้องแก้ไขไฟล์ใด |
docs.documents.get |
รับเอกสารที่ระบุเวอร์ชันล่าสุด ซึ่งรวมถึงการจัดรูปแบบและข้อความทั้งหมด แสดงผลอินสแตนซ์ของทรัพยากร documents |
รับเอกสารสำหรับรหัสเอกสารที่ต้องการ |
ขั้นตอนการสร้างเอกสาร
การสร้างและป้อนข้อมูลเอกสารใหม่นั้นทำได้ง่าย เนื่องจากไม่มีเนื้อหาให้ต้องกังวลและไม่มีผู้ทำงานร่วมกันที่เปลี่ยนสถานะเอกสารได้ โดยหลักการแล้ว กระบวนการนี้จะทำงานตามที่แสดงในแผนภาพลำดับต่อไปนี้
ในรูปที่ 1 ผู้ใช้ที่โต้ตอบกับทรัพยากร documents
จะมีโฟลว์ข้อมูลต่อไปนี้
- แอปเรียกใช้เมธอด
documents.create
ในเว็บเซิร์ฟเวอร์ - เว็บเซิร์ฟเวอร์จะส่งการตอบกลับ HTTP ที่มีอินสแตนซ์ของเอกสารที่สร้างขึ้นเป็นทรัพยากร
documents
- (ไม่บังคับ) แอปจะเรียกใช้เมธอด
documents.batchUpdate
เพื่อดำเนินการชุดคำขอแก้ไขในระดับอะตอมเพื่อป้อนข้อมูลในเอกสาร - เว็บเซิร์ฟเวอร์จะส่งการตอบกลับ HTTP เมธอด
documents.batchUpdate
บางเมธอดจะระบุเนื้อหาการตอบกลับพร้อมข้อมูลเกี่ยวกับคำขอที่ใช้ ขณะที่เมธอดอื่นๆ จะแสดงการตอบกลับที่ว่างเปล่า
เวิร์กโฟลว์การอัปเดตเอกสาร
การอัปเดตเอกสารที่มีอยู่มีความซับซ้อนมากขึ้น ก่อนจะดำเนินการเรียกใช้ที่สำคัญเพื่ออัปเดตเอกสาร คุณต้องทราบสถานะปัจจุบันของเอกสารก่อน เช่น องค์ประกอบประกอบด้วยองค์ประกอบใด เนื้อหาใดอยู่ในองค์ประกอบเหล่านั้น และลำดับขององค์ประกอบภายในเอกสาร แผนภาพลำดับต่อไปนี้จะแสดงวิธีการทำงาน
ในรูปที่ 2 ผู้ใช้ที่โต้ตอบกับทรัพยากร documents
จะมีข้อมูลต่อไปนี้
- แอปเรียกใช้เมธอด
documents.get
ในเว็บเซิร์ฟเวอร์โดยใช้documentId
ของไฟล์เพื่อค้นหา - เว็บเซิร์ฟเวอร์จะส่งการตอบกลับ HTTP ที่มีอินสแตนซ์ของเอกสารที่ระบุเป็นทรัพยากร
documents
JSON ที่แสดงผลประกอบด้วยเนื้อหาเอกสาร การจัดรูปแบบ และฟีเจอร์อื่นๆ - แอปจะแยกวิเคราะห์ JSON เพื่อให้ผู้ใช้กำหนดเนื้อหาหรือรูปแบบที่ต้องการอัปเดต
- แอปเรียกใช้เมธอด
documents.batchUpdate
เพื่อดำเนินการกับชุดคำขอแก้ไขเพื่ออัปเดตเอกสารอย่างมีชั้นเชิง - เว็บเซิร์ฟเวอร์จะส่งการตอบกลับ HTTP เมธอด
documents.batchUpdate
บางเมธอดจะระบุเนื้อหาการตอบกลับพร้อมข้อมูลเกี่ยวกับคำขอที่ใช้ ขณะที่เมธอดอื่นๆ จะแสดงการตอบกลับที่ว่างเปล่า
แผนภาพนี้ไม่พิจารณาเวิร์กโฟลว์ที่ผู้ทำงานร่วมกันคนอื่นๆ ทำการอัปเดตพร้อมกันในเอกสารเดียวกัน ดูข้อมูลเพิ่มเติมได้ที่ส่วนแนวทางปฏิบัติแนะนำในหัวข้อวางแผนสำหรับการทำงานร่วมกัน
หัวข้อที่เกี่ยวข้อง
- โครงสร้างของเอกสารใน Google เอกสาร
- คําขอและการตอบกลับ
- กฎและลักษณะการทำงานของการแก้ไขโครงสร้าง
- แนวทางปฏิบัติแนะนำเพื่อผลลัพธ์ที่ดีที่สุด