透過可恢復的上載 API,您可以將大型檔案上載至 Graph API,從中斷的上載工作階段繼續上載,而無需重新開始。上載完成後,您便可將已上載檔案的控制代碼用於支援這類控制代碼的其他 Graph API 端點。
請注意,可恢復的上載 API 並不是上載檔案的唯一方式。許多節點都有支援上載的關係連線,但大多數都無法處理大型檔案或恢復中斷的上載工作階段。
我們有就支援已上載檔案控制代碼的端點提供參考資料中,並且在當中指出不同的端點是否支援由可恢復的上載 API 所傳回的控制代碼。
檔案上載流程包含兩個步驟:
如果成功,系統將會傳回檔案控制代碼,您隨後便可根據哪些其他端點支援由可恢復的上載 API 所傳回的檔案控制代碼,將系統傳回的控制代碼用於其中。
將描述檔案的 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..." }
透過向 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 }