Resumable Upload APIで大きなファイルをグラフAPIにアップロードすると、たとえ中断しても、アップロードセッションを最初からやり直さなくても再開することができます。いったんアップロードされたら、それらのファイルハンドルをサポートしているグラフAPIエンドポイントで、アップロードされたファイルのハンドルを使うことができます。
Resumable Upload APIが、ファイルをアップロードする唯一の方法ではありません。多くのノードにはアップロードをサポートするエッジがありますが、そのほとんどは大きなファイルを取り扱ったり、中断されたアップロードセッションを再開したりする方法がありません。
アップロードされたファイルハンドルをサポートするエンドポイントを参照すると、そのエンドポイントがResumable Upload APIによって返されたハンドルをサポートしているかどうかが示されます。
ファイルのアップロードは次の2ステッププロセスです。
成功するとファイルハンドルが返されます。これを、Resumable Upload APIが返したファイルハンドルをサポートするほかのエンドポイントで使用することができます。
アプリケーションアップロードエンドポイント({app-id}/uploads
)に、ファイルを記述したPOST
リクエストを送信します。成功した場合に返されるアップロードセッションIDを次のステップで使って、アップロードを開始することができます。
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}
— アプリケーションID。このアプリに関連付けられるアップロードファイル。アプリユーザーは、このアプリの管理者または開発者の役割を持っている必要があります。file-length
— ファイルサイズ(バイト単位)。 file-type
— ファイルのMIMEタイプ。有効な値は、application/pdf
、image/jpeg
、image/jpg
、image/png
、video/mp4
{access-token}
— アプリユーザーのユーザーアクセストークン。利用可能なクエリパラメーターとサポートされているファイルタイプの全一覧については、アプリケーションアップロードエンドポイントリファレンスを参照してください。
{ "id": "{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..." }
グラフAPIホストアドレスにPOST
リクエストを送信してアップロードセッションを開始します。その際、以下に示す必須ヘッダーと共に、アップロードセッション{id}
を追加します。成功すると、ファイルハンドル{h}
が返されます。これは、Resumable Upload 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で返されたアップロードセッションID。{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..." }
アップロードセッションを開始したのに予想以上に時間がかかったり中断されたりした場合は、グラフAPIホストアドレスにGET
リクエストを送信します。その際、アップロードセッションIDを追加してください。APIは、中断時点からアップロードプロセスを再開するために使用できるfile_offset
値を返します。
GET https://graph.facebook.com/{api-version}/{upload-session-id} ?access_token={access-token}
プレースホルダーの値:
{api-version}
— グラフAPIのバージョン。{upload-session-id}
— ステップ1: セッションを作成するで返されたアップロードセッションID。{access-token}
— アプリユーザーのユーザーアクセストークン。{ "id": "{id}", "file_offset": {file-offset} }
応答プロパティ値:
{id}
— クエリされたアップロードセッション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 }