圖形 API

可續傳的上傳 API

可續傳的上傳 API 允許您將大型檔案上傳到圖形 API 且能繼續中斷的上傳連線階段，而無需重新開始。上傳後，您可以將上傳檔案的名稱與支援的其他圖形 API 端點一起使用。

請注意，可續傳的上傳 API 不是上傳檔案的唯一方法。許多節點都有支援上傳的關係連線，但多數節點沒有處理大型檔案的方法或繼續中斷的上傳連線階段的方法。

上傳檔案控制代碼的端點的參考將指示端點是否支援可繼續上傳 API 傳回的名稱控制代碼。

上傳步驟

上傳檔案分為兩步驟：

  1. 使用 Application Uploads 端點描述您的檔案並建立上傳連線階段。
  2. 使用傳回的上傳連線階段編號啟動上傳流程。

如果成功，將傳回一個檔案控制代碼，然後您可以將其與支援由可續傳的上傳 API 傳回的檔案名稱的其他端點一起使用。

步驟 1：建立連線階段

傳送 POST 要求，向應用程式上傳端點（{app-id}/uploads）描述您的檔案。成功後，系統會傳回上傳連線階段編號，您可以在下一步中使用該編號啟動上傳。

要求語法

POST https://graph.facebook.com/{api-version}/{app-id}/uploads
  &file_length={file-length}
  &file_type={file-type}
  &access_token={access-token}

參數預留位置：

  • {api-version} — 圖形 API 版本。
  • {app-id} — 應用程式編號。將與此應用程式相關聯的上傳檔案。應用程式用戶必須要有此應用程式的管理員或開發人員角色。
  • file-length — 檔案大小，單位為位元組。
  • file-type — 檔案的 MIME 類型。有效值為：application/pdf、image/jpeg、image/jpg、image/png 和 video/mp4
  • {access-token} — 應用程式用戶的用戶存取權杖。

如需可用查詢參數和支援的檔案類型的完整清單，請參閱應用程式上傳端點參考資料。

回應

{
  "id": "{id}"
}

回應屬性值：

  • {id} — 上傳連線階段編號。

要求範例

curl -X POST \
 "https://graph.facebook.com/v19.0/584544743160774/uploads?file_length=109981&file_type=image/png&access_token=EAAIT..."

回應範例

{
    "id": "upload:MTphd..."
}

步驟 2：啟動上傳

啟動上傳連線階段，方法是傳送 POST 要求至圖形 API 主機位址，並附加上傳連線階段 {id} 以及下面指出的必要標頭。成功後，系統會傳回檔案控制代碼 {h}，然後您可以將其與支援由可續傳的上傳 API 傳回的檔案控制代碼的任何圖形 API 端點一起使用。

如果上傳連線階段花費的時間超過預期或已中斷，請按照中斷一節中描述的步驟進行。

要求語法

POST https://graph.facebook.com/{api-version}/{upload-session-id}
  --header 'Authorization: OAuth {access-token}' 
  --header 'file_offset: 0'
  --data-binary @{file-name}

預留位置值

  • {api-version} — 圖形 API 版本。
  • {upload-session-id} — 步驟 1 中傳回的上傳連線階段編號。
  • {access-token} — 應用程式用戶的用戶存取權杖。應用程式用戶必須具有步驟 1 中鎖定之應用程式的角色。
  • {file-name} — 所要上傳檔案的名稱。

您必須在標頭中包含存取權杖，否則要求會失敗。

回應

{
  "h": "{h}"
}

回應屬性值：

  • {h} — 上傳檔案的檔案控制代碼

要求範例

curl -X POST \
 "https://graph.facebook.com/v19.0/upload:MTphd..." \
 --header "Authorization: OAuth EAAIT..." \
 --header "file_offset: 0" \
 --data-binary @cats_are_jerks.png

回應範例

{
    "h": "2:c2FtcGxl..."
}

中斷

如果您已啟動上傳連線階段，但花費的時間超過預期或已中斷，請傳送 GET 要求至圖形 API 主機位址，並附加上傳連線階段編號。API 會傳回 file_offset 值，然後您就可以使用該值，從中斷點繼續上傳程序。

要求語法

GET https://graph.facebook.com/{api-version}/{upload-session-id}
  ?access_token={access-token}

預留位置值：

  • {api-version} — 圖形 API 版本。
  • {upload-session-id} — 步驟 1：建立連線階段中傳回的上傳連線階段編號。
  • {access-token} — 應用程式用戶的用戶存取權杖。

回應

{
  "id": "{id}",
  "file_offset": {file-offset}
}

回應屬性值：

  • {id} — 所查詢的上傳連線階段編號。
  • {file-offset} — 整數，表示已成功上傳的位元組數。

擷取 file_offset 值，並重複步驟 2：啟動上傳，將該值指派至對應的 file_offset 標頭。這樣會從中斷點繼續上傳程序。

要求範例

curl -X GET \
 "https://graph.facebook.com/v19.0/upload:MTphd...&access_token=EAAIT..." \

回應範例

{
  "id": "upload:MTphd",
  "file_offset": 5238
}