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

การดำเนินการที่ทำงานต่อเนื่อง (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 แอปพลิเคชัน/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() เท่านั้น คุณจะดึงข้อมูลด้วยวิธีอื่นไม่ได้ เนื่องจาก API ไดรฟ์ไม่รองรับเมธอด List() หากค่า name หายไป คุณต้องสร้างคำตอบใหม่โดยเรียกใช้คำขอเมธอด download() อีกครั้ง

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

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

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

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

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