Tạo gói

Lựa chọn tải lên

API Android Over The Air cho phép bạn tải dữ liệu về gói lên để tạo tài nguyên 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 để bản cập nhật được phân phối đến các thiết bị.

Chúng tôi cung cấp một tệp nhị phân cho Linux và Windows để hỗ trợ việc tải gói tiếp tục lên mà bạn có thể tuỳ ý sử dụng thay vì triển khai các giao thức được mô tả dưới đây. Nếu bạn muốn tích hợp sâu hơn, vui lòng dùng một trong các giao thức được mô tả bên dưới.

Linux

Tải ứng dụng trình tải lên Android Over The Air API phiên bản 1 dành cho Linux.

Windows

Tải ứng dụng trình tải lên Android Over The Air API phiên bản 1 dành cho Windows.

Để sử dụng khoá này, 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á, tệp 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 tuỳ chọn.

Giao thức tải 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. Chỉ định phương thức 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 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: X-Goog-Upload-Protocol: resumable. Để chuyển dữ liệu một cách đáng tin cậy, đặc biệt là đối với các tệp lớn hơ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 phù hợp để sử dụng cho hầu hết các ứng dụng, vì nó cũng hoạt động trên các tệp nhỏ hơn, nhưng bạn sẽ phải tốn thêm 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 có kích thước nhỏ để có thể tải toàn bộ dữ liệu lên lại 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 đối với URI /upload/package và đặt X-Goog-Upload-Protocol thành 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.

Phần nội dung của yêu cầu được định dạng theo loại nội dung multipart/related [RFC2387] và chứa đúng 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:

  1. Phần siêu dữ liệu: Phải đứng trước và Content-Type phải là application/json.
  2. 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 lên nhiều phần

Ví dụ bên dưới cho thấy yêu cầu tải lên nhiều phầ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

Bạn có thể dễ dàng làm việc này bằng cách sử dụng curl và OAuth2l. Dưới đây là yêu cầu mẫu giả định bạn đang sử dụng một khoá dịch vụ (xem cách uỷ quyền của chúng tôi để 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 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. Cách này đặc biệt hữu ích nếu bạn đang chuyển các tệp có kích thước lớn và 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. Tính năng này cũng có thể giảm mức sử dụng băng thông trong trường hợp lỗi mạng vì bạn không phải bắt đầu 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:

  1. Bắt đầu một phiên hoạt động có thể tiếp tục. Gửi yêu cầu ban đầu đến URI tải lên, bao gồm siêu dữ liệu và thiết lập một vị trí tải lên duy nhất có thể tiếp tục.
  2. 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.
  3. Tải tệp lên. Gửi toàn bộ 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ó 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ừ 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 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 đến URI /upload/package và đặ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 nội dung thực tế của tệp mà 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ành application/zip.
  • X-Goog-Upload-Command. Đặt thành start
  • X-Goog-Upload-Header-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.
  • Content-Type. Đây là loại nội dung của siêu dữ liệu và phải được đặt thành application/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 cho thấy 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, API 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 phần tham số truy vấn upload_id nhằm cung cấp mã tải lên duy nhất để sử dụng cho phiên này. Phản hồi cũng chứa tiêu đề X-Goog-Upload-Status. Tiêu đề 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 tệp 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ư 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 một yêu cầu POST đế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à:

POST session_uri

Các tiêu đề HTTP cần sử dụng khi tạo yêu cầu tải tệp tiếp tục lên bao gồm:

  1. Content-Length. Thiết lập giá trị này 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.
  2. X-Goog-Upload-Command. Thiết lập thành upload và finalize.
  3. X-Goog-Upload-Offset. Giá trị này chỉ định độ lệch của byte cần được ghi. Xin lưu ý rằng ứng dụng phải tải byte lên theo tuần tự.
Ví dụ: Yêu cầu tải tệp có thể tiếp tục lên

Đây là một yêu cầu 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 phản hồi 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ì sẽ có chi phí hiệu suất liên quan đến các yêu cầu bổ sung và cách này thường không cần thiết. Ứng dụ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 với 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 dữ liệu để giảm lượng dữ liệu được chuyển trong bất kỳ yêu cầu nào. 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 những 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:

  1. 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 đưa ra yêu cầu cho URI tải lên với X-Goog-Upload-Command được đặt thành query.

    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 rất 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ũ.

  2. 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 đề X-Goog-Upload-Size-Received trong phản hồi để chỉ định số byte đã nhận được cho đến thời điểm hiện tại.
  3. 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 đặt tiêu đề X-Goog-Upload-Offset theo độ 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

Giống như tất cả các lệnh, ứng dụng phải kiểm tra tiêu đề X-Goog-Upload-Status trong phản hồi HTTP của 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ừ thời điểm 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 máy chủ đã nhận được 43 byte đầu tiên của tệp tính đến nay.

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 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.

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 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ý 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ý 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:

  1. Tạo một yêu cầu đối với API.
  2. Nhận phản hồi HTTP 503, cho biết bạn nên thử lại yêu cầu.
  3. Đợi 1 giây + random_number_milliseconds rồi thử lại yêu cầu.
  4. Nhận phản hồi HTTP 503, cho biết bạn nên thử lại yêu cầu.
  5. Đợi 2 giây + random_number_milliseconds rồi thử lại yêu cầu.
  6. Nhận phản hồi HTTP 503, cho biết bạn nên thử lại yêu cầu.
  7. Đợi 4 giây + random_number_milliseconds rồi thử lại yêu cầu.
  8. Nhận phản hồi HTTP 503, cho biết bạn nên thử lại yêu cầu.
  9. Đợi 8 giây + random_number_milliseconds rồi thử lại yêu cầu.
  10. Nhận phản hồi HTTP 503, cho biết bạn nên thử lại yêu cầu.
  11. Đợi 16 giây + random_number_milliseconds rồi thử lại yêu cầu.
  12. 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.