เอกสาร

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

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

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