เอกสาร

คู่มือนี้จะแนะนำแนวคิดต่างๆ เช่น เมธอดหลักที่ประกอบกันเป็น Google เอกสาร API, วิธีเข้าถึงเอกสาร และเวิร์กโฟลว์เมื่อสร้างเอกสาร

เมธอดของ API

ทรัพยากร documents มีวิธีการที่คุณใช้เรียกใช้ Docs API วิธีการต่อไปนี้ช่วยให้คุณสร้าง อ่าน และอัปเดตเอกสารใน Google เอกสารได้

  • ใช้เมธอด 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 เวิร์กโฟลว์ในการสร้างและป้อนข้อมูลในเอกสารใหม่

ในรูปที่ 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 บางรายการจะแสดงข้อมูลเกี่ยวกับคำขอที่ใช้ในเนื้อหาของคำตอบ ขณะที่เมธอดอื่นๆ จะแสดงคำตอบว่าง

แผนภาพนี้ไม่คำนึงถึงเวิร์กโฟลว์ที่มีการอัปเดตพร้อมกันโดยผู้ทำงานร่วมกันคนอื่นๆ ในเอกสารเดียวกัน ดูข้อมูลเพิ่มเติมได้ที่ส่วนแนวทางปฏิบัติแนะนำวางแผนเพื่อการทำงานร่วมกัน