Thực hiện quá trình tải lên tiếp nối

Trang này mô tả cách tạo yêu cầu tải lên có thể tiếp tục trong API Xuất bản Chế độ xem đường phố. 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 phương án này 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 có thể tiếp tục cũng có thể làm giảm mức sử dụng băng thông khi mạng gặp sự cố, 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.

Nếu đang gửi các tệp nhỏ qua kết nối mạng đáng tin cậy, bạn có thể sử dụng tính năng tải lên đơn giản.

Bắt đầu một phiên tải lên có thể tiếp tục

Sau khi có uploadUrl, bạn có thể bắt đầu một phiên tải lên có thể tiếp tục:

  1. Tạo yêu cầu POST đến uploadUrl.

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

    • X-Goog-Upload-Protocol: Đặt thành resumable.
    • X-Goog-Upload-Header-Content-Length: Đặt thành tổng số byte của dữ liệu tệp sẽ được truyền trong các yêu cầu tiếp theo.
    • X-Goog-Upload-Header-Content-Type: Đặt thành loại MIME của dữ liệu tệp.
    • X-Goog-Upload-Command: Đặt thành start.

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

Ví dụ: Bắt đầu một phiên tải lên có thể tiếp tục

Ví dụ sau đây cho thấy cách bắt đầu một phiên có thể tiếp tục để tải một tệp mới lên. Trong trường hợp này, tệp là một hình ảnh và tổng số byte trong tệp là 4200000. Xin lưu ý rằng phần nội dung của yêu cầu đang trống; do đó, tiêu đề Content-Length được đặt thành 0.

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234 HTTP/1.1
Authorization: Bearer [YOUR_AUTH_TOKEN]
Content-Length: 0
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Header-Content-Length: 4200000
X-Goog-Upload-Header-Content-Type: image/jpeg
X-Goog-Upload-Command: start

Phần Lưu URL phiên có thể tiếp tục mô tả cách xử lý phản hồi cho yêu cầu bắt đầu phiên tải lên có thể tiếp tục.

Lưu URL phiên có thể tiếp tục

Đối với yêu cầu được gửi để bắt đầu một phiên tải lên có thể tiếp tục, máy chủ sẽ trả lời bằng mã trạng thái HTTP 200 OK, bao gồm cả tiêu đề sau:

  • X-Goog-Upload-URL: 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 để bạn có thể sử dụng cho các yêu cầu tiếp theo.

Ví dụ: Lưu URL phiên có thể tiếp tục

Ví dụ sau đây cho thấy một phản hồi bao gồm URL phiên có thể tiếp tục và yêu cầu về độ chi tiết về kích thước.

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable

Đang tải tệp lên

Có hai cách để tải tệp lên bằng phiên có thể tiếp nối:

  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 và do đó có hiệu suất tốt hơn.
  2. Trong nhiều phầ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 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 đơn

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

  1. Tạo 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 phần 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 phần Tiếp tục quá trình tải lên bị gián đoạn.

Nhiều phần

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

  1. Tạo yêu cầu POST đến URL phiên 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. Tạo các phần dữ liệu theo bội số của 2 MiB (mebibyte), ngoại trừ phần dữ liệu cuối cùng đã hoàn tất thao tác tải lên. Giữ kích thước dữ liệu càng lớn càng tốt để đảm bảo hiệu quả tải lên.

  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 độ dời mà các byte sẽ được ghi. Xin lưu ý rằng bạn phải tải các byte lên theo tuần tự.

  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 phần 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 từ 1 đến 4 cho từng phần còn lại trong tệp.

Ví dụ: Tải tệp lên

Yêu cầu đơn

Ví dụ sau đây cho thấy một yêu cầu có thể tiếp tục để tải toàn bộ tệp JPEG có kích thước 4.200.000 byte lên trong một yêu cầu duy nhất, sử dụng URL phiên có thể tiếp tục nhận được ở bước trước:

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 4200000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 0

[BYTES 0-4199999]

Nếu yêu cầu thành công, bạn sẽ nhận được mã trạng thái HTTP 200 OK.

Nhiều phầ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 có kích thước 4.200.000 byte lên theo nhiều phần, sử dụng URL phiên có thể tiếp tục và độ chi tiết về kích thước thu được ở bước trước. Ví dụ này sử dụng kích thước phân đoạn là 2097000 byte, là bội số của 2 MiB (mebibyte).

Phần đầu tiên:

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 0



[BYTES 0-2096999]

Phần thứ hai:

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 2097000



[BYTES 2097000-4193999]

Phần cuối cùng:

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 6000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 4194000



[BYTES 4194000-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:

  1. Tạo yêu cầu POST đến URL phiên có thể tiếp tục.
  2. Thiết lập X-Goog-Upload-Command thành query.
  3. Gửi yêu cầu.

Máy chủ sẽ phản hồi bằng mã trạng thái HTTP 200 OK và kích thước hiện tại của nội dung 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 độ dời 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ó mặt và giá trị không phải là active, thì quá trình tải lên đã bị chấm dứt.