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

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

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

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

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

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

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

ขั้นตอนระดับสูงสำหรับเมธอด file.download
รูปที่ 1 ขั้นตอนระดับสูงสำหรับเมธอด 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 เริ่มต้นต่อไปนี้

ประเภทเอกสาร รูปแบบ ประเภท MIME นามสกุลไฟล์
Google Apps Script JSON application/vnd.google-apps.script+json .json
Google เอกสาร Microsoft Word application/vnd.openxmlformats-officedocument.wordprocessingml.document .docx
Google วาดเขียน PNG image/png .png
Google ฟอร์ม ZIP application/zip .zip
Google ชีต Microsoft Excel application/vnd.openxmlformats-officedocument.spreadsheetml.sheet .xlsx
Google Sites ข้อความธรรมดา text/raw .txt
Google สไลด์ Microsoft PowerPoint application/vnd.openxmlformats-officedocument.presentationml.presentation .pptx
Google Vids MP4 video/mp4 .mp4
Jamboard PDF application/pdf .pdf

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

เมื่อเรียกใช้เมธอด 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
  }
}

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

โปรดทราบว่าฟิลด์ 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');

แทนที่ NAME ด้วยชื่อที่เซิร์ฟเวอร์กำหนดของการดำเนินการตามที่ แสดงในการตอบกลับคำขอเมธอด download

curl

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

แทนที่ NAME ด้วยชื่อที่เซิร์ฟเวอร์กำหนดของการดำเนินการตามที่ แสดงในการตอบกลับคำขอเมธอด download

คำสั่งนี้ใช้เส้นทาง /drive/v3/operations/NAME

โปรดทราบว่าระบบจะแสดงผล 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

รหัส ค่าแจกแจง รหัสสถานะ HTTP คำอธิบาย การดำเนินการที่แนะนำ
1 CANCELLED 499 Client Closed Request การดำเนินการถูกยกเลิก โดยปกติแล้วจะเป็นผู้เรียก เรียกใช้การดำเนินการอีกครั้ง
2 UNKNOWN 500 Internal Server Error ข้อผิดพลาดนี้อาจแสดงผลเมื่อค่า Status ที่ได้รับจากพื้นที่ที่อยู่หนึ่งเป็นของพื้นที่ข้อผิดพลาดที่ไม่รู้จักในพื้นที่ที่อยู่นี้ หากข้อผิดพลาด API แสดงข้อมูลไม่เพียงพอ ระบบอาจแปลงข้อผิดพลาดเป็นข้อผิดพลาดนี้ ลองอีกครั้งโดยใช้ Exponential Backoff
3 INVALID_ARGUMENT 400 Bad Request ไคลเอ็นต์ระบุอาร์กิวเมนต์ไม่ถูกต้อง ข้อผิดพลาดนี้แตกต่างจาก FAILED_PRECONDITION INVALID_ARGUMENT บ่งชี้ถึงอาร์กิวเมนต์ที่มีปัญหาไม่ว่าสถานะของระบบจะเป็นอย่างไร เช่น ชื่อไฟล์ที่จัดรูปแบบไม่ถูกต้อง อย่าลองอีกครั้งโดยไม่แก้ไขปัญหา
4 DEADLINE_EXCEEDED 504 Gateway Timeout กำหนดเวลาหมดอายุก่อนที่การดำเนินการจะเสร็จสมบูรณ์ สำหรับการดำเนินการที่เปลี่ยนสถานะของระบบ ข้อผิดพลาดนี้อาจแสดงผลแม้ว่าการดำเนินการจะเสร็จสมบูรณ์แล้วก็ตาม ตัวอย่างเช่น การตอบกลับที่สำเร็จจากเซิร์ฟเวอร์อาจล่าช้าจนกำหนดเวลาหมดอายุ ลองอีกครั้งโดยใช้ Exponential Backoff
5 NOT_FOUND 404 Not Found ไม่พบเอนทิตีที่ขอ เช่น ทรัพยากร FHIR อย่าลองอีกครั้งโดยไม่แก้ไขปัญหา
6 ALREADY_EXISTS 409 Conflict เอนทิตีที่ไคลเอ็นต์พยายามสร้าง เช่น อินสแตนซ์ DICOM มีอยู่แล้ว อย่าลองอีกครั้งโดยไม่แก้ไขปัญหา
7 PERMISSION_DENIED 403 Forbidden ผู้เรียกไม่มีสิทธิ์ดำเนินการที่ระบุ รหัสข้อผิดพลาดนี้ไม่ได้หมายความว่าคำขอถูกต้อง เอนทิตีที่ขอมีอยู่ หรือเป็นไปตามเงื่อนไขเบื้องต้นอื่นๆ อย่าลองอีกครั้งโดยไม่แก้ไขปัญหา
8 RESOURCE_EXHAUSTED 429 Too Many Requests ทรัพยากรบางอย่างหมดลง เช่น โควต้าต่อโปรเจ็กต์ ลองอีกครั้งโดยใช้ Exponential Backoff โควต้าอาจพร้อมใช้งานเมื่อเวลาผ่านไป
9 FAILED_PRECONDITION 400 Bad Request การดำเนินการถูกปฏิเสธเนื่องจากระบบไม่อยู่ในสถานะที่จำเป็นสำหรับการดำเนินการ ตัวอย่างเช่น ไดเรกทอรีที่จะลบไม่ใช่ไดเรกทอรีว่าง หรือมีการใช้การดำเนินการ rmdir กับรายการที่ไม่ใช่ไดเรกทอรี อย่าลองอีกครั้งโดยไม่แก้ไขปัญหา
10 ABORTED 409 Conflict การดำเนินการถูกยกเลิก โดยปกติแล้วเนื่องจากปัญหาการทำงานพร้อมกัน เช่น การตรวจสอบลำดับล้มเหลวหรือการยกเลิกธุรกรรม ลองอีกครั้งโดยใช้ Exponential Backoff
11 OUT_OF_RANGE 400 Bad Request มีการพยายามดำเนินการนอกช่วงที่ถูกต้อง เช่น การค้นหาหรือการอ่านเลยจุดสิ้นสุดของไฟล์ ข้อผิดพลาดนี้แตกต่างจาก INVALID_ARGUMENT ตรงที่บ่งชี้ถึงปัญหาที่อาจแก้ไขได้หากสถานะระบบมีการเปลี่ยนแปลง อย่าลองอีกครั้งโดยไม่แก้ไขปัญหา
12 UNIMPLEMENTED 501 Not Implemented การดำเนินการไม่ได้นำไปใช้หรือไม่ได้รองรับ/เปิดใช้ใน Drive API ไม่ต้องลองอีกครั้ง
13 INTERNAL 500 Internal Server Error ข้อผิดพลาดภายใน ข้อผิดพลาดนี้บ่งชี้ว่าระบบพบข้อผิดพลาดที่ไม่คาดคิดในการประมวลผลในระบบพื้นฐาน ลองอีกครั้งโดยใช้ Exponential Backoff
14 UNAVAILABLE 503 Service Unavailable Drive API ไม่พร้อมใช้งาน ซึ่งส่วนใหญ่แล้วเป็นสภาวะชั่วคราวที่แก้ไขได้โดยลองอีกครั้งโดยใช้ Exponential Backoff โปรดทราบว่าการลองดำเนินการที่ไม่ใช่ Idempotent อีกครั้งอาจไม่ปลอดภัยเสมอไป ลองอีกครั้งโดยใช้ Exponential Backoff
15 DATA_LOSS 500 Internal Server Error ข้อมูลสูญหายหรือเสียหายโดยกู้คืนไม่ได้ โปรดติดต่อผู้ดูแลระบบ ผู้ดูแลระบบอาจต้องติดต่อตัวแทนฝ่ายสนับสนุนหากข้อมูลรั่วไหลหรือเสียหาย
16 UNAUTHENTICATED 401 Unauthorized คำขอไม่มีข้อมูลเข้าสู่ระบบการตรวจสอบสิทธิ์ที่ถูกต้องสำหรับการดำเนินการ อย่าลองอีกครั้งโดยไม่แก้ไขปัญหา