Tính năng tải nội dung nghe nhìn lên cho phép API Display & Video 360 lưu trữ dữ liệu trên đám mây và cung cấp dữ liệu đó cho máy chủ. Các loại dữ liệu mà một người có thể muốn tải lên bao gồm ảnh, video, tệp PDF, tệp zip hoặc bất kỳ loại dữ liệu nào khác.
Các ví dụ trong tài liệu này cho thấy việc sử dụng tính năng tải nội dung nghe nhìn lên cho một Farm API hư cấu. Tuy nhiên, các khái niệm tương tự sẽ áp dụng cho Display & Video 360 API.
Lựa chọn tải lên
API Display & Video 360 cho phép bạn tải một số loại dữ liệu nhị phân hoặc nội dung nghe nhìn lên. Các đặc điểm cụ thể của dữ liệu mà bạn có thể tải lên được chỉ định trên trang tham chiếu cho mọi phương pháp hỗ trợ tải nội dung đa phương tiện lên:
- Kích thước tệp tải lên tối đa: Lượng dữ liệu tối đa mà bạn có thể lưu trữ bằng phương pháp này.
- Các loại MIME nội dung đa phương tiện được chấp nhận: Các loại dữ liệu nhị phân bạn có thể lưu trữ bằng phương thức này.
Bạn có thể gửi yêu cầu tải lên theo bất kỳ cách nào sau đây. Chỉ định phương thức bạn đang sử dụng với tham số yêu cầu uploadType
.
- Tải lên đơn giản:
uploadType=media
. Để chuyển nhanh các tệp nhỏ hơn, chẳng hạn như 5 MB trở xuống. - Tải nhiều phần lên:
uploadType=multipart
. Để chuyển nhanh các tệp nhỏ và siêu dữ liệu; chuyển tệp cùng với siêu dữ liệu mô tả tệp, tất cả trong một yêu cầu duy nhất. - Tải lên tiếp nối:
uploadType=resumable
. Để chuyển dữ liệu một cách ổn định, đặc biệt quan trọng với các tệp lớn. Với phương thức này, bạn sử dụng yêu cầu khởi tạo phiên có thể bao gồm siêu dữ liệu (không bắt buộc). Đây là một chiến lược hay để sử dụng cho hầu hết các ứng dụng, vì nó cũng hoạt động với các tệp nhỏ hơn với chi phí là một yêu cầu HTTP bổ sung cho mỗi lần tải lên.
Khi tải lên một nội dung đa phương tiện, bạn cần sử dụng URI đặc biệt. Trên thực tế, các phương thức hỗ trợ tải nội dung đa phương tiện lên có hai điểm cuối URI:
URI /upload cho nội dung nghe nhìn. Định dạng của điểm cuối tải lên là URI tài nguyên chuẩn có tiền tố “/upload”. Sử dụng URI này khi chuyển chính dữ liệu đa phương tiện.
Ví dụ:
POST /upload/farm/v1/animals
URI tài nguyên chuẩn, cho siêu dữ liệu. Nếu tài nguyên chứa bất kỳ trường dữ liệu nào, thì các trường đó sẽ được dùng để lưu trữ siêu dữ liệu mô tả tệp đã tải lên. Bạn có thể sử dụng URI này khi tạo hoặc cập nhật giá trị siêu dữ liệu.
Ví dụ:
POST /farm/v1/animals
Tải lên đơn giản
Phương pháp đơn giản nhất để tải tệp lên là tạo một yêu cầu tải lên đơn giản. Tùy chọn này là lựa chọn phù hợp khi:
- Dung lượng tệp đủ nhỏ để tải lên lại nếu không có kết nối mạng.
- Không bao gồm siêu dữ liệu. Điều này có thể đúng nếu bạn dự định gửi siêu dữ liệu cho tài nguyên này trong một yêu cầu riêng, hoặc nếu không có siêu dữ liệu nào được hỗ trợ hoặc có sẵn.
Để sử dụng tính năng tải lên đơn giản, hãy tạo yêu cầu POST
hoặc PUT
đến URI /upload của phương thức và thêm tham số truy vấn uploadType=media
. Ví dụ:
POST https://www.googleapis.com/upload/farm/v1/animals?uploadType=media
Các tiêu đề HTTP cần sử dụng khi tạo một yêu cầu tải lên đơn giản bao gồm:
Content-Type
. Đặt thành một trong các loại dữ liệu nội dung nghe nhìn tải lên được chấp nhận của phương thức, được chỉ định trong tài liệu tham khảo API.Content-Length
. Đặt thành số byte tương ứng mà bạn đang tải lên. Không bắt buộc nếu bạn đang sử dụng mã hoá chuyển dữ liệu chia nhỏ.
Ví dụ: Tải lên đơn giản
Ví dụ sau cho thấy việc sử dụng một yêu cầu tải lên đơn giản cho Farm API hư cấu.
POST /upload/farm/v1/animals?uploadType=media HTTP/1.1 Host: www.googleapis.com Content-Type: image/jpeg Content-Length: number_of_bytes_in_file Authorization: Bearer your_auth_token JPEG data
Nếu yêu cầu thành công, máy chủ sẽ trả về mã trạng thái HTTP 200 OK
cùng với bất kỳ siêu dữ liệu nào:
HTTP/1.1 200 Content-Type: application/json { "name": "Llama" }
Tải nhiều phần lên
Nếu muốn gửi siêu dữ liệu kèm theo dữ liệu cần tải lên, bạn có thể thực hiện một yêu cầu multipart/related
duy nhất. Đây là lựa chọn phù hợp nếu dữ liệu bạn gửi vẫn đủ nhỏ để tải lên lại toàn bộ nếu kết nối bị mất.
Để sử dụng tính năng tải lên nhiều phần, hãy tạo yêu cầu POST
hoặc PUT
đến URI /upload của phương thức và thêm tham số truy vấn uploadType=multipart
, ví dụ:
POST https://www.googleapis.com/upload/farm/v1/animals?uploadType=multipart
Các tiêu đề HTTP cấp cao nhất cần sử dụng khi tạo yêu cầu tải lên nhiều phần bao gồm:
Content-Type
. Đặt thành nhiều phần/có liên quan và bao gồm chuỗi ranh giới mà bạn đang sử dụng để xác định các phần của yêu cầu.Content-Length
. Đặt thành tổng số byte trong nội dung yêu cầu. Dung lượng nội dung phương tiện của yêu cầu phải nhỏ hơn kích thước tệp tối đa được chỉ định cho phương pháp này.
Phần nội dung của yêu cầu được định dạng thành loại nội dung multipart/related
[RFC2387] và chứa đúng 2 phần. Các phần được xác định bằng một chuỗi ranh giới và theo sau chuỗi ranh giới cuối cùng là hai dấu gạch nối.
Mỗi phần của yêu cầu nhiều phần cần có thêm tiêu đề Content-Type
:
- Phần siêu dữ liệu: Phải xuất hiện trước, và
Content-Type
phải khớp với một trong các định dạng siêu dữ liệu được chấp nhận. - Phần nội dung nghe nhìn:Phải đứng thứ hai và
Content-Type
phải khớp với một loại MIME nội dung đa phương tiện được chấp nhận của phương thức.
Xem tài liệu tham khảo API để biết danh sách các loại MIME nội dung đa phương tiện được chấp nhận và giới hạn kích thước cho các tệp đã tải lên.
Lưu ý: Để chỉ tạo hoặc cập nhật phần siêu dữ liệu mà không tải dữ liệu liên quan lên, bạn chỉ cần gửi yêu cầu POST
hoặc PUT
đến điểm cuối tài nguyên chuẩn: https://www.googleapis.com/farm/v1/animals
Ví dụ: Tải lên nhiều phần
Ví dụ bên dưới cho thấy một yêu cầu tải lên nhiều phần cho Farm API hư cấu.
POST /upload/farm/v1/animals?uploadType=multipart HTTP/1.1 Host: www.googleapis.com Authorization: Bearer your_auth_token Content-Type: multipart/related; boundary=foo_bar_baz Content-Length: number_of_bytes_in_entire_request_body --foo_bar_baz Content-Type: application/json; charset=UTF-8 { "name": "Llama" } --foo_bar_baz Content-Type: image/jpeg JPEG data --foo_bar_baz--
Nếu yêu cầu thành công, máy chủ sẽ trả về mã trạng thái HTTP 200 OK
cùng với bất kỳ siêu dữ liệu nào:
HTTP/1.1 200 Content-Type: application/json { "name": "Llama" }
Tải lên tiếp nối
Để tải các tệp dữ liệu lên một cách đáng tin cậy, bạn có thể sử dụng giao thức tải lên tiếp nối. Giao thức này cho phép bạn tiếp tục hoạt động tải lên sau các lỗi giao tiếp làm gián đoạn luồng dữ liệu. Điều này cực kỳ hữu ích nếu bạn đang truyền các tệp lớn với khả năng cao sẽ gặp phải các vấn đề gián đoạn mạng hoặc một số lỗi đường truyền khác, chẳng hạn như khi tải lên từ ứng dụng dành cho thiết bị di động. Điều này cũng có thể làm giảm việc sử dụng băng thông trong trường hợp mạng bị lỗi, vì bạn không phải tải lại từ đầu các tệp lớn.
Các bước để sử dụng tính năng tải lên tiếp nối:
- Bắt đầu một phiên hoạt động có thể tiếp tục. Tạo một yêu cầu khởi tạo cho URI tải lên chứa siêu dữ liệu, nếu có.
- Lưu URI phiên có thể tiếp tục. Lưu URI phiên được trả về trong phản hồi của yêu cầu ban đầu; bạn sẽ sử dụng URI này cho các yêu cầu còn lại trong phiên này.
- Tải tệp lên. Gửi tệp nội dung đa phương tiện đến URI của phiên có thể tiếp nối.
Ngoài ra, các ứng dụng sử dụng tính năng tải lên tiếp nối cần có mã để tiếp tục quá trình tải lên bị gián đoạn. Nếu quá trình tải lên bị gián đoạn, hãy tìm hiểu lượng dữ liệu đã nhận được, sau đó tiếp tục tải lên tại thời điểm bị gián đoạn đó.
Lưu ý: URI tải lên sẽ hết hạn sau một tuần.
Bước 1: Bắt đầu một phiên có thể tiếp tục
Để bắt đầu quá trình tải lên tiếp tục, hãy tạo yêu cầu POST
hoặc PUT
đến URI /upload của phương thức, đồng thời thêm tham số truy vấn uploadType=resumable
, ví dụ:
POST https://www.googleapis.com/upload/farm/v1/animals?uploadType=resumable
Đối với yêu cầu khởi tạo này, nội dung phải để trống hoặc chỉ chứa siêu dữ liệu; bạn sẽ chuyển nội dung thực tế của tệp bạn muốn tải lên trong các yêu cầu tiếp theo.
Sử dụng các tiêu đề HTTP dưới đây với yêu cầu khởi tạo:X-Upload-Content-Type
. Đặt thành loại MIME nội dung đa phương tiện của dữ liệu tải lên sẽ được truyền trong các yêu cầu tiếp theo.X-Upload-Content-Length
. Thiết lập thành số byte của dữ liệu tải lên sẽ được truyền trong các yêu cầu tiếp theo. Nếu không xác định được độ dài tại thời điểm tạo yêu cầu này, bạn có thể bỏ qua tiêu đề này.- Nếu có chứa siêu dữ liệu:
Content-Type
. Đặt theo loại dữ liệu của siêu dữ liệu. Content-Length
. Đặt thành số byte được cung cấp trong phần nội dung của yêu cầu ban đầu này. Không bắt buộc nếu bạn đang sử dụng mã hoá chuyển dữ liệu chia nhỏ.
Xem tài liệu tham khảo API để biết danh sách các loại MIME nội dung đa phương tiện được chấp nhận và giới hạn kích thước cho các tệp đã tải lên.
Ví dụ: Yêu cầu khởi tạo phiê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 cho Farm API hư cấu.
POST /upload/farm/v1/animals?uploadType=resumable HTTP/1.1 Host: www.googleapis.com Authorization: Bearer your_auth_token Content-Length: 38 Content-Type: application/json; charset=UTF-8 X-Upload-Content-Type: image/jpeg X-Upload-Content-Length: 2000000 { "name": "Llama" }
Lưu ý: Đối với yêu cầu cập nhật phiên khởi tạo có thể tiếp tục mà không có siêu dữ liệu, hãy để trống phần nội dung của yêu cầu và đặt tiêu đề Content-Length
thành 0
.
Phần tiếp theo sẽ mô tả cách xử lý các yêu cầu này.
Bước 2: Lưu URI phiên có thể tiếp tục
Nếu yêu cầu khởi tạo phiên thành công, máy chủ API sẽ phản hồi bằng mã trạng thái HTTP 200 OK
. Ngoài ra, API này còn cung cấp tiêu đề Location
chỉ định URI phiên có thể tiếp tục của bạn. Tiêu đề Location
như trong ví dụ bên dưới bao gồm phần tham số truy vấn upload_id
cung cấp mã tải lên duy nhất để sử dụng cho phiên này.
Ví dụ: Phản hồi khởi tạo phiên có thể tiếp tục
Dưới đây là phản hồi cho yêu cầu ở Bước 1:
HTTP/1.1 200 OK Location: https://www.googleapis.com/upload/farm/v1/animals?uploadType=resumable&upload_id=xa298sd_sdlkj2 Content-Length: 0
Giá trị của tiêu đề Location
, như minh hoạ trong phản hồi ví dụ ở trên, là URI phiên mà bạn sẽ dùng làm điểm cuối HTTP để tải tệp lên hoặc truy vấn trạng thái tải lên thực tế.
Sao chép và lưu URI phiên để 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
Để tải tệp lên, hãy gửi yêu cầu PUT
đến URI tải lên mà bạn nhận được ở bước trước. Định dạng của yêu cầu tải lên sẽ là:
PUT session_uri
Những tiêu đề HTTP cần sử dụng khi tạo các yêu cầu tiếp tục tải tệp lên bao gồm Content-Length
. Đặt thành số byte tương ứng mà bạn đang tải lên trong yêu cầu này, thường là kích thước tệp tải lên.
Ví dụ: Yêu cầu tải tệp có thể tiếp tục lên
Đây là yêu cầu tiếp tục để tải lên toàn bộ tệp JPEG 2.000.000 byte cho ví dụ hiện tại.
PUT https://www.googleapis.com/upload/farm/v1/animals?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1 Content-Length: 2000000 Content-Type: image/jpeg bytes 0-1999999
Nếu yêu cầu thành công thì máy chủ sẽ phản hồi bằng một HTTP 201 Created
, cùng với bất kỳ siêu dữ liệu nào liên kết với tài nguyên này. Nếu yêu cầu ban đầu của phiên có thể tiếp tục là PUT
, thì để cập nhật tài nguyên hiện có, phản hồi thành công sẽ là 200 OK
cùng với bất kỳ siêu dữ liệu nào được liên kết với tài nguyên này.
Nếu yêu cầu tải lên bị gián đoạn hoặc nếu bạn nhận được HTTP 503 Service Unavailable
hay bất kỳ phản hồi 5xx
nào khác từ máy chủ, hãy làm theo quy trình tiếp tục quá trình tải lên bị gián đoạn.
Tải tệp lên theo nhiều đoạn
Với quá trình tải lên tiếp nối, bạn có thể chia một tệp thành nhiều phần và gửi một loạt yêu cầu để tải lên từng phần theo trình tự. Đây không phải là phương pháp ưu tiên vì có chi phí hiệu suất liên quan đến các yêu cầu bổ sung và thường không cần thiết. Tuy nhiên, bạn có thể cần phải sử dụng tính năng phân đoạn dữ liệu để giảm lượng dữ liệu được chuyển trong một yêu cầu duy nhất. Điều này rất hữu ích khi có giới hạn thời gian cố định cho từng yêu cầu, cũng như đối với một số loại yêu cầu nhất định của Google App Engine. API này cũng cho phép bạn làm những việc như cung cấp chỉ báo tiến trình tải lên cho các trình duyệt cũ không hỗ trợ tiến trình tải lên theo mặc định.
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ị chấm dứt trước khi nhận được phản hồi, hoặc nếu bạn nhận được phản hồi HTTP 503 Service Unavailable
từ máy chủ, thì bạn cần tiếp tục quá trình tải lên bị gián đoạn. Để thực hiện việc này:
- Yêu cầu trạng thái. Truy vấn trạng thái hiện tại của quá trình tải lên bằng cách gửi một yêu cầu
PUT
trống cho URI tải lên. Đối với yêu cầu này, tiêu đề HTTP phải bao gồm tiêu đềContent-Range
cho biết vị trí hiện tại trong tệp là không xác định. Ví dụ: đặtContent-Range
thành*/2000000
nếu tổng chiều dài tệp của bạn là 2.000.000. Nếu bạn không biết kích thước đầy đủ của tệp, hãy đặtContent-Range
thành*/*
.Lưu ý: Bạn có thể yêu cầu trạng thái giữa các phần, chứ không chỉ khi quá trình tải lên bị gián đoạn. Điều này hữu ích trong những trường hợp bạn muốn hiển thị chỉ báo tiến trình tải lên cho các trình duyệt cũ.
- Lấy số byte tương ứng đã tải lên. Xử lý phản hồi trong truy vấn trạng thái. Máy chủ sử dụng tiêu đề
Range
trong phản hồi để chỉ định số byte đã nhận được cho đến hiện tại. Ví dụ: tiêu đềRange
của0-299999
cho biết đã nhận 300.000 byte đầu tiên của tệp. - Tải dữ liệu còn lại lên. Cuối cùng, giờ bạn đã biết vị trí để tiếp tục yêu cầu, hãy gửi dữ liệu còn lại hoặc phân đoạn hiện tại. Xin lưu ý rằng bạn cần coi dữ liệu còn lại là một đoạn riêng biệt trong cả hai trường hợp. Vì vậy, bạn cần gửi tiêu đề
Content-Range
khi tiếp tục tải lên.
Ví dụ: Tiếp tục quá trình tải lên bị gián đoạn
1) Yêu cầu trạng thái tải lên.
Yêu cầu sau đây sử dụng tiêu đề Content-Range
để cho biết vị trí hiện tại trong tệp 2.000.000 byte là không xác định.
PUT {session_uri} HTTP/1.1 Content-Length: 0 Content-Range: bytes */2000000
2) Trích xuất số byte đã tải lên từ thời điểm phản hồi.
Phản hồi của máy chủ sử dụng tiêu đề Range
để cho biết đã nhận được 43 byte đầu tiên của tệp tính đến hiện tại. Sử dụng giá trị trên của tiêu đề Range
để xác định vị trí bắt đầu quá trình tải lên tiếp tục.
HTTP/1.1 308 Resume Incomplete Content-Length: 0 Range: 0-42
Lưu ý: Phản hồi trạng thái có thể là 201 Created
hoặc 200 OK
nếu quá trình tải lên hoàn tất. Điều này có thể xảy ra nếu bị mất kết nối sau khi tất cả byte được tải lên, nhưng trước khi ứng dụng nhận được phản hồi từ máy chủ.
3) Tiếp tục quá trình tải lên từ điểm dừng lại.
Yêu cầu sau đây sẽ tiếp tục quá trình tải lên bằng cách gửi các byte còn lại của tệp, bắt đầu từ byte 43.
PUT {session_uri} HTTP/1.1 Content-Length: 1999957 Content-Range: bytes 43-1999999/2000000 bytes 43-1999999
Các phương pháp hay nhất
Khi tải nội dung nghe nhìn lên, bạn nên nắm được một số phương pháp hay nhất liên quan đến việc xử lý lỗi.
- Tiếp tục hoặc thử tải lại các tệp tải lên không thành công do gián đoạn kết nối hoặc bất kỳ lỗi
5xx
nào, bao gồm:500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
- Sử dụng chiến lược thời gian đợi luỹ thừa nếu có bất kỳ lỗi máy chủ
5xx
nào bị trả về khi tiếp tục hoặc thử lại các yêu cầu tải lên. Những lỗi này có thể xảy ra nếu máy chủ bị quá tải. Thuật toán thời gian đợi luỹ thừa có thể giúp giảm bớt các sự cố này trong giai đoạn có lượng lớn yêu cầu hoặc lưu lượng truy cập mạng lớn. - Bạn không nên xử lý các loại yêu cầu khác bằng thuật toán thời gian đợi luỹ thừa, nhưng vẫn có thể thử lại một số yêu cầu. Khi thử lại các yêu cầu này, hãy giới hạn số lần thử lại. Ví dụ: mã của bạn có thể giới hạn tối đa 10 lần thử lại trước khi báo cáo lỗi.
- Xử lý các lỗi
404 Not Found
và410 Gone
khi thực hiện quá trình tải lên có thể tiếp tục, bằng cách khởi động lại toàn bộ quá trình tải lên từ đầu.
Thuật toán thời gian đợi luỹ thừa
Thuật toán thời gian đợi luỹ thừa là một chiến lược xử lý lỗi tiêu chuẩn cho các ứng dụng mạng, trong đó ứng dụng khách định kỳ thử lại một yêu cầu không thành công trong khoảng thời gian tăng dần. Nếu một lượng lớn yêu cầu hoặc lưu lượng truy cập mạng lớn khiến máy chủ trả về lỗi, thì thời gian đợi luỹ thừa có thể là một chiến lược tốt để xử lý những lỗi đó. Ngược lại, giải pháp này không phải là chiến lược phù hợp để xử lý các lỗi không liên quan đến lưu lượng truy cập mạng hoặc thời gian phản hồi, chẳng hạn như thông tin xác thực uỷ quyền không hợp lệ hoặc lỗi không tìm thấy tệp.
Được sử dụng đúng cách, thuật toán thời gian đợi luỹ thừa tăng hiệu quả sử dụng băng thông, giảm số lượng yêu cầu cần thiết để nhận được phản hồi thành công và tối đa hoá thông lượng yêu cầu trong các môi trường đồng thời.
Quy trình triển khai thuật toán thời gian đợi lũy thừa đơn giản như sau:
- Tạo một yêu cầu đối với API.
- Nhận phản hồi
HTTP 503
, cho biết bạn nên thử lại yêu cầu. - Đợi 1 giây + random_number_milliseconds rồi thử lại yêu cầu.
- Nhận phản hồi
HTTP 503
, cho biết bạn nên thử lại yêu cầu. - Đợi 2 giây + random_number_milliseconds rồi thử lại yêu cầu.
- Nhận phản hồi
HTTP 503
, cho biết bạn nên thử lại yêu cầu. - Đợi 4 giây + random_number_milliseconds rồi thử lại yêu cầu.
- Nhận phản hồi
HTTP 503
, cho biết bạn nên thử lại yêu cầu. - Đợi 8 giây + random_number_milliseconds rồi thử lại yêu cầu.
- Nhận phản hồi
HTTP 503
, cho biết bạn nên thử lại yêu cầu. - Đợi 16 giây + random_number_milliseconds rồi thử lại yêu cầu.
- Dừng. Báo cáo hoặc ghi lại một lỗi.
Trong luồng trên, random_number_milliseconds là một số mili giây ngẫu nhiên nhỏ hơn hoặc bằng 1000. Điều này là cần thiết vì việc áp dụng độ trễ ngẫu nhiên nhỏ giúp phân phối tải đồng đều hơn và tránh khả năng làm hỏng máy chủ. Giá trị của random_number_mili giây phải được xác định lại sau mỗi lần chờ.
Lưu ý: Thời gian chờ luôn là (2 ^ n) + random_number_mili giây, trong đó n là một số nguyên tăng đơn điệu ban đầu được xác định là 0. Số nguyên n được tăng thêm 1 cho mỗi lần lặp (mỗi yêu cầu).
Thuật toán sẽ được đặt để kết thúc khi n là 5. Mức trần này ngăn ứng dụng thử lại vô hạn và dẫn đến tổng độ trễ khoảng 32 giây trước khi một yêu cầu được coi là "lỗi không thể khôi phục". Bạn có thể thử lại nhiều lần hơn, đặc biệt là khi quá trình tải lên trong thời gian dài đang diễn ra. Chỉ cần đảm bảo giới hạn thời gian thử lại ở mức hợp lý, chẳng hạn như dưới 1 phút.