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

การดำเนินการที่ทำงานต่อเนื่อง (LRO) คือเมธอด 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. ตรวจสอบสถานะรอดำเนินการ: หาก LRO แสดงสถานะรอดำเนินการของ done=true แสดงว่าไฟล์พร้อมให้ดาวน์โหลดและสถานะการดำเนินการเสร็จสมบูรณ์แล้ว

  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 เอกสารหรือชีตในตอนแรกจะแสดงการเปลี่ยนเส้นทาง คลิกลิงก์ใหม่เพื่อดาวน์โหลดไฟล์

ทั้งคำขอไปยังเมธอด 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 application/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 จะระบุว่ามีการอนุญาตให้ดาวน์โหลดบางส่วนหรือไม่ จริงเมื่อดาวน์โหลดเนื้อหาไฟล์ 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 พร้อมรหัสของไฟล์ที่จะดาวน์โหลด รหัสของการแก้ไข และพารามิเตอร์ URL alt=media พารามิเตอร์ URL alt=media บอกให้เซิร์ฟเวอร์ทราบว่ามีการขอดาวน์โหลดเนื้อหาในรูปแบบการตอบกลับทางเลือก

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

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

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

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

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

  • FILE_ID: fileId ของไฟล์ที่ต้องการดาวน์โหลด
  • REVISION_ID: revisionId ของเวอร์ชันที่คุณต้องการดาวน์โหลด

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

แก้ปัญหา LRO

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

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

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

รหัส ค่าแจกแจง คำอธิบาย การดำเนินการที่แนะนำ
1 CANCELLED การดำเนินการถูกยกเลิก โดยปกติแล้วผู้โทรจะเป็นผู้ยกเลิก เรียกใช้การดำเนินการอีกครั้ง
2 UNKNOWN ระบบอาจแสดงข้อผิดพลาดนี้เมื่อค่า Status ที่ได้รับจากสเปซที่อยู่อื่นเป็นของพื้นที่ข้อผิดพลาดที่ไม่รู้จักในสเปซที่อยู่นี้ หากข้อผิดพลาดของ API แสดงข้อมูลไม่เพียงพอ ระบบอาจแปลงข้อผิดพลาดดังกล่าวเป็นข้อผิดพลาดนี้ ลองอีกครั้งโดยใช้ Exponential Backoff
3 INVALID_ARGUMENT ไคลเอ็นต์ระบุอาร์กิวเมนต์ไม่ถูกต้อง ข้อผิดพลาดนี้แตกต่างจาก FAILED_PRECONDITION INVALID_ARGUMENT ระบุอาร์กิวเมนต์ที่มีปัญหา ไม่ว่าระบบจะอยู่ในสถานะใดก็ตาม เช่น ชื่อไฟล์ที่มีรูปแบบไม่ถูกต้อง อย่าลองอีกครั้งหากยังไม่ได้แก้ไขปัญหา
4 DEADLINE_EXCEEDED กำหนดเวลาหมดอายุก่อนที่การดำเนินการจะเสร็จสมบูรณ์ สําหรับการดำเนินการที่เปลี่ยนสถานะของระบบ ระบบอาจแสดงข้อผิดพลาดนี้แม้ว่าการดำเนินการจะเสร็จสมบูรณ์แล้วก็ตาม ตัวอย่างเช่น การตอบกลับที่สำเร็จจากเซิร์ฟเวอร์อาจล่าช้านานพอที่การตอบกลับจะหมดเวลา ลองอีกครั้งโดยใช้ Exponential Backoff
5 NOT_FOUND ไม่พบเอนทิตีที่ขอ เช่น ทรัพยากร FHIR อย่าลองอีกครั้งโดยไม่แก้ไขปัญหา
6 ALREADY_EXISTS มีเอนทิตีที่ไคลเอ็นต์พยายามสร้าง เช่น อินสแตนซ์ DICOM อยู่แล้ว อย่าลองอีกครั้งหากยังไม่ได้แก้ไขปัญหา
7 PERMISSION_DENIED ผู้โทรไม่มีสิทธิ์ดำเนินการที่ระบุ รหัสข้อผิดพลาดนี้ไม่ได้หมายความว่าคำขอถูกต้อง เอนทิตีที่ขอมีอยู่ หรือเป็นไปตามเงื่อนไขเบื้องต้นอื่นๆ อย่าลองอีกครั้งหากยังไม่ได้แก้ไขปัญหา
8 RESOURCE_EXHAUSTED ทรัพยากรบางอย่างหมดแล้ว เช่น โควต้าต่อโปรเจ็กต์ ลองอีกครั้งโดยใช้ Exponential Backoff โควต้าอาจกลับมาใช้งานได้เมื่อเวลาผ่านไป
9 FAILED_PRECONDITION ระบบปฏิเสธการดำเนินการเนื่องจากระบบไม่อยู่ในสถานะที่จําเป็นสําหรับการดําเนินการ เช่น ไดเรกทอรีที่จะลบไม่ได้ว่างเปล่า หรือมีการใช้การดำเนินการ rmdir กับรายการที่ไม่ใช่ไดเรกทอรี อย่าลองอีกครั้งโดยไม่แก้ไขปัญหา
10 ABORTED ระบบยกเลิกการดำเนินการ ซึ่งมักเกิดจากปัญหาการทำงานพร้อมกัน เช่น การตรวจสอบตัวจัดลำดับไม่สำเร็จหรือการยกเลิกธุรกรรม ลองอีกครั้งโดยใช้ Exponential Backoff
11 OUT_OF_RANGE พยายามดำเนินการเกินช่วงที่ถูกต้อง เช่น เลื่อนหาหรืออ่านเกินจุดสิ้นสุดไฟล์ ข้อผิดพลาดนี้บ่งบอกถึงปัญหาที่อาจแก้ไขได้หากสถานะของระบบมีการเปลี่ยนแปลง ซึ่งแตกต่างจาก INVALID_ARGUMENT อย่าลองอีกครั้งโดยไม่แก้ไขปัญหา
12 UNIMPLEMENTED การดำเนินการนี้ไม่มีการใช้งานหรือไม่รองรับ/เปิดใช้ในไดรฟ์ API ไม่ต้องลองใหม่
13 INTERNAL ข้อผิดพลาดภายใน ข้อความนี้บ่งบอกว่าระบบพบข้อผิดพลาดที่ไม่คาดคิดระหว่างการประมวลผลในระบบพื้นฐาน ลองอีกครั้งโดยใช้ Exponential Backoff
14 UNAVAILABLE Drive API ไม่พร้อมใช้งาน ปัญหานี้มักเป็นปัญหาชั่วคราว ซึ่งแก้ไขได้ด้วยการลองอีกครั้งโดยใช้ Exponential Backoff โปรดทราบว่าการลองดำเนินการที่ไม่ซ้ำกันอีกครั้งนั้นไม่ปลอดภัยเสมอไป ลองอีกครั้งโดยใช้ Exponential Backoff
15 DATA_LOSS ข้อมูลสูญหายโดยกู้คืนไม่ได้หรือข้อมูลเสียหาย โปรดติดต่อผู้ดูแลระบบ ผู้ดูแลระบบอาจต้องติดต่อตัวแทนฝ่ายสนับสนุนหากข้อมูลสูญหายหรือเสียหาย
16 UNAUTHENTICATED คำขอไม่มีข้อมูลเข้าสู่ระบบการตรวจสอบสิทธิ์ที่ถูกต้องสำหรับการดำเนินการ อย่าลองอีกครั้งหากยังไม่ได้แก้ไขปัญหา