เอกสาร

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

เมธอด API

ทรัพยากร documents มี ที่คุณใช้เพื่อเรียกใช้ 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 ไดรฟ์ API documentId จะตรงกับ id ในแหล่งข้อมูล files

จัดการเอกสารใน Google ไดรฟ์

ไฟล์เอกสารถูกเก็บไว้ใน Google ไดรฟ์ ซึ่งเป็นพื้นที่เก็บข้อมูลในระบบคลาวด์ของเรา service. แม้ว่า 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 ให้เนื้อหาการตอบกลับพร้อมข้อมูลเกี่ยวกับคำขอที่นำไปใช้ ในขณะที่ คนอื่นๆ แสดงคำตอบที่ว่างเปล่า

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