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 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 có thể tiếp tục cũng có thể làm giảm mức sử dụng băng thông khi xảy ra lỗi mạng, vì bạn không phải bắt đầu lại quá trình tải lên tệp lớn từ đầu.

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:

Trường tiêu đề
Content-Length Đặt thành 0 vì nội dung yêu cầu đang trống.
X-Goog-Upload-Command Đặt thành start.
X-Goog-Upload-Content-Type Ví dụ: đặt thành loại mime của tệp image/jpeg.
X-Goog-Upload-Protocol Đặt thành resumable.
X-Goog-Upload-Raw-Size Đặt thành tổng số byte của dữ liệu tệp cần đã chuyển.

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 cả tiêu đề sau.

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 quá trình 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 điều 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 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. 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, 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.

    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 chuyển trong bất kỳ yêu cầu. 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 biết tiến trình tải lên.
    • Bạn cần biết thời điểm an toàn để loại bỏ dữ liệu.

Yêu cầu duy nhất

Cách tải tệp lên trong một yêu cầu duy nhất:

  1. Tạo một yêu cầu POST đến URL của phiên hoạt động có thể tiếp tục.
  2. Thêm dữ liệu của tệp vào nội dung yêu cầu.

  3. Thêm các tiêu đề HTTP sau:

    • Content-Length: Đặt thành số byte trong .
    • X-Goog-Upload-Command: Đặt thành upload, finalize.

  4. Gửi yêu cầu.

Nếu yêu cầu tải lên bị gián đoạn hoặc bạn nhận được 5xx hãy làm theo quy trình trong Tiếp tục quá trình tải lên bị gián đoạn.

Nếu yêu cầu thành công, bạn sẽ nhận được trạng thái HTTP 200 OK và mã tải lên trong nội dung phản hồi. Tạo mục nội dung đa phương tiện bằng mã thông báo tải lên này.

Nhiều phần

Cách tải tệp lên theo nhiều phần:

  1. Tạo một yêu cầu POST đến URL của phiên hoạt động có thể tiếp tục.

  2. Thêm dữ liệu của đoạn vào phần nội dung yêu cầu.

    Ngoại trừ đoạn cuối cùng đã hoàn tất quá trình tải lên, hãy tạo các phân đoạn khác theo bội số có kích thước được chấp nhận của các đoạn. Giữ nguyên kích thước phân đoạn lớn nhất có thể để việc tải lên được hiệu quả.

  3. Thêm các tiêu đề HTTP sau:

    • Content-Length: Đặt thành số byte trong phân đoạn.
    • X-Goog-Upload-Command: Đặt thành upload. Đối với phần cuối cùng, hãy đặt thành upload, finalize.
    • X-Goog-Upload-Offset: Đặt thành giá trị chênh lệch mà tại đó giá trị byte. Lưu ý rằng bạn phải tải các byte lên theo tuần tự. Độ lệch đầu tiên là 0.
  4. Gửi yêu cầu.

    Nếu yêu cầu tải lên bị gián đoạn hoặc bạn nhận được 5xx hãy làm theo quy trình trong Tiếp tục quá trình tải lên bị gián đoạn.

  5. Lặp lại các bước này cho từng đoạn còn lại trong tệp.

Nếu yêu cầu thành công, bạn sẽ nhận được trạng thái HTTP 200 OK và mã tải lên trong nội dung phản hồi. Tạo mục nội dung đa phương tiện bằng mã thông báo tải lên này.

Ví dụ:

Yêu cầu duy nhất

Ví dụ sau đây cho thấy một yêu cầu có thể tiếp tục để tải một tệp JPEG có kích thước 3.039.417 byte lên trong một yêu cầu duy nhất.

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]

Phản hồi chứa URL tải lên và kích thước phân đoạn dự kiến:

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

Yêu cầu tải lên cuối cùng:

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]

Nhiều đoạn

Ví dụ sau đây cho thấy một yêu cầu tiếp tục được tải lên Tệp JPEG 3.039.417 byte trong nhiều đoạn, sử dụng phiên có thể tiếp tục URL và thông tin chi tiết về kích thước phân đoạn được chấp nhận ở bước trước. Ví dụ này sử dụng kích thước phân đoạn là 262.144 byte được trả về trong trường tiêu đề, x-goog-upload-chunk-granularity, khi đã khởi tạo phiên tải lên. Xin lưu ý rằng mỗi tệp tải lên đều chứa các byte là bội số của 262.144.

Khởi chạy phiên tải lên để nhận URL tải lên và kích thước phân đoạn như mô tả trong bước trước:

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]

Phản hồi chứa URL tải lên và kích thước phân đoạn dự kiến:

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

Phân đoạn đầu tiên:

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]

Phân đoạn thứ hai:

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]

Phần cuối cùng:

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 độ 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 đó, 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.