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 thông 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 đang sử dụng thư viện ứng dụng, xin lưu ý rằng một số thư viện ứng dụng cung cấp dịch vụ hỗ trợ gốc cho quá trình tải lên tiếp nối.

Sử dụng tùy chọn tải lên tiếp nối nếu:

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

Quá trình tải lên tiếp nối cũng có thể 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 các tệp lớn lên ngay từ đầu.

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

Bắt đầu 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. Tải tệp lên bằng cách sử dụng URL tải lên tiếp nối được trả về trong yêu cầu này.

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ì phần nội dung yêu cầu trống.
X-Goog-Upload-Command Đặt thành start.
X-Goog-Upload-Content-Type Đặt thành loại MIME của tệp, ví dụ: 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 sẽ được 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 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 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ă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 quá trình tải lên được thực hiện trong nhiều phần, thì tất cả tệp tải lên (ngoại trừ lượt tải lên gần đây nhất) đều phải được thực hiện theo bội số của giá trị này. Điều này nghĩa là các byte tải lên của tệp phải được căn chỉnh theo giá trị này. Trong phân đoạ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 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 lên có phiên hoạt động có thể tiếp tục:

  1. Trong một yêu cầu duy nhất. Thông thường, phương pháp này là tốt nhất vì cần ít yêu cầu hơn nên hiệu suất cũng cao hơn.

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

    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 một yêu cầu duy nhất. Bạn có thể cần làm như vậy khi có giới hạn thời gian cố định cho từng yêu cầu.
    • 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.

Một yêu cầu

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 phiên 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 tệp.
    • 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 phản hồi 5xx, hãy làm theo quy trình trong bài viết 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 mã trạng thái HTTP 200 OK và mã thông báo 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ã tải lên này.

Nhiều đoạ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 phiên có thể tiếp tục.

  2. Thêm dữ liệu của phân đoạn vào 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 đoạn khác theo bội số của kích thước các đoạn được chấp nhận. Hãy duy trì kích thước phân đoạn lớn nhất có thể để quá trình tải lên diễn ra hiệu quả.

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

    • Content-Length: Đặt thành số lượng byte trong đoạn.
    • X-Goog-Upload-Command: Đặt thành upload. Đối với phân đoạn cuối cùng, hãy đặt thành upload, finalize.
    • X-Goog-Upload-Offset: Đặt thành độ lệch mà byte cần được ghi. Xin lưu ý rằng các byte phải được tải 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 phản hồi 5xx, hãy làm theo quy trình trong bài viết 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 trên cho từng phần còn lại trong tệp.

Nếu yêu cầu thành công, bạn sẽ nhận được mã trạng thái HTTP 200 OK và mã thông báo 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ã tải lên này.

Ví dụ:

Một yêu cầu

Ví dụ sau đây cho thấy một yêu cầu tiếp nối để tải tệp JPEG 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 có thể tiếp tục để tải tệp JPEG 3.039.417 byte lên nhiều phần, sử dụng URL phiên có thể tiếp tục và độ chi tiết kích thước phân đoạn được chấp nhận thu được trong 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 phiên tải lên được khởi động. Xin lưu ý rằng mỗi tệp tải lên chứa số byte nằm trong bội số của 262.144.

Khởi động 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 đoạ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 mã trạng thái HTTP không phải 200, hãy truy vấn máy chủ để tìm hiểu xem đã tải lên thành công bao nhiêu phần.

Dưới đây là một yêu cầu POST đến URL phiên có thể tiếp tục. Bạn phải đặ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 tại mức chênh lệch này. Bạn phải tiếp tục ở mức chênh lệch 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 ở mức chênh lệch 0.

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