Quản lý các hoạt động diễn ra trong thời gian dài

Thao tác chạy trong thời gian dài (LRO) là một phương thức API mất nhiều thời gian hơn để hoàn tất so với thời gian thích hợp cho một phản hồi API. Thông thường, bạn không nên giữ luồng gọi mở trong khi tác vụ chạy vì điều này mang lại trải nghiệm người dùng kém. Thay vào đó, bạn nên trả về một số loại lời hứa cho người dùng và cho phép họ kiểm tra lại sau.

API Google Drive trả về một LRO mỗi khi bạn gọi phương thức download() trên tài nguyên files để tải nội dung của một tệp xuống thông qua API Drive hoặc thư viện ứng dụng của API đó.

Phương thức này trả về tài nguyên operations cho ứng dụng khách. Bạn có thể sử dụng tài nguyên operations để truy xuất trạng thái của phương thức API một cách không đồng bộ bằng cách thăm dò hoạt động thông qua phương thức get(). LRO trong API Drive tuân thủ mẫu thiết kế LRO của Google Cloud.

Để biết thêm thông tin, hãy xem phần Thao tác chạy trong thời gian dài.

Tổng quan về quy trình

Sơ đồ sau đây cho thấy các bước cấp cao về cách hoạt động của phương thức file.download.

1. Gọi files.download: Khi ứng dụng gọi phương thức download(), ứng dụng sẽ khởi chạy yêu cầu tải xuống API Drive cho tệp. Để biết thêm thông tin, hãy xem phần Tải tệp xuống.

2. Yêu cầu cấp quyền: Yêu cầu này sẽ gửi thông tin xác thực đến API Drive. Nếu ứng dụng của bạn yêu cầu gọi API Drive bằng thông tin xác thực của người dùng chưa được cấp, thì ứng dụng sẽ nhắc người dùng đăng nhập. Ứng dụng của bạn cũng yêu cầu quyền truy cập với phạm vi mà bạn chỉ định khi thiết lập quy trình xác thực.

3. Bắt đầu tải xuống: Hệ thống sẽ tạo một yêu cầu API Drive để bắt đầu tải tệp xuống. Bạn có thể gửi yêu cầu này cho Google Vids hoặc một số nội dung khác trong Google Workspace.

4. Bắt đầu LRO: Một thao tác chạy trong thời gian dài bắt đầu và thao tác này sẽ quản lý quá trình tải xuống.

5. Trả về thao tác đang chờ xử lý: API Drive trả về một thao tác đang chờ xử lý chứa thông tin về người dùng đưa ra yêu cầu và một số trường siêu dữ liệu tệp.

6. Trạng thái chờ xử lý ban đầu: Ứng dụng của bạn sẽ nhận được thao tác đang chờ xử lý cùng với trạng thái chờ xử lý ban đầu là done=null. Điều này cho biết tệp chưa sẵn sàng để tải xuống và trạng thái thao tác đang chờ xử lý.

7. Gọi operations.get và xác minh kết quả: Ứng dụng của bạn gọi get() theo các khoảng thời gian được đề xuất để thăm dò kết quả của thao tác và nhận trạng thái mới nhất của một thao tác chạy trong thời gian dài. Nếu trạng thái đang chờ xử lý của done=false được trả về, thì ứng dụng của bạn phải tiếp tục thăm dò ý kiến cho đến khi thao tác trả về trạng thái hoàn tất (done=true). Đối với các tệp lớn, bạn có thể phải thăm dò ý kiến nhiều lần. Để biết thêm thông tin, hãy xem phần Nhận thông tin chi tiết về một thao tác chạy trong thời gian dài.

8. Kiểm tra trạng thái đang chờ xử lý: Nếu trạng thái đang chờ xử lý của done=true được trả về từ LRO, thì điều này cho biết tệp đã sẵn sàng để tải xuống và trạng thái thao tác đã hoàn tất.

9. Trả về thao tác đã hoàn tất bằng URI tải xuống: Sau khi LRO hoàn tất, API Drive sẽ trả về URI tải xuống và người dùng hiện có thể truy cập vào tệp.

Tải tệp xuống

Để tải nội dung xuống trong một thao tác chạy trong thời gian dài, hãy sử dụng phương thức download() trên tài nguyên files. Phương thức này lấy các thông số truy vấn của file_id, mime_type và revision_id:

• Bắt buộc. Tham số truy vấn file_id là mã nhận dạng của tệp cần tải xuống.

• Không bắt buộc. Tham số truy vấn mime_type biểu thị loại MIME mà phương thức sẽ sử dụng. Tính năng này chỉ hoạt động khi tải nội dung đa phương tiện không phải blob xuống (chẳng hạn như tài liệu Google Workspace). Để biết danh sách đầy đủ các loại MIME được hỗ trợ, hãy xem bài viết Xuất loại MIME cho tài liệu Google Workspace.

  Nếu bạn không đặt loại MIME, tài liệu Google Workspace sẽ được tải xuống bằng loại MIME mặc định. Để biết thêm thông tin, hãy xem phần Loại MIME mặc định.

• Không bắt buộc. Tham số truy vấn revision_id là mã sửa đổi của tệp cần tải xuống. Tính năng này chỉ dùng được khi tải tệp blob, Google Tài liệu và Google Trang tính xuống. Trả về mã lỗi INVALID_ARGUMENT khi tải một bản sửa đổi cụ thể xuống các tệp không được hỗ trợ.

Phương thức download() là cách duy nhất để tải tệp Vids xuống ở định dạng MP4 và thường phù hợp nhất để tải hầu hết tệp video xuống.

Các đường liên kết tải xuống được tạo cho Google Tài liệu hoặc Trang tính ban đầu sẽ trả về một lệnh chuyển hướng. Nhấp vào đường liên kết mới để tải tệp xuống.

Yêu cầu gửi đến phương thức download() bắt đầu LRO và yêu cầu tìm nạp URI tải xuống cuối cùng đều phải sử dụng khoá tài nguyên. Để biết thêm thông tin, hãy xem bài viết Truy cập vào tệp trên Drive được chia sẻ bằng đường liên kết bằng khoá tài nguyên.

Giao thức yêu cầu được hiển thị tại đây.

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

Thay thế FILE_ID bằng fileId của tệp bạn muốn tải xuống.

Loại MIME mặc định

Nếu bạn không đặt loại MIME khi tải nội dung không phải blob xuống, thì các loại MIME mặc định sau đây sẽ được chỉ định:

Tải câu trả lời xuống

Khi gọi phương thức download(), phần nội dung phản hồi bao gồm một tài nguyên đại diện cho một thao tác chạy trong thời gian dài. Phương thức này thường trả về một đường liên kết để tải nội dung tệp xuống.

{
  "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
  }
}

Kết quả này bao gồm các giá trị sau:

• RESOURCE_KEY: Khoá tài nguyên giúp bảo vệ tệp của bạn khỏi truy cập ngoài ý muốn. Để biết thêm thông tin, hãy xem bài viết Truy cập vào các tệp trên Drive được chia sẻ qua đường liên kết bằng khoá tài nguyên.

• NAME: Tên do máy chủ chỉ định.

• DOWNLOAD_URI: URI tải xuống cuối cùng cho tệp.

Xin lưu ý rằng trường partialDownloadAllowed cho biết liệu tải xuống một phần có được phép hay không. Đúng khi tải nội dung tệp blob xuống.

Xem thông tin chi tiết về một thao tác chạy trong thời gian dài

Các thao tác chạy trong thời gian dài là các lệnh gọi phương thức có thể mất nhiều thời gian để hoàn tất. Thông thường, các thao tác tải xuống mới tạo ban đầu sẽ được trả về ở trạng thái đang chờ xử lý (done=null), đặc biệt là đối với các tệp Vids.

Bạn có thể sử dụng tài nguyên operations mà API Drive cung cấp để kiểm tra trạng thái của LRO đang xử lý bằng cách thêm tên duy nhất do máy chủ chỉ định.

Phương thức get() nhận trạng thái mới nhất của một thao tác chạy trong thời gian dài một cách không đồng bộ. Ứng dụng có thể sử dụng phương thức này để thăm dò kết quả thao tác theo các khoảng thời gian mà dịch vụ API đề xuất.

Thăm dò ý kiến về một thao tác chạy trong thời gian dài

Để thăm dò ý kiến về một LRO có sẵn, hãy gọi lại phương thức get() cho đến khi thao tác hoàn tất. Sử dụng thời gian đợi luỹ thừa giữa mỗi yêu cầu thăm dò ý kiến, chẳng hạn như 10 giây.

LRO vẫn hoạt động trong tối thiểu 12 giờ, nhưng trong một số trường hợp có thể kéo dài hơn. Khoảng thời gian này có thể thay đổi và có thể khác nhau giữa các loại tệp. Sau khi tài nguyên hết hạn, bạn cần phải gửi yêu cầu phương thức download() mới.

Mọi yêu cầu đến get() đều phải sử dụng khoá tài nguyên. Để biết thêm thông tin, hãy xem phần Truy cập vào tệp trên Drive được chia sẻ bằng đường liên kết bằng khoá tài nguyên.

Các giao thức yêu cầu được hiển thị tại đây.

operations.get(name='NAME');

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

Xin lưu ý rằng name chỉ được trả về trong phản hồi cho yêu cầu download(). Không có cách nào khác để truy xuất vì API Drive không hỗ trợ phương thức List(). Nếu giá trị name bị mất, bạn phải tạo một phản hồi mới bằng cách gọi lại yêu cầu phương thức download().

Phản hồi từ yêu cầu get() bao gồm một tài nguyên đại diện cho một thao tác chạy trong thời gian dài. Để biết thêm thông tin, hãy xem phần Phản hồi tải xuống.

Khi phản hồi chứa trạng thái hoàn tất (done=true), thao tác chạy trong thời gian dài đã hoàn tất.

Tải bản sửa đổi xuống

Bạn có thể sử dụng giá trị của trường headRevisionId từ tài nguyên files để tải bản sửa đổi mới nhất xuống. Thao tác này sẽ tìm nạp bản sửa đổi tương ứng với siêu dữ liệu của tệp mà bạn đã truy xuất trước đó. Để tải dữ liệu xuống cho tất cả các bản sửa đổi trước đó của tệp vẫn được lưu trữ trên đám mây, bạn có thể gọi phương thức list() trên tài nguyên revisions bằng tham số fileId. Thao tác này sẽ trả về tất cả revisionIds trong tệp.

Để tải nội dung sửa đổi của tệp blob xuống, bạn phải gọi phương thức get() trên tài nguyên revisions bằng mã nhận dạng của tệp cần tải xuống, mã nhận dạng của bản sửa đổi và tham số URL alt=media. Tham số URL alt=media cho máy chủ biết rằng một yêu cầu tải nội dung xuống đang được yêu cầu dưới dạng định dạng phản hồi thay thế.

Bạn không thể tải bản sửa đổi cho Google Tài liệu, Trang tính, Trang trình bày và Vids xuống bằng phương thức get() với URL alt=media . Nếu không, lỗi fileNotDownloadable sẽ được tạo.

Tham số URL alt=media là một tham số hệ thống có sẵn trên tất cả các API REST của Google. Nếu sử dụng thư viện ứng dụng cho API Drive, bạn không cần phải đặt rõ ràng tham số này.

Giao thức yêu cầu được hiển thị tại đây.

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

Thay thế nội dung sau:

• FILE_ID: fileId của tệp mà bạn muốn tải xuống.
• REVISION_ID: revisionId của bản sửa đổi mà bạn muốn tải xuống.

Các bản sửa đổi của Google Tài liệu, Bản vẽ và Trang trình bày sẽ tự động tăng số bản sửa đổi. Tuy nhiên, dãy số này có thể có khoảng trống nếu các bản sửa đổi bị xoá, vì vậy, bạn không nên dựa vào các số tuần tự để truy xuất các bản sửa đổi.

Khắc phục sự cố về LRO

Khi một LRO không thành công, phản hồi của LRO đó sẽ bao gồm một mã lỗi chính tắc của Google Cloud.

Bảng sau đây giải thích nguyên nhân của từng mã và đề xuất cách xử lý mã đó. Đối với nhiều lỗi, bạn nên thử lại yêu cầu bằng cách sử dụng thời gian đợi luỹ thừa.

Bạn có thể đọc thêm về mô hình lỗi này và cách xử lý trong Hướng dẫn thiết kế API.

Chủ đề có liên quan

• Tải xuống và xuất tệp
• Quản lý các bản sửa đổi tệp