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

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

Google ไดรฟ์ 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. Start LRO: การดำเนินการที่ใช้เวลานานจะเริ่มขึ้นและจัดการกระบวนการดาวน์โหลด

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

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

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

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

  9. ส่งคืนการดำเนินการที่เสร็จสมบูรณ์พร้อม URI การดาวน์โหลด: เมื่อ LRO เสร็จสมบูรณ์แล้ว ไดรฟ์ 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 การดาวน์โหลดสุดท้ายควรใช้คีย์ทรัพยากรทั้ง 2 รายการ ดูข้อมูลเพิ่มเติมได้ที่ เข้าถึงไฟล์ในไดรฟ์ที่แชร์ด้วยลิงก์โดยใช้คีย์ทรัพยากร

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

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 ข้อความดิบ ข้อความ/ดิบ .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 เอกสาร, ชีต, สไลด์ และ Vids โดยใช้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 การดำเนินการไม่ได้ใช้งานหรือไม่ได้รองรับ/เปิดใช้ใน Drive API ไม่ต้องลองใหม่
13 INTERNAL ข้อผิดพลาดภายใน ข้อความนี้บ่งบอกว่าเกิดข้อผิดพลาดที่ไม่คาดคิดในการประมวลผลในระบบพื้นฐาน ลองอีกครั้งโดยใช้ Exponential Backoff
14 UNAVAILABLE API ของไดรฟ์ไม่พร้อมใช้งาน โดยส่วนใหญ่แล้วเงื่อนไขนี้เป็นเงื่อนไขชั่วคราว ซึ่งแก้ไขได้โดยลองอีกครั้งโดยใช้ Exponential Backoff โปรดทราบว่าการลองดำเนินการที่ไม่ใช่ Idempotent อีกครั้งอาจไม่ปลอดภัยเสมอไป ลองอีกครั้งโดยใช้ Exponential Backoff
15 DATA_LOSS ข้อมูลสูญหายโดยกู้คืนไม่ได้หรือข้อมูลเสียหาย โปรดติดต่อผู้ดูแลระบบ ผู้ดูแลระบบอาจต้องติดต่อตัวแทนฝ่ายสนับสนุนหากข้อมูลสูญหายหรือเสียหาย
16 UNAUTHENTICATED คำขอไม่มีข้อมูลเข้าสู่ระบบการตรวจสอบสิทธิ์ที่ถูกต้องสำหรับการดำเนินการ อย่าลองอีกครั้งโดยไม่แก้ไขปัญหา