เอกสาร

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

เมธอด API

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

• ใช้เมธอด 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 ไดรฟ์

ระบบจะจัดเก็บไฟล์ใน Docs ไว้ใน Google ไดรฟ์ ซึ่งเป็นบริการพื้นที่เก็บข้อมูลบนระบบคลาวด์ของเรา แม้ว่า Docs API จะมีเมธอดแบบสแตนด์อโลนของตัวเอง แต่ในหลายๆ ครั้งคุณก็จำเป็นต้องใช้เมธอด Google Drive API เพื่อโต้ตอบกับไฟล์ใน Docs ของผู้ใช้ด้วย เช่น หากต้องการคัดลอกไฟล์ใน Docs ให้ใช้ เมธอด files.copy ของ Drive API ดูข้อมูลเพิ่มเติมได้ที่ คัดลอก เอกสารที่มีอยู่

โดยค่าเริ่มต้น เมื่อใช้ Docs API ระบบจะบันทึกเอกสารใหม่ลงในโฟลเดอร์รากของผู้ใช้ในไดรฟ์ นอกจากนี้ยังมีตัวเลือกในการบันทึกไฟล์ลงในโฟลเดอร์ในไดรฟ์ด้วย ดูข้อมูลเพิ่มเติมได้ที่ทำงานกับ โฟลเดอร์ใน Google ไดรฟ์

ทำงานกับไฟล์ใน Docs

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

ประเภท MIME ของเอกสารจะระบุประเภทและรูปแบบข้อมูล รูปแบบประเภท MIME สำหรับ Docs คือ application/vnd.google-apps.document ดูรายการ ประเภท MIME ได้ที่ประเภท MIME ที่ Google Workspace และ Google ไดรฟ์รองรับ

หากต้องการค้นหาตามประเภท MIME สำหรับไฟล์ใน Docs ภายในไดรฟ์ของฉันเท่านั้น ให้ต่อท้ายตัวกรองสตริงการค้นหาต่อไปนี้

q: mimeType = 'application/vnd.google-apps.document'

ดูข้อมูลเพิ่มเติมเกี่ยวกับตัวกรองสตริงการค้นหาได้ที่ ค้นหาไฟล์และ โฟลเดอร์

เมื่อทราบ documentId แล้ว ให้ใช้ documents.get เมธอดเพื่อ ดึงข้อมูลอินสแตนซ์ที่สมบูรณ์ของเอกสารที่ระบุ ดูข้อมูลเพิ่มเติมได้ที่ คำขอและการตอบกลับ

หากต้องการส่งออกเนื้อหาไบต์ของเอกสาร Google Workspace ให้ใช้เมธอดของไดรฟ์ files.export โดยระบุ documentId ของไฟล์ที่จะส่งออกและ ประเภท MIME ของการส่งออก ที่ถูกต้อง ดูข้อมูลเพิ่มเติมได้ที่ ส่งออกเนื้อหาเอกสาร Google Workspace

เปรียบเทียบเมธอด Get และ List

ตารางต่อไปนี้อธิบายความแตกต่างระหว่างเมธอดของไดรฟ์และ Docs รวมถึงข้อมูลที่แสดงผลสำหรับแต่ละเมธอด

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

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

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

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

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

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

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

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

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

หัวข้อที่เกี่ยวข้อง

• โครงสร้างของเอกสารใน Google เอกสาร
• คำขอและการตอบกลับ
• กฎและลักษณะการทำงานของการแก้ไขโครงสร้าง
• แนวทางปฏิบัติแนะนำเพื่อให้ได้ผลลัพธ์ที่ดีที่สุด