เอกสาร

คู่มือนี้จะแนะนำแนวคิดต่างๆ เช่น วิธีหลักที่ประกอบกันเป็น Google เอกสาร 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 ไดรฟ์ 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 และ Docs รวมถึงข้อมูลที่ส่งคืนพร้อมกับแต่ละเมธอด

ผู้ประกอบธุรกิจ คำอธิบาย การใช้งาน
drive.files.get รับข้อมูลเมตาของไฟล์ตามรหัส แสดงผลอินสแตนซ์ของทรัพยากร files รับข้อมูลเมตาของไฟล์ที่เฉพาะเจาะจง
drive.files.list รับไฟล์ของผู้ใช้ แสดงรายการไฟล์ ดูรายการไฟล์ของผู้ใช้เมื่อไม่แน่ใจว่าต้องแก้ไขไฟล์ใด
docs.documents.get รับเอกสารเวอร์ชันล่าสุดที่ระบุ รวมถึงการจัดรูปแบบและข้อความทั้งหมด แสดงผลอินสแตนซ์ของทรัพยากร documents รับเอกสารสำหรับรหัสเอกสารที่เฉพาะเจาะจง

เวิร์กโฟลว์การสร้างเอกสาร

การสร้างและป้อนข้อมูลในเอกสารใหม่เป็นเรื่องง่าย เนื่องจากไม่มีเนื้อหาที่มีอยู่ให้กังวลและไม่มีผู้ทำงานร่วมกันที่สามารถเปลี่ยนสถานะเอกสารได้ ในเชิงแนวคิด กระบวนการนี้จะทำงานตามที่แสดงในลำดับไดอะแกรมต่อไปนี้

เวิร์กโฟลว์ในการสร้างและ ป้อนข้อมูลในเอกสารใหม่
รูปที่ 1 เวิร์กโฟลว์ในการสร้างและป้อนข้อมูลในเอกสารใหม่

ในรูปที่ 1 ผู้ใช้ที่โต้ตอบกับทรัพยากร documents จะมีขั้นตอนการไหลของข้อมูลดังนี้

  1. แอปเรียกใช้เมธอด documents.create ในเว็บเซิร์ฟเวอร์
  2. เว็บเซิร์ฟเวอร์จะส่งการตอบกลับ HTTP ที่มีอินสแตนซ์ของเอกสารที่สร้างเป็นทรัพยากร documents
  3. ไม่บังคับ แอปจะเรียกใช้เมธอด documents.batchUpdate เพื่อดำเนินการชุดคำขอแก้ไขแบบอะตอมมิกเพื่อป้อนข้อมูลลงในเอกสาร
  4. เว็บเซิร์ฟเวอร์ส่งการตอบกลับ HTTP documents.batchUpdate บางเมธอด จะแสดงเนื้อหาการตอบกลับพร้อมข้อมูลเกี่ยวกับคำขอที่ใช้ ในขณะที่ เมธอดอื่นๆ จะแสดงการตอบกลับที่ว่างเปล่า

เวิร์กโฟลว์การอัปเดตเอกสาร

การอัปเดตเอกสารที่มีอยู่จะซับซ้อนกว่า ก่อนที่จะทำการเรียกเพื่ออัปเดตเอกสารได้อย่างมีประสิทธิภาพ คุณต้องทราบสถานะปัจจุบันของเอกสาร ซึ่งได้แก่ องค์ประกอบที่ประกอบกันเป็นเอกสาร เนื้อหาในองค์ประกอบเหล่านั้น และลำดับขององค์ประกอบภายใน เอกสาร แผนภาพลำดับต่อไปนี้แสดงวิธีการทำงาน

เวิร์กโฟลว์ในการอัปเดตเอกสาร
รูปที่ 2 เวิร์กโฟลว์ในการอัปเดตเอกสาร

ในรูปที่ 2 ผู้ใช้ที่โต้ตอบกับdocumentsทรัพยากรจะมีขั้นตอนการไหลของข้อมูลดังนี้

  1. แอปจะเรียกใช้เมธอด documents.get ในเว็บเซิร์ฟเวอร์พร้อมด้วย documentId ของไฟล์ที่จะค้นหา
  2. เว็บเซิร์ฟเวอร์จะส่งการตอบกลับ HTTP ที่มีอินสแตนซ์ของเอกสารที่ระบุเป็นdocumentsทรัพยากร JSON ที่ส่งกลับมาจะมี เนื้อหา การจัดรูปแบบ และฟีเจอร์อื่นๆ ของเอกสาร
  3. แอปจะแยกวิเคราะห์ JSON เพื่อให้ผู้ใช้ทราบว่าควร อัปเดตเนื้อหาหรือรูปแบบใด
  4. แอปเรียกใช้เมธอด documents.batchUpdate เพื่อดำเนินการชุดคำขอแก้ไขเพื่ออัปเดตเอกสารแบบอะตอม
  5. เว็บเซิร์ฟเวอร์ส่งการตอบกลับ HTTP documents.batchUpdate บางเมธอด จะแสดงเนื้อหาการตอบกลับพร้อมข้อมูลเกี่ยวกับคำขอที่ใช้ ในขณะที่ เมธอดอื่นๆ จะแสดงการตอบกลับที่ว่างเปล่า

แผนภาพนี้ไม่ได้พิจารณาลำดับงานที่ผู้ทำงานร่วมกันรายอื่นอัปเดตเอกสารเดียวกันพร้อมกัน ดูข้อมูลเพิ่มเติมได้ที่ส่วนแนวทางปฏิบัติแนะนำวางแผนเพื่อ การทำงานร่วมกัน