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

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

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