上傳選項
Android Over The Air API 可讓您上傳套件資料，建立新的套件資源。這些 可與一或多項設定建立關聯的 OTA 套件，以便傳送更新 也不必在意裝置之間
我們提供 Linux 和 Windows 的二進位檔案，協助您進行支援續傳的套件上傳作業 無須實作以下所述的通訊協定。如果你想進一步瞭解 整合時，請使用以下其中一種通訊協定。
Linux
Windows
如要使用，您必須先建立服務帳戶，並取得該帳戶的 JSON 金鑰檔案。
請參閱這裡的建立帳戶指南。
取得二進位檔和金鑰檔案後，您就可以使用指令列選項指定二進位檔和金鑰檔案，以便指定
您的金鑰檔案、您的部署作業和上傳的套件。請使用 --help
即可查看所有選項
上傳通訊協定
您可以透過下列任何一種方式提出上傳要求，
請使用 X-Goog-Upload-Protocol 要求標頭指定您要使用的方法。
- 多部分上傳作業：
X-Goog-Upload-Protocol: multipart。如要快速轉移 較小的檔案和中繼資料；可轉移檔案以及描述該檔案的中繼資料，且所有作業都是在單一要求中完成。 - 支援續傳的上傳作業：
X-Goog-Upload-Protocol: resumable。需要可靠的移轉作業，尤其是大型企業 檔案。透過這個方法，您可以使用工作階段啟動要求，其中可以選擇是否包含中繼資料。對於大多數客戶而言 也適用於較小的檔案，只需每次上傳額外一次 HTTP 要求即可。
多部分上傳
如果您要傳送的資料不大，建議選擇這個方式 ，在連線失敗時重新完整上傳所有影片。
如要使用多部分上傳作業，請向 /upload/package 發出 POST 要求
URI，並將 X-Goog-Upload-Protocol 設為 multipart。
提出多部分上傳要求時，要使用的頂層 HTTP 標頭包括：
Content-Type。設為多部分/相關並納入您要的邊界字串 來識別請求的各個部分Content-Length。設定為要求主體中的位元組總數。
要求主體的格式為 multipart/related 內容
類型 [RFC2387]，其中包含兩個部分。
這些部分是靠邊界字串來辨識的，而緊接在最後一個邊界字串後面會有兩個連字號。
多部分要求的每個部分都需要一個額外的 Content-Type 標頭：
- 中繼資料部分：第一順位，且
Content-Type必須是application/json。 - 媒體部分：第二順位，且
Content-Type必須是application/zip。
範例：多部分上傳作業
以下範例顯示 Android Over The Air API 的多部分上傳要求。
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--
如果要求成功，伺服器會傳回 HTTP 200 OK 狀態碼
HTTP/1.1 200
最簡單的方法是使用 curl 和 oauth2l。下方為要求範例 假設您使用服務金鑰 (請參閱 授權方式以取得更多資訊)。
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
支援續傳的上傳作業
如要更可靠地上傳資料檔案，可以使用支援續傳的上傳通訊協定。這個通訊協定允許 在通訊問題導致資料傳輸過程中斷後，讓您繼續上傳作業。這項服務 如要傳輸大型檔案以及造成網路中斷的可能性 或部分其他傳輸錯誤 (例如從行動用戶端應用程式上傳時)。這項服務 也能在網路發生問題時降低頻寬用量，因為您無須這麼做 從頭開始上傳大型檔案。
支援續傳的上傳通訊協定會使用多個指令：
- 啟動可續傳的工作階段。對包含 中繼資料並建立可續傳的不重複上傳位置。
- 儲存支援續傳的工作階段 URI。請儲存 初始要求的回應；在工作階段的剩餘要求中
- 上傳檔案。將所有或部分 ZIP 檔案傳送至可續傳的工作階段 URI。
此外，使用可續傳上傳功能的應用程式，必須擁有繼續執行中斷的上傳作業小節中的程式碼。如果上傳內容 請找出已成功接收多少資料，然後從那一刻開始繼續上傳作業。
注意： 上傳 URI 會在 3 天後失效。
步驟 1：啟動可續傳的工作階段
如要啟動支援續傳的上傳作業，請向 /upload/package 發出 POST 要求
URI，並將 X-Goog-Upload-Protocol 設為 resumable。
這個啟動要求的主體只能包含中繼資料；並實際移轉 內容。
請將下列 HTTP 標頭與初始要求搭配使用：X-Goog-Upload-Header-Content-Type。這是上傳檔案的內容類型，必須設為application/zip。X-Goog-Upload-Command。設為「start」X-Goog-Upload-Header-Content-Length。設定為要在後續要求中傳輸的上傳資料位元組數。 如果提出這項要求時無法得知長度，您可以省略這個標頭。Content-Type。這是中繼資料的內容類型，必須設為application/json。Content-Length。設定為這項初始要求的主體中提供的位元組數。
範例：可續傳工作階段啟動要求
以下範例說明如何為 Android Over The Air API 啟動支援續傳的工作階段。
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" }
下一節將說明如何處理回應。
步驟 2：儲存可續傳的工作階段 URI
如果工作階段啟動要求成功，API 伺服器會傳回 HTTP 200 OK 狀態碼。
此外，API 還提供用於指定可續傳工作階段 URI 的 X-Goog-Upload-URL 標頭。
如以下範例所示，X-Goog-Upload-URL 標頭包含 upload_id 查詢參數
部分，為這個工作階段提供不重複的上傳 ID。回應中也會包含 X-Goog-Upload-Status
標頭，如果上傳要求有效且已接受，則為 active。這個狀態可能是 final
系統會在上傳內容遭拒時提供這項資訊
範例：可續傳工作階段啟動作業的回應
以下是步驟 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
如以上回應範例所示，X-Goog-Upload-URL 標頭的值為
做為 HTTP 端點的工作階段 URI，用於執行實際檔案上傳或查詢上傳狀態。
請複製並儲存工作階段 URI，好讓您能夠在後續的要求中使用。
步驟 3：上傳檔案
如要上傳檔案，請傳送 POST 要求給您在
上一個步驟上傳要求的格式如下：
POST session_uri
提出可續傳檔案上傳要求時使用的 HTTP 標頭包括：
Content-Length。將其設為您要在這個要求中上傳的位元組數，這通常是上傳檔案大小。X-Goog-Upload-Command。將此設為upload和finalize。X-Goog-Upload-Offset。這會指定應寫入位元組的位移。請注意 必須依序上傳位元組。
範例：可續傳檔案上傳要求
以下是在目前範例中，上傳整個 2,000,000 個位元組 ZIP 檔案的可續傳要求。
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
如果要求成功，伺服器會回應 HTTP 200 Ok。
如果上傳要求中斷，或是收到 HTTP 503 Service Unavailable 或
伺服器的其他 5xx 回應，請按照「繼續執行中斷的上傳作業」一節所述的程序操作。
將檔案以區塊的形式上傳
透過支援續傳的上傳作業，您可將檔案分為多個區塊，然後傳送一系列要求，依序上傳每個區塊。
這不是偏好的方法，因為有一些效能成本與其他要求相關聯，因為
通常都不需要我們建議客戶上傳所有剩餘酬載的位元組，並且
在每個 upload 指令中加入 finalize 指令。
然而，您可能需要使用切割成區塊的方式，減少任何 單一請求。它還可讓您執行其他操作，例如為舊版瀏覽器提供上傳進度指示 不支援上傳進度
繼續執行中斷的上傳作業
如果上傳要求在收到回應之前終止，或您收到
伺服器傳回 HTTP 503 Service Unavailable 回應，請繼續執行中斷的上傳作業。步驟如下：
- 要求狀態：向上傳 URI 提出要求，查詢上傳作業的目前狀態
其中
X-Goog-Upload-Command設為query。附註：您可以在不同區塊的上傳作業之間提出狀態要求，而不是只能在上傳中斷時提出要求。這是 。
- 取得已上傳的位元組數：請處理狀態查詢的回應。伺服器會使用
回應中的
X-Goog-Upload-Size-Received標頭，以指定到目前為止已經收到多少位元組。 - 上傳剩餘的資料：最後，您已知道要在哪裡恢復要求後，請將
也就是剩餘的資料或當前區塊請注意，無論如何，其餘資料都需做為獨立區塊處理，因此
您在繼續執行上傳作業時，必須將
X-Goog-Upload-Offset標頭設為適當的偏移值。
範例：繼續執行中斷的上傳作業
1) 要求上傳狀態。
POST /?upload_id=xa298sd_sdlkj2 HTTP/1.1 Host: androidovertheair.googleapis.com X-Goog-Upload-Command: query
和所有指令一樣，用戶端必須在查詢指令的 HTTP 回應中檢查 X-Goog-Upload-Status 標頭。
如果有標頭，但值不是 active，則代表上傳作業已終止。
2) 從回應擷取當下已經上傳的位元組數。
伺服器的回應會使用 X-Goog-Upload-Size-Received 標頭來表示
目前接收檔案的前 43 個位元組。
HTTP/1.1 200 OK X-Goog-Upload-Status: active X-Goog-Upload-Size-Received: 42
3) 從上次離開的位置續傳上傳作業。
以下要求透過傳送檔案的剩餘位元組 (從位元組 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
最佳做法
當您要上傳媒體時，瞭解幾個與錯誤處理相關的最佳做法是很有用的。
- 請繼續或重新執行因連線中斷或因任何
5xx錯誤導致失敗的上傳作業，這些錯誤包括：500 Internal Server Error502 Bad Gateway503 Service Unavailable504 Gateway Timeout
- 如果您在繼續或重試上傳要求時，收到任何
5xx伺服器錯誤，請使用指數輪詢策略。如果伺服器超載，就可能發生這些錯誤。在發生大量要求或存在繁重網路流量期間，指數輪詢可協助減輕這一類問題。 - 其他類型的要求不應透過指數輪詢處理，但您仍可重試其中一些要求。重試這些要求時，請限制重試的次數。舉例來說，您的程式碼最多可以重試 10 次以下，然後再回報錯誤。
- 執行支援續傳的上傳作業時，請從頭開始徹底處理
404 Not Found錯誤。
指數輪詢
指數輪詢是網路應用程式的標準錯誤處理策略，用戶端可透過這種策略，以逐漸增加的次數定期重試失敗的要求。如果大量要求或繁重的網路流量導致伺服器傳回錯誤，指數輪詢就是處理這類錯誤的一種不錯的策略。相反地，處理與網路流量或回應時間相關的錯誤 (例如授權憑證無效或找不到檔案的錯誤) 並不是很有意義的策略。
在正確的使用之下，指數輪詢可以提升頻寬使用的效率，減少取得成功回應所需的要求數，並最大化並行環境中的要求總處理量。
實作簡單指數輪詢的流程如下：
- 對 API 提出要求。
- 收到指出您應該要重試要求的
HTTP 503回應。 - 等待 1 秒又 random_number_milliseconds 毫秒，然後重試要求。
- 收到指出您應該要重試要求的
HTTP 503回應。 - 等待 2 秒又 random_number_milliseconds 毫秒，然後重試要求。
- 收到指出您應該要重試要求的
HTTP 503回應。 - 等待 4 秒鐘 + random_number_milliseconds 毫秒，然後重試要求。
- 收到指出您應該要重試要求的
HTTP 503回應。 - 等待 8 秒鐘 + random_number_milliseconds 毫秒，然後重試要求。
- 收到指出您應該要重試要求的
HTTP 503回應。 - 等待 16 秒鐘 + random_number_milliseconds 毫秒，然後重試要求。
- 停止。報告或記錄錯誤。
在以上流程中，random_number_milliseconds 是小於或等於 1000 的隨機毫秒數。這是必要的，因為使用較小的隨機延遲有助於更平均分散負載，避免可能使伺服器發生衝擊。必須在每次等待之後重新定義 random_number_milliseconds 的值。
注意：等待時間一律是 (2 ^ n) + random_number_milliseconds，其中 n 是一開始定義為 0 的單調遞增整數。對於每個疊代 (每次要求)，整數 n 會遞增 1。
演算法已設定為會在 n 等於 5 時終止。這個上限可以防止用戶端一直重試下去，導致要求在總延遲時間達到約 32 秒之後，才會被視為「無法復原的錯誤」。您可以把重試次數的上限設高一點，尤其是在大型上傳作業執行的過程中；但請確保要把重試延遲時間的上限設定在合理的地方，例如短於一分鐘。