คู่มือนี้จะแนะนำแนวคิดต่างๆ เช่น เมธอดหลักที่รวมอยู่ใน Google เอกสาร API วิธีเข้าถึงเอกสาร และเวิร์กโฟลว์เมื่อสร้างเอกสาร
เมธอด API
ทรัพยากร documents
มีวิธีที่คุณใช้ในการเรียกใช้ Docs API คุณสามารถใช้เมธอดต่อไปนี้ในการสร้าง อ่าน และอัปเดตเอกสารใน Google เอกสาร
- ใช้เมธอด
documents.create
เพื่อสร้างเอกสาร - ใช้เมธอด
documents.get
เพื่อเรียกเนื้อหาของเอกสารที่ระบุ - ใช้เมธอด
documents.batchUpdate
เพื่อดำเนินการกับชุดการอัปเดตอย่างอะตอมในเอกสารที่ระบุ
เมธอด documents.get
และ documents.batchUpdate
ต้องมี documentId
เป็นพารามิเตอร์เพื่อระบุเอกสารเป้าหมาย เมธอด documents.create
จะแสดงผลอินสแตนซ์ของเอกสารที่สร้างขึ้น ซึ่งคุณจะอ่าน documentId
ได้ สำหรับข้อมูลเพิ่มเติมเกี่ยวกับคำขอ 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 เพื่อโต้ตอบกับไฟล์ Google เอกสารของผู้ใช้ด้วย เช่น หากต้องการคัดลอกไฟล์เอกสาร ให้ใช้เมธอด 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 เอกสาร
- คำขอและการตอบกลับ
- กฎและลักษณะการทำงานของการแก้ไขโครงสร้าง
- แนวทางปฏิบัติแนะนำเพื่อผลลัพธ์ที่ดีที่สุด