จัดการการดำเนินการที่ใช้เวลานาน

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

Google Drive API จะแสดงผล LRO ทุกครั้งที่คุณเรียกใช้เมธอด download ในทรัพยากร files เพื่อดาวน์โหลดเนื้อหาของไฟล์ ผ่าน Drive API หรือไลบรารีของ ไคลเอ็นต์

เมธอดจะแสดงผลทรัพยากร operations ให้ ไคลเอ็นต์ คุณสามารถใช้ทรัพยากร operations เพื่อดึงข้อมูล สถานะของเมธอด API แบบไม่พร้อมกันได้โดยการสำรวจการดำเนินการผ่านเมธอด get LRO ใน Drive API เป็นไปตาม รูปแบบการออกแบบ LRO ของ Google Cloud

ดูข้อมูลเพิ่มเติมได้ที่ การดำเนินการที่ใช้เวลานาน

ภาพรวมของกระบวนการ

แผนผังต่อไปนี้แสดงขั้นตอนระดับสูงของวิธีการทำงานของเมธอด file.download

1. เรียกใช้ files.download: เมื่อแอปเรียกใช้เมธอด download แอปจะ เปิดใช้คำขอการดาวน์โหลด Drive API สำหรับไฟล์ ดูข้อมูลเพิ่มเติมได้ที่ ดาวน์โหลดไฟล์

2. ขอสิทธิ์: คำขอจะส่งข้อมูลเข้าสู่ระบบการตรวจสอบสิทธิ์ไปยัง Drive API หากแอปของคุณต้องเรียกใช้ Drive API โดยใช้การตรวจสอบสิทธิ์ของผู้ใช้ที่ยังไม่ได้รับอนุญาต ระบบจะแจ้งให้ผู้ใช้ลงชื่อเข้าใช้ นอกจากนี้ แอปของคุณยังขอสิทธิ์เข้าถึงด้วย ขอบเขตที่คุณระบุ เมื่อตั้งค่าการตรวจสอบสิทธิ์

3. เริ่มดาวน์โหลด: ระบบจะส่งคำขอ Drive API เพื่อเริ่มดาวน์โหลดไฟล์ คำขออาจส่งไปยัง Google Vids หรือเนื้อหาอื่นๆ ของ Google Workspace

4. เริ่ม LRO: การดำเนินการที่ใช้เวลานานจะเริ่มขึ้นและจัดการกระบวนการดาวน์โหลด

5. แสดงผลการดำเนินการที่รอดำเนินการ: Drive API จะแสดงผลการดำเนินการที่รอดำเนินการซึ่งมีข้อมูลเกี่ยวกับผู้ใช้ที่ส่งคำขอและ ฟิลด์ข้อมูลเมตาของไฟล์หลายรายการ

6. สถานะเริ่มต้นที่รอดำเนินการ: แอปของคุณจะได้รับการดำเนินการที่รอดำเนินการพร้อมกับสถานะเริ่มต้นที่รอดำเนินการของ done=null ซึ่งหมายความว่าไฟล์ยังไม่พร้อมสำหรับการดาวน์โหลดและสถานะการดำเนินการรอดำเนินการอยู่

7. เรียกใช้ operations.get และยืนยันผลลัพธ์: แอปของคุณจะเรียกใช้ get ตาม ช่วงเวลาที่แนะนำเพื่อสำรวจผลการดำเนินการและรับสถานะล่าสุด ของการดำเนินการที่ใช้เวลานาน หากระบบแสดงผลสถานะที่รอดำเนินการของ done=false แอปของคุณจะต้องสำรวจต่อไปจนกว่าการดำเนินการจะแสดงผลสถานะเสร็จสมบูรณ์ (done=true) สำหรับไฟล์ขนาดใหญ่ คุณอาจต้องสำรวจหลายครั้ง ดูข้อมูลเพิ่มเติมได้ที่ ดูรายละเอียดเกี่ยวกับการดำเนินการที่ใช้เวลานาน

8. ตรวจสอบสถานะที่รอดำเนินการ: หากระบบแสดงผลสถานะที่รอดำเนินการของ done=true จาก LRO หมายความว่าไฟล์พร้อมสำหรับการดาวน์โหลดและสถานะการดำเนินการเสร็จสมบูรณ์แล้ว

9. แสดงผลการดำเนินการที่เสร็จสมบูรณ์พร้อม URI การดาวน์โหลด: เมื่อ LRO เสร็จสิ้น Drive API จะแสดงผล URI การดาวน์โหลดและผู้ใช้จะใช้ไฟล์ได้แล้ว

ดาวน์โหลดไฟล์

หากต้องการดาวน์โหลดเนื้อหาภายใต้การดำเนินการที่ใช้เวลานาน ให้ใช้เมธอด download ในทรัพยากร files เมธอดนี้ใช้พารามิเตอร์ file_id, mime_type และ revision_id ดังนี้

• ต้องระบุ พารามิเตอร์เส้นทาง file_id คือรหัสของไฟล์ที่จะดาวน์โหลด

• ไม่บังคับ พารามิเตอร์การค้นหา mime_type หมายถึงประเภท MIME ที่เมธอดควรใช้ โดยจะใช้ได้เฉพาะเมื่อดาวน์โหลดเนื้อหาสื่อที่ไม่ใช่ Blob (เช่น เอกสาร Google Workspace) ดูรายการประเภท MIME ที่รองรับทั้งหมดได้ที่ ประเภท MIME สำหรับการส่งออกเอกสาร Google Workspace

  หากไม่ได้ตั้งค่าประเภท MIME ระบบจะดาวน์โหลดเอกสาร Google Workspace ด้วยประเภท MIME เริ่มต้น ดูข้อมูลเพิ่มเติมได้ที่ ประเภท MIME เริ่มต้น

• ไม่บังคับ พารามิเตอร์การค้นหา revision_id คือรหัสการแก้ไขของไฟล์ที่จะดาวน์โหลด โดยจะใช้ได้เฉพาะเมื่อดาวน์โหลดไฟล์ Blob, Google เอกสาร และ Google ชีต แสดงผลรหัสข้อผิดพลาด INVALID_ARGUMENT เมื่อดาวน์โหลดการแก้ไขที่เฉพาะเจาะจงในไฟล์ที่ไม่รองรับ

เมธอด download เป็นวิธีเดียวในการดาวน์โหลดไฟล์ Vids ในรูปแบบ MP4 และโดยทั่วไปเหมาะที่สุดสำหรับการดาวน์โหลดไฟล์วิดีโอส่วนใหญ่ หากคุณพยายามส่งออกไฟล์ Google Vids คุณจะได้รับข้อผิดพลาด fileNotExportable

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

ทั้งคำขอไปยังเมธอด download ที่เริ่ม LRO และคำขอเพื่อดึงข้อมูล URI การดาวน์โหลดขั้นสุดท้ายควรใช้คีย์ทรัพยากร ดูข้อมูลเพิ่มเติมได้ที่ เข้าถึงไฟล์ในไดรฟ์ที่แชร์ผ่านลิงก์โดยใช้คีย์ทรัพยากร

โปรโตคอลคำขอจะแสดงที่นี่

POST https://www.googleapis.com/drive/v3/files/{FILE_ID}/download

แทนที่ FILE_ID ด้วย fileId ของไฟล์ที่ต้องการ ดาวน์โหลด

ประเภท MIME เริ่มต้น

หากไม่ได้ตั้งค่าประเภท MIME เมื่อดาวน์โหลดเนื้อหาที่ไม่ใช่ Blob ระบบจะกำหนดประเภท MIME เริ่มต้นต่อไปนี้

ดาวน์โหลดคำตอบ

เมื่อเรียกใช้เมธอด download เนื้อหาการตอบกลับ จะประกอบด้วยทรัพยากร ที่แสดงถึงการดำเนินการที่ใช้เวลานาน โดยปกติแล้วเมธอดจะแสดงผลลิงก์เพื่อดาวน์โหลดเนื้อหาของไฟล์

{
  "done": true,
  "metadata": {
    "@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileMetadata",
    "resourceKey": "RESOURCE_KEY"
  },
  "name": "NAME",
  "response": {
    "@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileResponse",
    "downloadUri": "DOWNLOAD_URI",
    "partialDownloadAllowed": false
  }
}

เอาต์พุตนี้มีค่าต่อไปนี้

• RESOURCE_KEY: คีย์ทรัพยากรช่วยปกป้องไฟล์ของคุณจากการเข้าถึง โดยไม่ได้รับอนุญาต ดูข้อมูลเพิ่มเติมได้ที่เข้าถึงไฟล์ในไดรฟ์ที่แชร์ผ่านลิงก์โดยใช้คีย์ทรัพยากร

• NAME: ชื่อที่เซิร์ฟเวอร์กำหนด

• DOWNLOAD_URI: URI การดาวน์โหลดขั้นสุดท้ายสำหรับไฟล์

โปรดทราบว่าฟิลด์ partialDownloadAllowed จะระบุว่าอนุญาตให้ดาวน์โหลดบางส่วนหรือไม่ และจะเป็น true เมื่อดาวน์โหลดเนื้อหาไฟล์ Blob

ดูรายละเอียดเกี่ยวกับการดำเนินการที่ใช้เวลานาน

การดำเนินการที่ใช้เวลานานคือการเรียกใช้เมธอดที่อาจใช้เวลาพอสมควรจึงจะเสร็จสมบูรณ์ โดยปกติแล้ว ระบบจะแสดงผลการดำเนินการดาวน์โหลดที่สร้างขึ้นใหม่ในสถานะรอดำเนินการ (done=null) ในตอนแรก โดยเฉพาะอย่างยิ่งสำหรับไฟล์ Vids

คุณสามารถใช้ทรัพยากร operations ที่ Drive API มีให้เพื่อตรวจสอบสถานะของ LRO ที่กำลังประมวลผลโดย ใส่ชื่อที่ไม่ซ้ำกันที่เซิร์ฟเวอร์กำหนด

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

สำรวจการดำเนินการที่ใช้เวลานาน

หากต้องการสำรวจ LRO ที่พร้อมใช้งาน ให้เรียกใช้เมธอด get ซ้ำๆ จนกว่าการดำเนินการจะเสร็จสิ้น ใช้ Exponential Backoff ระหว่างคำขอสำรวจแต่ละรายการ เช่น 10 วินาที

LRO จะยังคงพร้อมใช้งานเป็นเวลาอย่างน้อย 12 ชั่วโมง แต่ในบางกรณีอาจใช้งานได้นานกว่านั้น ระยะเวลานี้อาจมีการเปลี่ยนแปลงและอาจแตกต่างกันไปตามประเภทไฟล์ เมื่อทรัพยากรหมดอายุ คุณจะต้องส่งคำขอเมธอด download ใหม่

คำขอทั้งหมดไปยัง get ควรใช้คีย์ทรัพยากร ดูข้อมูลเพิ่มเติมได้ที่ เข้าถึงไฟล์ในไดรฟ์ที่แชร์ผ่านลิงก์โดยใช้คีย์ทรัพยากร

โปรโตคอลคำขอจะแสดงที่นี่

operations.get(name='NAME');

curl -i -H \
      'Authorization: Bearer $(gcloud auth print-access-token)" \
      'https://googleapis.com/drive/v3/operations/NAME?alt=json'

โปรดทราบว่าระบบจะแสดงผล name ในการตอบกลับคำขอ download เท่านั้น ไม่มีวิธีอื่นในการดึงข้อมูลดังกล่าวเนื่องจาก Drive API ไม่รองรับเมธอด list หากค่า name สูญหาย คุณต้องสร้างการตอบกลับใหม่โดยเรียกใช้คำขอเมธอด download อีกครั้ง

การตอบกลับจากคำขอ get จะประกอบด้วยทรัพยากรที่แสดงถึงการดำเนินการที่ใช้เวลานาน ดูข้อมูลเพิ่มเติมได้ที่ดาวน์โหลด คำตอบ

เมื่อการตอบกลับมีสถานะเสร็จสมบูรณ์ (done=true) หมายความว่าการดำเนินการที่ใช้เวลานานเสร็จสิ้นแล้ว

ดาวน์โหลดการแก้ไข

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

หากต้องการดาวน์โหลดเนื้อหาการแก้ไขของไฟล์ Blob คุณต้องเรียกใช้เมธอด get ในทรัพยากร revisions ด้วยรหัสของไฟล์ที่จะ ดาวน์โหลด รหัสของการแก้ไข และพารามิเตอร์alt ระบบ พารามิเตอร์ alt=media จะบอกเซิร์ฟเวอร์ว่ามีการขอการดาวน์โหลดเนื้อหาเป็นรูปแบบการตอบกลับทางเลือก

พารามิเตอร์ระบบ alt ใช้ได้กับ Google REST API ทั้งหมด หากคุณใช้ไลบรารีของไคลเอ็นต์สำหรับ Drive API คุณไม่จำเป็นต้องตั้งค่าพารามิเตอร์นี้อย่างชัดเจน

คุณไม่สามารถดาวน์โหลดการแก้ไขสำหรับ Google เอกสาร, ชีต, สไลด์ และ Vids โดยใช้เมธอด get กับพารามิเตอร์ alt=media ไม่เช่นนั้นระบบจะสร้างข้อผิดพลาด fileNotDownloadable

โปรโตคอลคำขอจะแสดงที่นี่

GET https://www.googleapis.com/drive/v3/files/{FILE_ID}/revisions/{REVISION_ID}?alt=media

แทนที่ค่าต่อไปนี้

• FILE_ID: fileId ของไฟล์ที่ต้องการ ดาวน์โหลด
• REVISION_ID: revisionId ของการแก้ไขที่ต้องการดาวน์โหลด

การแก้ไขของ Google เอกสาร, วาดเขียน และสไลด์จะเพิ่มหมายเลขการแก้ไขโดยอัตโนมัติ อย่างไรก็ตาม ชุดตัวเลขอาจมีช่องว่างหากมีการลบการแก้ไข ดังนั้นคุณจึงไม่ควรใช้หมายเลขลำดับเพื่อดึงข้อมูลการแก้ไข

แก้ปัญหา LRO

เมื่อ LRO ล้มเหลว การตอบกลับจะมีรหัสข้อผิดพลาด Canonical ของ Google Cloud code

ตารางต่อไปนี้แสดงรหัสข้อผิดพลาดแต่ละรายการ รหัสสถานะ HTTP ที่แมป คำอธิบาย และคำแนะนำเกี่ยวกับวิธีจัดการรหัสข้อผิดพลาด สำหรับข้อผิดพลาดหลายรายการ การดำเนินการที่แนะนำคือลองส่งคำขออีกครั้งโดยใช้ Exponential Backoff

ดูข้อมูลเพิ่มเติมเกี่ยวกับรูปแบบข้อผิดพลาดนี้และวิธีใช้งานได้ในคู่มือ การออกแบบ API

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

• ดาวน์โหลดและส่งออกไฟล์