Tải lên có thể tiếp tụcResumable uploads

Trang này mô tả cách tạo một yêu cầu tải lên tiếp nối tới API Thư viện Google Photos qua giao thức REST. Giao thức này cho phép bạn tiếp tục hoạt động tải lên sau khi lỗi giao tiếp làm gián đoạn luồng dữ liệu.

Sử dụng tuỳ chọn tải lên tiếp nối trong trường hợp:

• Bạn đang tải tệp có kích thước lớn lên.
• Khả năng bị gián đoạn mạng hoặc một số lỗi truyền khác là rất cao (ví dụ: nếu bạn đang tải tệp lên từ một ứng dụng di động).

Tính năng tải lên tiếp nối cũng có thể giúp bạn giảm mức sử dụng băng thông khi có mạng vì bạn không phải bắt đầu lại quá trình tải tệp lớn lên từ đầu tiên.

Bước 1: Bắt đầu phiên tải lên

Khởi tạo một phiên tải lên có thể tiếp tục bằng cách gửi yêu cầu POST đến https://photoslibrary.googleapis.com/v1/uploads. Sử dụng quy trình tải lên tiếp nối URL được trả về trong yêu cầu này, hãy tải tệp lên.

Yêu cầu POST phải bao gồm các tiêu đề sau:

Sau đây là tiêu đề yêu cầu POST:

POST https://photoslibrary.googleapis.com/v1/uploads
Authorization: Bearer oauth2-token
Content-Length: 0
X-Goog-Upload-Command: start
X-Goog-Upload-Content-Type: mime-type
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Raw-Size: bytes-of-file

Bước 2: Lưu URL phiên

Nếu thành công, yêu cầu POST sẽ trả về mã trạng thái HTTP 200 OK, bao gồm tiêu đề sau đây.

X-Goog-Upload-URL: url-to-make-uploads-to
X-Goog-Upload-Chunk-Granularity: chunk-granularity-in-bytes

Trường tiêu đề x-goog-upload-chunk-granularity chứa cách căn chỉnh byte và độ chi tiết về kích thước của tất cả các phần dữ liệu do ứng dụng gửi. Nếu nội dung tải lên được thực hiện trong nhiều phần, tất cả các tệp tải lên, ngoại trừ tệp tải lên gần đây nhất, phải được thực hiện trong bội số của giá trị này. Tức là số byte tải lên của tệp phải được căn chỉnh theo giá trị này. Trong phần cuối cùng, bạn có thể tải các byte còn lại lên.

Trường tiêu đề X-Goog-Upload-URL chứa một URL duy nhất phải được sử dụng để hoàn tất quá trình tải lên thông qua tất cả các yêu cầu còn lại. Sao chép và lưu URL phiên có thể tiếp tục này để bạn có thể sử dụng cho các yêu cầu tiếp theo.

Bước 3: Tải tệp lên

Có hai cách để tải tệp có phiên hoạt động có thể tiếp tục lên:

1. Trong một yêu cầu. Phương pháp này thường là tốt nhất vì yêu cầu ít yêu cầu hơn, do đó có hiệu suất tốt hơn.

2. Trong nhiều phần. Trong phương pháp này, quá trình tải lên được thực hiện trong nhiều yêu cầu bằng cách chia dữ liệu thành các phần. Dữ liệu được chia theo phần bội số của x-goog-upload-chunk-granularity. Nếu cần, bạn có thể thử lại các yêu cầu được phân đoạn.

   Hãy sử dụng phương pháp này nếu:

   • Bạn cần giảm lượng dữ liệu được truyền trong bất kỳ yêu cầu riêng lẻ nào. Bạn có thể cần làm việc này khi có giới hạn thời gian cố định cho từng yêu cầu riêng lẻ.
   • Bạn cần cung cấp một chỉ báo tuỳ chỉnh cho thấy lượt tải lên tiến trình.
   • Bạn cần biết thời điểm an toàn để loại bỏ dữ liệu.

Ví dụ:

POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1
Content-Length: 0
X-Goog-Upload-Command: start
X-Goog-Upload-Content-Type: image/jpeg
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Raw-Size: 3039417
[no body]

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable
X-Goog-Upload-Chunk-Granularity: 262144

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 3039417
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 0

[BYTES 0-4199999]

POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1
Content-Length: 0
X-Goog-Upload-Command: start
X-Goog-Upload-Content-Type: image/jpeg
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Raw-Size: 3039417
[no body]

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable
X-Goog-Upload-Chunk-Granularity: 262144

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 1048576
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 0

[BYTES 0-1048575]

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 1048576
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 1048576

[BYTES 1048576-2097151]

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 942265
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 2097152

[BYTES 2097152-4200000]

Tiếp tục quá trình tải lên bị gián đoạn

Nếu yêu cầu tải lên bị gián đoạn hoặc nếu bạn nhận được mã trạng thái HTTP không phải 200, hãy truy vấn máy chủ để tìm hiểu lượng dữ liệu tải lên thành công.

Dưới đây là yêu cầu POST đến URL phiên có thể tiếp tục. Bạn nên đặt X-Goog-Upload-Command thành query.

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 0
X-Goog-Upload-Command: query

Phản hồi từ máy chủ bao gồm mã trạng thái HTTP 200 OK và kích thước hiện tại của tệp tải lên.

HTTP/1.1 200 OK
X-Goog-Upload-Status: active
X-Goog-Upload-Size-Received: 100

Sau đó, bạn có thể tiếp tục tải lên ở mức chênh lệch này. Bạn phải tiếp tục tại độ dời do máy chủ cung cấp, trừ phi bạn gửi lệnh kết hợp tải lên và hoàn tất. Trong trường hợp này, bạn cũng có thể tiếp tục tại độ dời 0.

Nếu tiêu đề X-Goog-Upload-Status trong phản hồi HTTP của lệnh truy vấn có tồn tại và giá trị không phải là active, điều này cho biết rằng quá trình tải lên đã đã bị chấm dứt.