支援續傳的上傳作業

您可以使用支援 Google API 的可繼續上傳通訊協定，以更可靠的方式上傳影片。這個通訊協定可在網路中斷或其他傳輸失敗後，繼續上傳，讓您能在網路故障時節省時間和頻寬。

在下列情況中，使用支援續傳的上傳功能特別實用：

  • 您正在傳輸大型檔案。
  • 網路中斷的可能性很高。
  • 上傳來源來自具備低頻寬或不穩定的網際網路連線 (例如行動裝置)。

本指南說明應用程式透過可繼續上傳程序上傳影片的 HTTP 要求順序。本指南主要適用於無法使用 Google API 用戶端程式庫的開發人員，這些程式庫提供原生支援，支援續傳的上傳作業。事實上，請參閱《YouTube Data API - 上傳影片》指南，瞭解如何使用 Google API 用戶端程式庫 (Python) 透過可恢復的上傳程序上傳影片。

注意：您也可以查看使用啟用 HTTPS 記錄功能的任一 Google API 用戶端程式庫，查看針對可繼續上傳或任何其他 API 作業發出的一系列要求。例如，若要啟用 Python 的 HTTP 追蹤，請使用 httplib2 程式庫：

httplib2.debuglevel = 4

步驟 1 - 啟動可續傳的工作階段

若要開始進行可繼續的影片上傳，請傳送 POST 要求至下列網址。在網址中，將 part 參數值設為符合您要求的適當值。請記住，參數值可識別您要設定之屬性中包含的部分，也會指出您希望 API 回應包含的部分。要求網址中的參數值必須以網址編碼。

https://www.googleapis.com/upload/youtube/v3/videos?uploadType=resumable&part=PARTS

將要求主體設為 video 資源。此外，請設定下列 HTTP 要求標頭：

  • Authorization：要求的授權權杖。
  • Content-Length：要求主體中提供的位元組數。請注意，如果您使用區塊傳輸編碼，就不需要提供這個標頭。
  • Content-Type - 將值設為 application/json; charset=UTF-8。
  • X-Upload-Content-Length - 在後續要求中上傳的位元組數。請將這個值設為您上傳的檔案大小。
  • x-upload-content-type：您要上傳的檔案的 MIME 類型。您可以上傳任何影片 MIME 類型 (video/*) 或 MIME 類型為 application/octet-stream 的檔案。

以下範例說明如何啟動上傳影片的可繼續工作階段，要求會設定 (並擷取) video 資源的 snippet 和 status 部分，且會擷取資源的 contentdetails 部分屬性。

post /upload/youtube/v3/videos?uploadType=resumable&part=parts http/1.1
host: www.googleapis.com
authorization: bearer auth_token
content-length: content_length
content-type: application/json; charset=utf-8
x-upload-content-length: x_upload_content_length
X-Upload-Content-Type: X_UPLOAD_CONTENT_TYPE

video resource

以下範例顯示含有驗證權杖之外所有值的 POST 要求。範例中的 categoryId 值對應到影片類別。您可以使用 API 的 videoCategories.list 方法擷取支援類別清單。

POST /upload/youtube/v3/videos?uploadType=resumable&part=snippet,status,contentDetails HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer AUTH_TOKEN
Content-Length: 278
Content-Type: application/json; charset=UTF-8
X-Upload-Content-Length: 3000000
X-Upload-Content-Type: video/*

{
  "snippet": {
    "title": "My video title",
    "description": "This is a description of my video",
    "tags": ["cool", "video", "more keywords"],
    "categoryId": 22
  },
  "status": {
    "privacyStatus": "public",
    "embeddable": True,
    "license": "youtube"
  }
}

步驟 2：儲存支援工作階段的 URI

如果要求成功，API 伺服器就會回應 200 (OK) HTTP 狀態碼，而回應中包含的 Location HTTP 標頭會指定可繼續工作階段的 URI。這是您用來上傳影片檔案的 URI。

下方範例為步驟 1 中要求的 API 回應範例：

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/youtube/v3/videos?uploadType=resumable&upload_id=xa298sd_f&part=snippet,status,contentDetails
Content-Length: 0

步驟 3 - 上傳影片檔案

從 API 回應擷取工作階段 URI 後，您必須將實際的影片檔案內容上傳至該位置。要求的主體是您要上傳影片的二進位檔案內容。以下範例顯示要求格式。

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: CONTENT_LENGTH
Content-Type: CONTENT_TYPE

BINARY_FILE_DATA

這個要求會設定下列 HTTP 要求標頭：

  • Authorization：要求的授權權杖。
  • Content-Length - 您要上傳的檔案大小。這個值應與步驟 1 中 X-Upload-Content-Length HTTP 要求標頭的值相同。
  • Content-Type：您要上傳的檔案的 MIME 類型。這個值應與步驟 1 中 X-Upload-Content-Type HTTP 要求標頭的值相同。

步驟 4 - 完成上傳程序

您的要求將會產生下列其中一種情況：

  • 上傳成功。

    API 伺服器以 HTTP 201 (Created) 回應代碼回應。回應的主體就是您建立的 video 資源。

  • 上傳失敗，但可以繼續進行。

    只要發生下列任一情況，您就能恢復上傳作業：

    • 您的應用程式與 API 伺服器之間的連線已中斷，因此要求已中斷。在這種情況下，您將不會收到 API 回應。

    • API 回應會指定以下任一 5xx 回應代碼。收到上述任何回應代碼後，繼續上傳時，您的程式碼應採用指數輪詢策略。

      • 500 - Internal Server Error
      • 502 - Bad Gateway
      • 503 - Service Unavailable
      • 504 - Gateway Timeout

    如要繼續上傳，請按照下方的操作說明檢查上傳狀態並繼續上傳。請記住，每個可繼續工作階段的 URI 都有效期限制，最終會過期。因此，建議您在取得工作階段 URI 後就開始進行可繼續上傳作業，並在中斷後繼續中斷中斷的上傳作業。

  • 上傳失敗。

    如果上傳失敗，回應會包含錯誤回應，以協助說明造成錯誤的原因。如果上傳作業永久失敗，API 回應將包含上述以外的 4xx 回應代碼或 5xx 回應代碼。

    如果您傳送的要求已過期的工作階段 URI，伺服器會傳回 404 HTTP 回應代碼 (Not Found)。在這種情況下，您必須開始新的繼續作業上傳作業，取得新的工作階段 URI，然後從頭開始使用新的 URI 進行上傳作業。

步驟 4.1：檢查上傳狀態

如要檢查已中斷的可繼續上傳作業狀態，請將空白的 PUT 要求傳送至您在步驟 2 擷取的上傳網址，並用於步驟 3。在要求中，將 Content-Range 標頭值設為 bytes */CONTENT_LENGTH，其中 CONTENT_LENGTH 是您要上傳的檔案大小。

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: 0
Content-Range: bytes */CONTENT_LENGTH

步驟 4.2：處理 API 回應

如果上傳作業已經完成，無論上傳成功或失敗，API 都會傳回上傳時所提供的回應。

不過，如果上傳作業中斷或仍在進行中，API 回應就會包含 HTTP 308 (Resume Incomplete) 回應代碼。回應中的 Range 標頭會指定成功上傳多少位元組的檔案。

  • 標頭值是從 0 建立索引。因此，標頭值 0-999999 表示檔案的前 1,000,000 個位元組已經上傳。
  • 如果尚未上傳，API 回應就不會包含 Range 標頭。

下方範例回應顯示可恢復上傳作業的 API 回應格式：

308 Resume Incomplete
Content-Length: 0
Range: bytes=0-999999

如果 API 回應也包含 Retry-After 標頭，請使用該標頭的值來判斷何時要繼續上傳。

步驟 4.3：繼續上傳

如要繼續上傳，請將其他 PUT 要求傳送至步驟 2 擷取的上傳網址。針對要求中尚未上傳影片的部分，將要求主體設為二進位碼。

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: REMAINING_CONTENT_LENGTH
Content-Range: bytes FIRST_BYTE-LAST_BYTE/TOTAL_CONTENT_LENGTH

PARTIAL_BINARY_FILE_DATA

您必須設定下列 HTTP 要求標頭：

  • Authorization：要求的授權權杖。

  • Content-Length - 尚未上傳的內容大小 (以位元組為單位)。如果要上載檔案的其餘部分，只要從 TOTAL_CONTENT_LENGTH 值減去 FIRST_BYTE 值即可計算這個值。這兩個值都會用於 Content-Range 標頭中。

  • Content-Range：您要上傳的檔案的一部分。標頭值由三個值組成：

    • FIRST_BYTE：您要恢復上傳作業的位元組編號索引數 (從 0 開始)。這個值是上一個步驟中擷取的 Range 標頭中第二個數字的一個數字。在上一個範例中，Range 標頭值是 0-999999，因此後續恢復上傳的第一個位元組會是 1000000。

    • LAST_BYTE：您所上傳的二進位檔案的最後 0 個位元組索引 (從 0 開始)。通常是檔案中的最後一個位元組。因此，如果檔案大小是 3000000 位元組，則檔案中的最後一個位元組會是 2999999。

    • TOTAL_CONTENT_LENGTH：影片檔案的總大小 (以位元組為單位)。這個值與原始上傳要求中指定的 Content-Length 標頭相同。

    注意：您無法上傳二進位檔案的非連續區塊。如果您嘗試上傳非連續的封鎖項目，系統就不會上傳其餘的二進位內容。

    因此，恢復上傳時上傳的第一個位元組必須是上次成功上傳至 YouTube 的位元組。(請參閱步驟 4.2 中的 Range 標頭相關討論)。

    因此，如果 Range 標頭中的最後一個位元組是 999999，則在繼續上傳時，要求中的第一個位元組必須是位元組 1000000。(兩者皆使用 0 的索引)。如果您嘗試從位元組 999999 以下的輸出檔 (重疊位元組) 或位元組 1000001 以上的位元組繼續上傳，則不會上傳任何二進位內容。

將檔案以區塊為單位上傳

您的應用程式可以在收到網路中斷情形時，先將檔案分割為多個區塊，再提出一系列上傳區塊的要求，而不是嘗試上傳整個檔案，並在發生網路中斷時繼續上傳作業。這種方法很少使用，因此實際上不建議使用，因為這需要額外的要求，對成效造成影響。不過，如果您要在非常不穩定的網路上顯示進度指標，這個方法就很實用。

將檔案以分批上傳的操作說明，大致與本指南之前所述的四個步驟相同。不過，當您以區塊上傳時，要求開始上傳檔案 (上述步驟 3) 和繼續上傳 (上述步驟 4.3) 的 Content-Length 和 Content-Range 標頭值會分別設定。

  • Content-Length 標頭值會指定要求傳送的區塊大小。請注意，區塊大小有下列限制：

    • 區塊大小必須是 256 KB 的倍數。(此限制不適用於最後一個區塊，因為整個檔案的大小不得大於 256 KB 的倍數)。提醒您，區塊越大，效率就越高。

    • 上傳序列中的每個請求都必須有相同的區塊大小，而最後一個要求除外，因為該請求會指定最終區塊的大小。

  • Content-Range 標頭會指定在要求上傳檔案中的位元組。設定這個值時，請按照步驟 4.3 中的操作說明設定 Content-Range 標頭。

    舉例來說，bytes 0-524287/2000000 值表示在 2,000,000 個位元組的檔案中，要求將送出 524,288 個位元組 (256 x 2048)。

以下示例展示了一批要求為 2,000,000 字績文件為 ch 的一系列請求中的第一批格式：

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: 524888
Content-Type: video/*
Content-Range: bytes 0-524287/2000000

{bytes 0-524287}

如果最終要求以外的要求成功執行，API 伺服器會傳回 308 (Resume Incomplete) 回應。回應格式會與上述步驟 4.2：處理 API 回應中所述格式相同。

請使用 API 回應的 Range 標頭中傳回的最大值，決定下一個區塊的起始位置。按照步驟 4.3：繼續上傳的說明，繼續傳送 PUT 要求，以上傳後續的檔案區塊，直到整個檔案上傳為止。

整個檔案上傳完畢後，伺服器會傳回 201 HTTP 回應代碼 (Created)，並傳回新建立影片資源的要求部分。

如有任何要求中斷，或應用程式收到任何 5xx 回應代碼，請按照步驟 4 的說明完成上傳作業。不過，請勿繼續上傳檔案的其餘部分，只要繼續繼續上傳即可。請務必查看上傳狀態，判斷要繼續上傳檔案的位置。請勿假設伺服器收到了在先前要求中傳送的所有位元組 (甚至不接收任何位元組)。

附註：您也可以針對上傳的片段，要求有效上傳的狀態。(在順利擷取檔案之前，先不中斷上傳作業)。