Trang này mô tả cách đưa ra yêu cầu tải lên có thể tiếp tục trong Street View Publish API. 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 các tệp có kích thước lớn lên.
- Khả năng xảy ra tình trạng gián đoạn mạng hoặc một số lỗi truyền dữ liệu 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ể 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 khởi động 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 một kết nối mạng đáng tin cậy, bạn có thể sử dụng phương thức 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 nhận được uploadUrl, bạn có thể bắt đầu một phiên tải lên có thể tiếp tục:
- Tạo một yêu cầu
POSTchouploadUrl. Thêm các tiêu đề HTTP sau:
X-Goog-Upload-Protocol: Đặt thànhresumable.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ànhstart.
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 minh hoạ 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 nội dung yêu cầu 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
Lưu URL của 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 của 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 minh hoạ một phản hồi bao gồm URL của phiên có thể tiếp tục và yêu cầu về độ chi tiết 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ó 2 cách để tải tệp lên bằng một phiên có thể tiếp tục:
- Trong một yêu cầu duy nhất. Phương pháp này thường là tốt nhất, vì phương pháp này yêu cầu ít yêu cầu hơn và do đó có hiệu suất tốt hơn.
- Thành 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 phải thực hiện 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 duy nhất
Cách tải tệp lên trong một yêu cầu duy nhất:
- Tạo một yêu cầu
POSTđến URL của phiên có thể tiếp tục. - Thêm dữ liệu của tệp vào phần nội dung yêu cầu.
Thêm các tiêu đề HTTP sau:
Content-Length: Đặt thành số byte trong tệp.X-Goog-Upload-Command: Đặt thànhupload, finalize.
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 đoạn
Cách tải tệp lên theo nhiều phần:
- Tạo một yêu cầu
POSTđến URL của phiên có thể tiếp tục. - Thêm dữ liệu của khối vào nội dung yêu cầu. Tạo các phần có kích thước là bội số của 2 MiB (mebibyte), ngoại trừ phần cuối cùng hoàn tất quá trình 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.
Thêm các tiêu đề HTTP sau:
Content-Length: Đặt thành số byte trong khối.X-Goog-Upload-Command: Đặt thànhupload. Đối với phân đoạn cuối cùng, hãy đặt thànhupload, finalize.X-Goog-Upload-Offset: Đặt thành độ lệch 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ự.
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.Lặp lại các bước từ 1 đến 4 cho từng khối còn lại trong tệp.
Ví dụ: Tải tệp lên
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 lên toàn bộ tệp JPEG 4.200.000 byte trong một yêu cầu duy nhất, bằng cách 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 đoạn
Ví dụ sau đây minh hoạ 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 nhiều khối, bằng cách 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 khối là 2097000 byte, gấp nhiều lần 2 MiB (mebibyte).
Đoạ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]
Đoạ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]
Đoạ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ủ để biết quá trình tải lên đã thành công bao nhiêu:
- Tạo một yêu cầu
POSTđến URL của phiên có thể tiếp tục. - Đặt
X-Goog-Upload-Commandthànhquery. - 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 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 vị trí này. Bạn phải tiếp tục tại độ lệch do máy chủ cung cấp, trừ phi bạn gửi lệnh tải lên và hoàn tất kết hợp. Trong trường hợp đó, bạn cũng có thể tiếp tục tại độ 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ì quá trình tải lên đã bị chấm dứt.