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 để hoàn tất hơn mức phù 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 đó, bạn nên trả về một loại lời hứa nào đó 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 tài nguyên operations 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ò hoạt động thông qua phương thức get. Các LRO trong Drive API 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 Các 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 cấp cao về cách hoạt động của phương thức file.download.
Gọi
files.download: Khi ứng dụng của bạn gọi phương thứcdownload, phương thức này sẽ khởi chạy yêu cầu tải xuống Drive API cho tệp. Để biết thêm thông tin, hãy xem phần Tải tệp xuống.Yêu cầu quyền: Yêu cầu này gửi thông tin xác thực đến Drive API. Nếu ứng dụng của bạn yêu cầu gọi Drive API 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 phạm vi mà bạn chỉ định khi thiết lập quy trình xác thực.
Bắt đầu tải xuống: Yêu cầu Drive API được thực hiện để bắt đầu tải tệp xuống. Yêu cầu có thể được gửi đến Google Vids hoặc một số nội dung khác trong Google Workspace.
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.
Trả về thao tác đang chờ xử lý: Drive API 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.
Trạng thái ban đầu đang chờ xử lý: Ứ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 ban đầu đang chờ xử lý 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 hoạt động đang chờ xử lý.Gọi
operations.getvà xác minh kết quả: Ứng dụng của bạn gọigettheo 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 diễn ra trong thời gian dài. Nếu trạng thái đang chờ xử lý củadone=falseđược trả về, ứ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 dự kiến thăm dò nhiều lần. Để biết thêm thông tin, hãy xem phần Lấy thông tin chi tiết về một thao tác diễn ra trong thời gian dài.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 hoạt động đã hoàn tất.Trả về thao tác đã hoàn tất bằng URI tải xuống: Sau khi LRO hoàn tất, Drive API 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 kéo 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ố truy vấn của file_id, mime_type và revision_id:
Bắt buộc. Tham số truy vấn
file_idlà 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_typebiểu thị loại MIME mà phương thức này sẽ sử dụng. Tính năng này chỉ hoạt động khi bạn tải nội dung nghe nhìn không phải là blob xuống (chẳng hạn như tài liệu trên 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 trên Google Workspace.Nếu bạn không đặt loại MIME, thì 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 Các loại MIME mặc định.
Không bắt buộc. Tham số truy vấn
revision_idlà mã nhận dạng phiên bản 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ỗiINVALID_ARGUMENTkhi 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.
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 đối với 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 được chia sẻ qua đường liên kết trên Drive bằng khoá tài nguyên.
Giao thức yêu cầu được minh hoạ tại đây.
POST https://www.googleapis.com/drive/v3/files/{FILE_ID}/downloadThay 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 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:
| 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 | Mã ZIP | application/zip | .zip |
| Google Trang tính | Microsoft Excel | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet | .xlsx |
| Google Sites | Văn bản thô | văn bản/thô | .txt |
| Google Trang trình bày | Microsoft PowerPoint | application/vnd.openxmlformats-officedocument.presentationml.presentation | .pptx |
| Google Vids | MP4 | application/mp4 | .mp4 |
| Jamboard | application/pdf |
Tải câu trả lời xuống
Khi gọi phương thức download, 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.
{
"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 bị 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 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 có được phép tải xuống một phần hay không. True khi tải nội dung tệp blob xuống.
Lấy thông tin chi tiết về một thao tác diễn ra trong thời gian dài
Các thao tác diễn ra trong thời gian dài là những 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 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à Drive API 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 sẽ lấy trạng thái mới nhất của một hoạt động diễn ra trong thời gian dài theo 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ả hoạt động theo khoảng thời gian mà dịch vụ API đề xuất.
Thăm dò một thao tác thực hiện lâu
Để 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ò ý kiến, 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. 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. Khi tài nguyên hết hạn, bạn cần gửi yêu cầu mới về phương thức download.
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 bài viết Truy cập vào tệp được chia sẻ qua đường liên kết trên Drive bằng khoá tài nguyên.
Các giao thức yêu cầu sẽ xuất hiện tại đâ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 cho 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 cho 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 cho yêu cầu download.
Không có cách nào khác để truy xuất mã này vì Drive API không hỗ trợ phương thức List. Nếu mất giá trị name, 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ừ mộ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 phần Tải phản hồi xuống.
Khi phản hồi có trạng thái hoàn tất (done=true), tức là hoạt động diễn ra trong thời gian dài đã kết thúc.
Tải một bản sửa đổi xuống
Bạn có thể sử dụng giá trị của trường headRevisionId trong 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 phiên bản 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 đây 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 của bản sửa đổi trong 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 gửi dưới dạng một định dạng phản hồi thay thế.
Bạn không thể tải các bản sửa đổi của 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, thao tác này sẽ tạo ra lỗi fileNotDownloadable.
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 một thư viện ứng dụng cho Drive API, bạn không cần phải đặt rõ ràng tham số này.
Giao thức yêu cầu được minh hoạ tại đây.
GET https://www.googleapis.com/drive/v3/files/{FILE_ID}/revisions/{REVISION_ID}?alt=mediaThay thế nội dung sau:
- FILE_ID:
fileIdcủa tệp mà bạn muốn tải xuống. - REVISION_ID:
revisionIdcủa phiên bản mà bạn muốn tải xuống.
Google Tài liệu, Bản vẽ và Trang trình bày sẽ tự động tăng số phiên bản. 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 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 chuẩn 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, hành động được đề xuất là thử lại yêu cầu bằng cách sử dụng thuật toán 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 sử dụng mô hình này trong Hướng dẫn thiết kế API.
| Mã | Enum | Mô tả | Hành động được đề xuất |
|---|---|---|---|
| 1 | CANCELLED |
Thao tác đã bị huỷ, thường là do người gọi. | Chạy lại thao tác. |
| 2 | UNKNOWN |
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 |
Ứng dụng khách chỉ định một đố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ị lỗi. |
Đừng thử lại mà không khắc phục vấn đề. |
| 4 | DEADLINE_EXCEEDED |
Đã hết thời hạn 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 kết thúc. | Thử lại với thời gian đợi luỹ thừa. |
| 5 | 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. | Đừng thử lại mà không khắc phục vấn đề. |
| 6 | ALREADY_EXISTS |
Thực thể mà ứng dụng khách đã cố gắng tạo (chẳng hạn như một phiên bản DICOM) đã tồn tại. | Đừng thử lại mà không khắc phục vấn đề. |
| 7 | PERMISSION_DENIED |
Trình 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. | Đừng thử lại mà không khắc phục vấn đề. |
| 8 | RESOURCE_EXHAUSTED |
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. Định mức có thể được cấp theo thời gian. |
| 9 | FAILED_PRECONDITION |
Thao tác bị từ chối vì hệ thống không ở trạng thái cần thiết để thực hiện thao tác. Ví dụ: thư mục cần xoá không phải là thư mục 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. |
Đừng thử lại mà không khắc phục vấn đề. |
| 10 | ABORTED |
Thao tác bị huỷ bỏ, 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 |
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 phần cuối của 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. |
Đừng thử lại mà không khắc phục vấn đề. |
| 12 | UNIMPLEMENTED |
Thao tác này chưa được triển khai hoặc không được hỗ trợ/bật trong Drive API. | Đừng thử lại. |
| 13 | INTERNAL |
Lỗi nội bộ. Lỗi này cho biết đã xảy ra lỗi ngoài dự kiế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 |
Drive API hiện không hoạt động. Đây thường là một điều kiện tạm thời và bạn có thể 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 bạn cũng có thể thử lại các thao tác không có tính chất luỹ đẳng. | Thử lại với thời gian đợi luỹ thừa. |
| 15 | DATA_LOSS |
Mất hoặc hư hỏng dữ liệu và không phục hồi được. | Liên hệ với quản trị viên hệ thống. Quản trị viên hệ thống nên liên hệ với nhân viên hỗ trợ nếu xảy ra tình trạng mất hoặc hỏng dữ liệu. |
| 16 | UNAUTHENTICATED |
Yêu cầu không có thông tin xác thực hợp lệ cho thao tác. | Đừng thử lại mà không khắc phục vấn đề. |