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

Thao tác diễn ra 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 muố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 đó, tốt hơn là 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 này.

Phương thức này trả về một operations tài nguyên cho ứng dụng. Bạn có thể sử dụng tài nguyên operations để truy xuất không đồng bộ trạng thái của phương thức API bằng cách thăm dò thao tác 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 pattern.

Để biết thêm thông tin, hãy xem bài viết Thao tác diễn ra trong thời gian dài.

Tổng quan về quy trình

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

Các bước tổng quát cho phương thức file.download.
Hình 1. Các bước tổng quát cho phương thức file.download.

  1. Gọi files.download: Khi ứng dụng của bạn 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 bài viết Tải tệp xuống.

  2. Yêu cầu quyền: Yêu cầu này 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 bằng các 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: Một yêu cầu API Drive được thực hiện để bắt đầu tải tệp xuống. Yêu cầu này có thể được gửi đến Google Vids hoặc một số nội dung khác của Google Workspace.

  4. Bắt đầu LRO: Một thao tác diễn ra trong thời gian dài bắt đầu và quản lý quy 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 đang chờ xử lý ban đầu: Ứng dụng của bạn nhận được thao tác đang chờ xử lý cùng với trạng thái đang 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 khoảng thời gian được đề xuất để thăm dò kết quả thao tác và nhận trạng thái mới nhất của một thao tác diễn ra 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ò 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, hãy thăm dò nhiều lần. Để biết thêm thông tin, hãy xem bài viết Nhận thông tin chi tiết về một thao tác diễn ra 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ể sử dụng tệp.

Tải tệp xuống

Để tải nội dung xuống trong một thao tác diễn ra 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 tham số file_id, mime_type và revision_id:

  • Bắt buộc. Tham số đường dẫn file_id là mã 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 này sẽ sử dụng. Tham số này chỉ có 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). Để xem danh sách đầy đủ các loại MIME được hỗ trợ, hãy xem bài viết Xuất các loại MIME cho tài liệu Google Workspace.

    Nếu 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 bài viết Loại MIME mặc định.

  • Không bắt buộc. Tham số truy vấn revision_id là mã bản sửa đổi của tệp cần tải xuống. Tham số này chỉ 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 trên 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 các tệp video xuống. Nếu cố gắng xuất tệp Google Vids, bạn sẽ nhận được lỗi fileNotExportable.

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 trả về một lượt 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 các tệp Drive được chia sẻ qua đường liên kết bằng khoá tài nguyên.

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

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

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

Loại MIME mặc định

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

Loại tài liệu Định dạng Loại MIME Đuôi tệp
Google Apps Script JSON application/vnd.google-apps.script+json .json
Google Tài liệu Microsoft Word application/vnd.openxmlformats-officedocument.wordprocessingml.document .docx
Google Bản vẽ PNG hình ảnh/png .png
Google Biểu mẫu ZIP application/zip .zip
Google Trang tính Microsoft Excel application/vnd.openxmlformats-officedocument.spreadsheetml.sheet .xlsx
Google Sites Văn bản thô text/raw .txt
Google Trang trình bày Microsoft PowerPoint application/vnd.openxmlformats-officedocument.presentationml.presentation .pptx
Google Vids MP4 video/mp4 .mp4
Jamboard PDF application/pdf .pdf

Phản hồi tả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 diễn ra 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.

name
{
  "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:

Xin lưu ý rằng trường partialDownloadAllowed biểu thị xem có được phép tải xuống một phần hay không và là true khi tải nội dung tệp blob xuống.

Nhận thông tin chi tiết về một thao tác diễn ra trong thời gian dài

Thao tác diễn ra trong thời gian dài là các lệnh gọi phương thức có thể mất một khoảng thời gian đáng kể để hoàn tất. Thông thường, các thao tác tải xuống mới tạo ban đầu đượ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 đưa vào 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 diễn ra trong thời gian dài một cách không đồng bộ. Ứng dụng có thể dùng phương thức này để thăm dò kết quả của một thao tác theo khoảng thời gian do dịch vụ API đề xuất.

Thăm dò một thao tác diễn ra trong thời gian dài

Để thăm dò một LRO có sẵn, hãy gọi phương thức get nhiều lần 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ò, chẳng hạn như 10 giây.

LRO vẫn có sẵn trong tối thiểu 12 giờ nhưng trong một số trường hợp có thể tồn tại lâu hơn. Thời lượng 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 gửi yêu cầu phương thức download mới.

Mọi yêu cầu gửi đến get đề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 các tệp Drive được chia sẻ qua đường liên kết bằng khoá tài nguyên.

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

Lệnh gọi phương thức

operations.get(name='NAME');

Thay thế NAME bằng tên do máy chủ chỉ định của thao tác như trong phản hồi đối với yêu cầu phương thức download.

curl

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

Thay thế NAME bằng tên do máy chủ chỉ định của thao tác như trong phản hồi đối với yêu cầu phương thức download.

Lệnh này sử dụng đường dẫn /drive/v3/operations/NAME.

Xin lưu ý rằng name chỉ được trả về trong phản hồi đối với 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 mất giá trị name, bạn phải tạo 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 diễn ra trong thời gian dài. Để biết thêm thông tin, hãy xem bài viết Tải xuống phản hồi.

Khi phản hồi chứa trạng thái hoàn tất (done=true), thao tác diễn ra 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 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 trả về tất cả revisionIds trong tệp.

Để tải nội dung bản 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ã của tệp cần tải xuống, mã 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 lượt 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ế.

Không thể tải các 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, hệ thống sẽ tạo ra lỗi fileNotDownloadable.

Tham số URL alt=media là một tham số hệ thống có 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 đặt tham số này một cách rõ ràng.

Giao thức yêu cầu được hiển thị ở đâ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, chuỗi số 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 bản sửa đổi.

Khắc phục sự cố 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 hiển thị từng mã lỗi, mã trạng thái HTTP được ánh xạ, nội dung mô tả và đề xuất về cách xử lý mã lỗi. Đối với nhiều lỗi, hành động được đề xuất là thử lại yêu cầu bằng thời gian đợi luỹ thừa.

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

Mã Enum Mã trạng thái HTTP Mô tả Hành động được đề xuất
1 CANCELLED 499 Client Closed Request Thao tác đã bị huỷ, thường là do phương thức gọi. Chạy lại thao tác.
2 UNKNOWN 500 Internal Server Error Lỗi này có thể được trả về khi giá trị Status nhận được từ một không gian địa chỉ khác thuộc về một không gian lỗi không xác định trong không gian địa chỉ này. Nếu lỗi API không trả về đủ thông tin, thì lỗi đó có thể được chuyển đổi thành lỗi này. Thử lại với thời gian đợi luỹ thừa.
3 INVALID_ARGUMENT 400 Bad Request Ứng dụng chỉ định đối số không hợp lệ. Lỗi này khác với FAILED_PRECONDITION. INVALID_ARGUMENT cho biết các đối số có vấn đề bất kể trạng thái của hệ thống, chẳng hạn như tên tệp bị định dạng sai. Không thử lại nếu chưa khắc phục vấn đề.
4 DEADLINE_EXCEEDED 504 Gateway Timeout Thời hạn đã hết trước khi thao tác có thể hoàn tất. Đối với các thao tác thay đổi trạng thái của hệ thống, lỗi này có thể được trả về ngay cả khi thao tác đã hoàn tất thành công. Ví dụ: phản hồi thành công từ một máy chủ có thể bị trì hoãn đủ lâu để thời hạn hết. Thử lại với thời gian đợi luỹ thừa.
5 NOT_FOUND 404 Not Found Không tìm thấy một số thực thể được yêu cầu, chẳng hạn như tài nguyên FHIR. Không thử lại nếu chưa khắc phục vấn đề.
6 ALREADY_EXISTS 409 Conflict Thực thể mà ứng dụng cố gắng tạo, chẳng hạn như một thực thể DICOM, đã tồn tại. Không thử lại nếu chưa khắc phục vấn đề.
7 PERMISSION_DENIED 403 Forbidden Phương thức gọi không có quyền thực thi thao tác đã chỉ định. Mã lỗi này không ngụ ý rằng yêu cầu là hợp lệ, thực thể được yêu cầu tồn tại hoặc đáp ứng các điều kiện tiên quyết khác. Không thử lại nếu chưa khắc phục vấn đề.
8 RESOURCE_EXHAUSTED 429 Too Many Requests Một số tài nguyên đã cạn kiệt, chẳng hạn như hạn mức cho mỗi dự án. Thử lại với thời gian đợi luỹ thừa. Hạn mức có thể trở nên có sẵn theo thời gian.
9 FAILED_PRECONDITION 400 Bad Request Thao tác đã bị từ chối vì hệ thống không ở trạng thái cần thiết để thực thi thao tác. Ví dụ: thư mục cần xoá không trống hoặc thao tác rmdir được áp dụng cho một thư mục không phải là thư mục. Không thử lại nếu chưa khắc phục vấn đề.
10 ABORTED 409 Conflict Thao tác đã bị huỷ, thường là do vấn đề về tính đồng thời, chẳng hạn như lỗi kiểm tra trình tự hoặc huỷ giao dịch. Thử lại với thời gian đợi luỹ thừa.
11 OUT_OF_RANGE 400 Bad Request Thao tác đã được thực hiện ngoài phạm vi hợp lệ, chẳng hạn như tìm kiếm hoặc đọc ngoài cuối tệp. Không giống như INVALID_ARGUMENT, lỗi này cho biết một vấn đề có thể được khắc phục nếu trạng thái hệ thống thay đổi. Không thử lại nếu chưa khắc phục vấn đề.
12 UNIMPLEMENTED 501 Not Implemented Thao tác không được triển khai hoặc không được hỗ trợ/bật trong API Drive. Không thử lại.
13 INTERNAL 500 Internal Server Error Lỗi nội bộ. Điều này cho biết đã gặp phải một lỗi không mong muốn trong quá trình xử lý trên hệ thống cơ bản. Thử lại với thời gian đợi luỹ thừa.
14 UNAVAILABLE 503 Service Unavailable API Drive không hoạt động. Đây rất có thể là một tình trạng tạm thời, có thể được khắc phục bằng cách thử lại với thời gian đợi luỹ thừa. Xin lưu ý rằng không phải lúc nào cũng an toàn khi thử lại các thao tác không có tính lũy đẳng. Thử lại với thời gian đợi luỹ thừa.
15 DATA_LOSS 500 Internal Server Error Mất dữ liệu hoặc hư hỏng không thể khôi phục. Liên hệ với quản trị viên hệ thống của bạn. Quản trị viên hệ thống có thể muốn liên hệ với đại diện hỗ trợ nếu xảy ra tình trạng mất dữ liệu hoặc hư hỏng dữ liệu.
16 UNAUTHENTICATED 401 Unauthorized Yêu cầu không có thông tin xác thực hợp lệ cho thao tác. Không thử lại nếu chưa khắc phục vấn đề.