เอกสาร

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

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

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