เอกสาร

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

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