Graph API

可恢復的上載 API

透過可恢復的上載 API，您可以將大型檔案上載至 Graph API，從中斷的上載工作階段繼續上載，而無需重新開始。上載完成後，您便可將已上載檔案的控制代碼用於支援這類控制代碼的其他 Graph API 端點。

請注意，可恢復的上載 API 並不是上載檔案的唯一方式。許多節點都有支援上載的關係連線，但大多數都無法處理大型檔案或恢復中斷的上載工作階段。

我們有就支援已上載檔案控制代碼的端點提供參考資料中，並且在當中指出不同的端點是否支援由可恢復的上載 API 所傳回的控制代碼。

上載步驟

檔案上載流程包含兩個步驟：

  1. 使用應用程式上載端點描述您的檔案並建立上載工作階段。
  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}：Graph 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：開始上載

透過向 Graph API 主機地址傳送 POST 要求來展開上載工作階段，並連同下方所示的必要標題附加上載工作階段 {id}。成功的話，系統會傳回檔案控制代碼 {h}，您隨後便可根據哪些 Graph 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}：Graph 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..."
}

中斷

如果您已發起上載工作階段，但所需時間超出預期或被中斷，請向 Graph API 主機地址傳送 GET 要求，並附加上載工作階段編號。此 API 會傳回一個 file_offset 值，您可以使用此值來從中斷的位置恢復上載流程。

要求語法

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

預留位置值：

  • {api-version}：Graph 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
}