グラフAPI

Resumable Upload API

Resumable Upload APIで大きなファイルをグラフAPIにアップロードすると、たとえ中断しても、アップロードセッションを最初からやり直さなくても再開することができます。いったんアップロードされたら、それらのファイルハンドルをサポートしているグラフAPIエンドポイントで、アップロードされたファイルのハンドルを使うことができます。

Resumable Upload APIが、ファイルをアップロードする唯一の方法ではありません。多くのノードにはアップロードをサポートするエッジがありますが、そのほとんどは大きなファイルを取り扱ったり、中断されたアップロードセッションを再開したりする方法がありません。

アップロードされたファイルハンドルをサポートするエンドポイントを参照すると、そのエンドポイントがResumable Upload APIによって返されたハンドルをサポートしているかどうかが示されます。

アップロードの手順

ファイルのアップロードは次の2ステッププロセスです。

  1. アプリケーションアップロードエンドポイントを使用して、ファイルを記述してアップロードセッションを作成します。
  2. 返されたアップロードセッションIDを使用して、アップロードプロセスを開始します。

成功するとファイルハンドルが返されます。これを、Resumable Upload APIが返したファイルハンドルをサポートするほかのエンドポイントで使用することができます。

ステップ1: セッションを作成する

アプリケーションアップロードエンドポイント({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..."
}

ステップ2: アップロードを開始する

グラフ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
}