Lựa chọn tải lên
API Android Over The Air cho phép bạn tải dữ liệu gói lên để tạo tài nguyên Package (Gói) mới. Đây là Các gói OTA có thể liên kết với một hoặc nhiều cấu hình để có thể phân phối bản cập nhật cho các thiết bị.
Chúng tôi cung cấp tệp nhị phân cho Linux và Windows để hỗ trợ quá trình tải gói có thể tiếp tục lên mà bạn được tự do sử dụng thay vì phải triển khai các giao thức được mô tả bên dưới. Nếu bạn muốn tìm hiểu thêm tích hợp, vui lòng sử dụng một trong các giao thức được mô tả bên dưới.
Linux
Windows
Tải ứng dụng tải lên Android Over The Air API v1 cho Windows.
Để sử dụng tài khoản đó, trước tiên, bạn cần tạo một tài khoản dịch vụ và lấy tệp khoá JSON cho tài khoản đó.
Vui lòng xem hướng dẫn tạo tài khoản của chúng tôi tại đây.
Sau khi có tệp nhị phân và tệp khoá, bạn có thể chạy tệp đó bằng các tuỳ chọn dòng lệnh để chỉ định
tệp khoá, quá trình triển khai và gói bạn đang tải lên. Vui lòng sử dụng --help
để xem tất cả các lựa chọn.
Tải giao thức lên
Bạn có thể gửi yêu cầu tải lên theo bất kỳ cách nào sau đây.
Hãy chỉ định phương thức mà bạn đang sử dụng với tiêu đề của yêu cầu X-Goog-Upload-Protocol
.
- Tải nhiều phần lên:
X-Goog-Upload-Protocol: multipart
. Để chuyển nhanh chóng tệp nhỏ hơn 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:
X-Goog-Upload-Protocol: resumable
. Để quá trình chuyển ổn định, đặc biệt quan trọng với những tệp. Với phương thức này, bạn sẽ sử dụng yêu cầu khởi tạo phiên và có thể bao gồm siêu dữ liệu nếu muốn. Đây là chiến lược hay để sử dụng cho hầu hết vì nó cũng hoạt động với các tệp nhỏ hơn và chỉ cần một yêu cầu HTTP bổ sung cho mỗi lượt tải lên.
Tải nhiều phần lên
Đây là lựa chọn phù hợp nếu dữ liệu bạn gửi ít đủ để tải lên lại toàn bộ nếu không kết nối được.
Để sử dụng tính năng tải lên nhiều phần, hãy gửi yêu cầu POST
tới /upload/package
URI rồi đặt X-Goog-Upload-Protocol
thành multipart
.
Những tiêu đề HTTP cấp cao nhất để sử dụng khi tạo một yêu cầu tải lên nhiều phần bao gồm:
Content-Type
. Đặt thành nhiều phần/liên quan và bao gồm chuỗi ranh giới 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.
Nội dung của yêu cầu được định dạng là nội dung multipart/related
loại [RFC2387] và chứa chính xác hai 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 đứng trước và
Content-Type
phải làapplication/json
. - Phần nội dung đa phương tiện: Phải đứng thứ hai, và
Content-Type
phải làapplication/zip
.
Ví dụ: Tải nhiều phần lên
Ví dụ bên dưới cho thấy một yêu cầu tải nhiều phần lên cho API Android Over The Air.
POST /upload/package HTTP/1.1 Host: androidovertheair.googleapis.com Authorization: Bearer your_auth_token Content-Type: multipart/related; boundary=BOUNDARY Content-Length: number_of_bytes_in_entire_request_body --BOUNDARY Content-Type: application/json; charset=UTF-8 {"deployment": "id", "package_title": "title" } --BOUNDARY Content-Type: application/zip; charset=UTF-8 Package ZIP --BOUNDARY--
Nếu yêu cầu thành công, máy chủ sẽ trả về mã trạng thái HTTP 200 OK
HTTP/1.1 200
Một cách để dễ dàng thực hiện việc này là sử dụng curl và oauth2l. Dưới đây là yêu cầu mẫu giả định rằng bạn đang sử dụng khoá dịch vụ (xem uỷ quyền cách thức để biết thêm thông tin).
Ví dụ về yêu cầu curl
JSON={"deployment": "id", "package_title": "title" } SERVICE_KEY_FILE=path to your service key json file curl \ -H "$(./oauth2l header --json $SERVICE_KEY_FILE android_partner_over_the_air)" \ -H "Host: androidovertheair.googleapis.com" \ -H "X-Goog-Upload-Protocol: multipart" \ -H "Content-Type: multipart/form-data" \ -F "json=$JSON;type=application/json" \ -F "data=@update.zip;type=application/zip" \ androidovertheair.googleapis.com/upload/package
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 thao tác tải lên sau khi lỗi giao tiếp làm gián đoạn luồng dữ liệu. Nó đặc biệt hữu ích nếu bạn đang chuyển các tệp lớn và có khả năng bị gián đoạn mạng hoặc một số lỗi truyền khác ở mức cao, chẳng hạn như khi tải lên từ ứng dụng khách dành cho thiết bị di động. Nó cũng có thể giảm mức sử dụng băng thông trong trường hợp xảy ra lỗi mạng vì bạn sẽ không phải khởi động lại quá trình tải tệp lớn lên từ đầu.
Giao thức tải lên tiếp nối sử dụng một số lệnh:
- Bắt đầu một phiên hoạt động có thể tiếp tục. Tạo yêu cầu ban đầu cho URI tải lên bao gồm siêu dữ liệu và thiết lập vị trí tải lên duy nhất có thể tiếp tụ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 yêu cầu ban đầu; bạn sẽ sử dụng thông tin đó 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ất cả hoặc một phần của tệp ZIP đến URI phiên có thể tiếp tục.
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ó đoạn mã để tiếp tục quá trình tải lên bị gián đoạn. Nếu tệp tải lên bị gián đoạn, hãy tìm hiểu lượng dữ liệu đã được nhận thành công, sau đó tiếp tục tải lên bắt đầu từ thời điểm đó.
Lưu ý: URI tải lên sẽ hết hạn sau 3 ngày.
Bước 1: Bắt đầu một phiên hoạt động có thể tiếp tục
Để bắt đầu quá trình tải lên tiếp nối, hãy gửi yêu cầu POST
đến /upload/package
URI rồi đặt X-Goog-Upload-Protocol
thành resumable
.
Đối với yêu cầu khởi tạo này, phần nội dung chỉ được chứa siêu dữ liệu; bạn sẽ chuyển dữ liệu nội dung 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-Goog-Upload-Header-Content-Type
. Đây là loại nội dung của tệp đang được tải lên và phải được đặt thànhapplication/zip
.X-Goog-Upload-Command
. Đặt thànhstart
X-Goog-Upload-Header-Content-Length
. Đặt 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.Content-Type
. Đây là loại nội dung của siêu dữ liệu và phải được đặt thànhapplication/json
.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.
Ví dụ: Yêu cầu khởi tạo phiê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 cho API Android Over The Air.
POST /upload/package HTTP/1.1 Host: android/over-the-air.googleapis.com Authorization: Bearer your_auth_token Content-Length: 38 Content-Type: application/json; charset=UTF-8 X-Goog-Upload-Command: start X-Goog-Upload-Header-Content-Type: application/zip X-Goog-Upload-Header-Content-Length: 2000000 {"deployment": "id", "package_title": "title" }
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, phần này còn cung cấp tiêu đề X-Goog-Upload-URL
chỉ định URI phiên có thể tiếp tục của bạn.
Tiêu đề X-Goog-Upload-URL
như trong ví dụ bên dưới bao gồm 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. Phản hồi này cũng chứa X-Goog-Upload-Status
và giá trị này sẽ là active
nếu yêu cầu tải lên hợp lệ và được chấp nhận. Trạng thái này có thể là final
nếu nội dung tải lên bị từ chối.
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 X-Goog-Upload-Status: active X-Goog-Upload-URL: androidovertheair.googleapis.com/?upload_id=xa298sd_sdlkj2 Content-Length: 0
Giá trị của tiêu đề X-Goog-Upload-URL
như trong phản hồi mẫu ở trên là
URI phiên mà bạn sẽ dùng làm điểm cuối HTTP để tải tệp thực tế lên hoặc truy vấn trạng thái tải lên.
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 POST
tới URI tải lên mà bạn nhận được trong
bước trước đó. Định dạng của yêu cầu tải lên sẽ là:
POST session_uri
Tiêu đề HTTP cần sử dụng khi tạo yêu cầu tải lên tệp tiếp tục bao gồm:
Content-Length
. Đặt thuộc tính này thành số byte 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.X-Goog-Upload-Command
. Đặt giá trị này thànhupload
vàfinalize
.X-Goog-Upload-Offset
. Thao tác này đã chỉ định độ lệch mà các byte sẽ được ghi. Xin lưu ý rằng khách hàng phải tải lên byte theo tuần tự.
Ví dụ: Yêu cầu tải tệp có thể tiếp nối lên
Đây là yêu cầu có thể tiếp tục để tải lên toàn bộ tệp ZIP 2.000.000 byte cho ví dụ hiện tại.
POST /?upload_id=xa298sd_sdlkj2 HTTP/1.1 Host: androidovertheair.googleapis.com X-Goog-Upload-Protocol: resumable X-Goog-Upload-Command: upload, finalize X-Goog-Upload-Offset: 0 Content-Length: 2000000 Content-Type: application/zip bytes 0-1999999
Nếu yêu cầu thành công, máy chủ sẽ phản hồi bằng một HTTP 200 Ok
.
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ột HTTP 503 Service Unavailable
hoặc
phản hồi 5xx
khác từ máy chủ, hãy làm theo quy trình đã nêu trong phần tiếp tục quá trình tải lên bị gián đoạn.
Tải tệp lên theo từng phần
Với tính năng tải lên tiếp nối, bạn có thể chia 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ì chi phí hiệu suất liên quan đến các yêu cầu bổ sung và đây là
thường là không cần thiết. Khách hàng nên tải tất cả các byte còn lại của tải trọng lên và
đưa lệnh finalize
vào mỗi lệnh upload
.
Tuy nhiên, bạn có thể cần phải sử dụng tính năng phân đoạn để giảm lượng dữ liệu được truyền trong bất kỳ một yêu cầu duy nhất. API này cũng cho phép bạn làm những việc như cung cấp chỉ báo về 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:
- Trạng thái của yêu cầu. 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 cho URI tải lên
với
X-Goog-Upload-Command
được đặt thànhquery
.Lưu ý: Bạn có thể hỏi trạng thái giữa các đoạn chứ không chỉ khi quá trình tải lên bị gián đoạn. Đây là hữu ích, chẳng hạn như khi bạn muốn hiển thị chỉ báo về tiến trình tải lên cho các trình duyệt cũ.
- Nhận số byte đã 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 đề
X-Goog-Upload-Size-Received
trong phản hồi để chỉ định số byte đã nhận được tính đến thời điểm hiện tại. - 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 đoạn hiện tại. Xin lưu ý rằng trong cả hai trường hợp, bạn cần coi dữ liệu còn lại là một phân đoạn riêng biệt
bạn cần đặt tiêu đề
X-Goog-Upload-Offset
thành độ lệch thích hợp 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.
POST /?upload_id=xa298sd_sdlkj2 HTTP/1.1 Host: androidovertheair.googleapis.com X-Goog-Upload-Command: query
Tương tự như với tất cả các lệnh, máy khách phải kiểm tra tiêu đề X-Goog-Upload-Status
trong phản hồi HTTP của một lệnh truy vấn.
Nếu có tiêu đề và giá trị không phải là active
, thì quá trình tải lên đã bị chấm dứt.
2) Trích xuất số byte đã tải lên tính đến thời điểm hiện tại của phản hồi.
Phản hồi của máy chủ sử dụng tiêu đề X-Goog-Upload-Size-Received
để cho biết rằng
đã nhận được 43 byte đầu tiên của tệp cho đến thời điểm này.
HTTP/1.1 200 OK X-Goog-Upload-Status: active X-Goog-Upload-Size-Received: 42
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 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.
POST /?upload_id=xa298sd_sdlkj2 HTTP/1.1 Host: androidovertheair.googleapis.com X-Goog-Upload-Command: upload, finalize Content-Length: 1999957 X-Goog-Upload-Offset: 43 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 tìm hiểu 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ên lại nhưng không thành công do kết nối bị gián đoạn 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 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 loại sự cố này trong khoảng thời gian có khối lượng yêu cầu lớn hoặc lưu lượng truy cập mạng lớn. - Các loại yêu cầu khác không được xử lý bằng thuật toán thời gian đợi luỹ thừa, nhưng bạn vẫn có thể thử lại một số loại yêu cầu trong số đó. Khi thử lại các yêu cầu này, hãy giới hạn số lần bạ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ý lỗi
404 Not Found
khi thực hiện quá trình tải lên tiếp nối bằng cách bắt đầu 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ý sai số chuẩn cho các ứng dụng mạng, trong đó ứng dụng thực hiện thử lại định kỳ 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ì thuật toán thời gian đợi luỹ thừa có thể là một chiến lược hiệu quả để xử lý những lỗi đó. Ngược lại, đây không phải là một chiến lược phù hợp để xử lý các lỗi không liên quan đến số lượng 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 giúp 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 để có được phản hồi thành công và tối đa hoá thông lượng của các yêu cầu trong 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 quy trình trên, random_number_milliseconds là một số mili giây ngẫu nhiên nhỏ hơn hoặc bằng 1.000. Điều này là cần thiết, vì việc đưa ra độ trễ ngẫu nhiên nhỏ sẽ giúp phân phối tải đồng đều hơn và tránh khả năng làm máy chủ bị gián đoạn. Giá trị của ngẫu nhiên_number_milliseconds 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_milliseconds, 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 khách hàng thử lại vô hạn và dẫn đến tổng thời gian trễ khoảng 32 giây trước khi yêu cầu bị coi là "lỗi không thể khôi phục". Bạn có thể thử lại nhiều lần nhất có thể, đặc biệt là khi quá trình tải lên có thời lượng dài đang diễn ra; bạn chỉ cần nhớ giới hạn độ trễ thử lại ở mức hợp lý, chẳng hạn như dưới một phút.