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.

Nếu bạn là nhà phát triển sử dụng thư viện ứng dụng, hãy lưu ý rằng một số thư viện ứng dụng cung cấp hỗ trợ riêng cho quá trình tải lên tiếp nối.

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

• Bạn đang tải các tệp có kích thước lớn lên.
• Khả năng gián đoạn mạng hoặc lỗi truyền tải nào đó khác cao (ví dụ: nếu bạn đang tải tệp lên từ ứng dụng dành cho thiết bị 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

Bắt đầu phiên tải lên có thể tiếp tục bằng cách gửi yêu cầu POST tới 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:

Dưới đây là tiêu đề của 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 của phiên hoạt động

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 cho 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à các byte tải lên của tệp phải được điều chỉnh theo giá trị này. Trong đoạn cuối cùng, bạn có thể tải đoạn còn lại lên byte.

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 nội dung này URL phiên có thể tiếp tục để 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 duy nhất. Đây thường là phương pháp hiệu quả nhất, vì cần ít yêu cầu hơn, từ đó mang lại hiệu suất tốt hơn.

2. Trong nhiều đoạn. Trong phương pháp này, phần tải lên được thực hiện trong nhiều yêu cầu bằng cách phân đoạn dữ liệu. Dữ liệu được chia theo 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 đã phân đoạn.

   Sử dụng phương pháp này trong trường hợp:

   • Bạn cần giảm lượng dữ liệu được chuyển trong bất kỳ của bạn. Bạn có thể cần làm việc này khi có giới hạn thời gian cố định cho yêu cầu cá nhân.
   • 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 trạng thái HTTP không phải 200 hãy truy vấn máy chủ để tìm hiểu xem có bao nhiêu lượt 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. X-Goog-Upload-Command phải được đặt 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 vị trí bù trừ do máy chủ cung cấp trừ phi bạn gửi một lệnh tải lên kết hợp và hoàn tất, trong trường hợp đó, bạn cũng có thể tiếp tục tại giá trị bù 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.