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