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

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

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

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

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

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

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

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

POST https://www.googleapis.com/drive/v3/files/{FILE_ID}/download

แทนที่ FILE_ID ด้วย fileId ของไฟล์ที่ต้องการ ดาวน์โหลด

ประเภท MIME เริ่มต้น

หากไม่ได้ตั้งค่าประเภท MIME เมื่อดาวน์โหลดเนื้อหาที่ไม่ใช่ Blob ระบบจะกำหนดประเภท MIME เริ่มต้นต่อไปนี้

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

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

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

• RESOURCE_KEY: คีย์ทรัพยากรช่วยปกป้องไฟล์ของคุณจากการเข้าถึงโดยไม่ตั้งใจ ดูข้อมูลเพิ่มเติมได้ที่เข้าถึงไฟล์ในไดรฟ์ที่แชร์ลิงก์โดยใช้คีย์ทรัพยากร

• NAME: ชื่อที่เซิร์ฟเวอร์กำหนด

• DOWNLOAD_URI: URI การดาวน์โหลดสุดท้ายสำหรับไฟล์

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

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

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

หัวข้อที่เกี่ยวข้อง

• ดาวน์โหลดและส่งออกไฟล์