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

Để 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:

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

  1. 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.
  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 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.
  3. 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ành application/zip.
  • X-Goog-Upload-Command. Đặt thành start
  • 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à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 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:

  1. 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.
  2. X-Goog-Upload-Command. Đặt giá trị này thành uploadfinalize.
  3. 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:

  1. 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ành query.

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

  2. 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.
  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 đ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:

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