图谱 API

可续传 API

使用可续传 API 可将大型文件上传至图谱 API 并恢复中断的上传会话，而无需从头开始上传。上传后，您可以立即将已上传文件的句柄与支持该句柄的其他图谱 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} — 图谱 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
}