Meta 的 Facebook 快拍 API

本文档介绍如何使用 Facebook 快拍 API 在 Facebook 公共主页上发布快拍。

发布快拍需要执行以下步骤：

1. 将您的媒体上传至 Meta 服务器
2. 将媒体作为快拍发布至您的公共主页

前期准备

本指南假设您已阅读公共主页 API 概览，实现了所需组件，并成功实施了入门指南。

• 您需要实现 Facebook 登录或企业版 Facebook 登录，以便向您的应用用户请求授予所需权限，来访问他们的 Facebook 公共主页和接收公共主页访问口令。

• 您的应用用户必须能够在公共主页访问口令所代表的公共主页上执行 CREATE_CONTENT 任务，并向您的应用授予以下权限：

  • pages_manage_posts
  • pages_read_engagement
  • pages_show_list

如要在 API 请求中使用企业系统用户，则还需要 business_management 权限。

媒体要求

您提供的照片或视频必须符合以下规格。

照片规格

视频规格

限制

• 为快拍上传的照片或视频不能在之前发布的帖子中用过
• 视频快拍不能超过 60 秒
• 如要在 GET 请求中加入收入私密文件夹的快拍，以便查看完整的快拍列表，您必须启用 Facebook 快拍私密文件夹

最佳实践

为方便阅读，本文档中代码示例的格式已经过调整。请将粗体、斜体值（例如 page_id）替换为您的值。

视频快拍

如要在 Facebook 公共主页上发布视频快拍，您需要向 Meta 服务器发起视频上传会话，将视频上传至 Meta 服务器，然后发布视频快拍。

第 1 步：发起会话

如要发起上传会话，请向 /page_id/video_stories 端点发送 POST 请求（其中 page_id 是您的 Facebook 公共主页编号），在请求中加入 upload_phase 参数，并将其设为 start。

请求示例

curl -X POST "https://graph.facebook.com/v21.0/page_id/video_stories" \
      -d '{
           "upload_phase":"start",
         }'

若请求成功，应用收到的 JSON 响应中将包含视频编号和您上传视频所使用的 Facebook 网址。

响应示例

{
  "video_id": "video_id",
  "upload_url": "https://rupload.facebook.com/video-upload/v21.0/video_id",
}  

第 2 步：上传视频

发起上传会话并收到上传网址后，您就可以上传视频了。您可以上传以下任意一种文件：

• 公开 http/https 服务器（如 CDN）上的托管视频文件
• 您设备中的本地视频文件

上传托管文件

如要上传托管的文件，请向您在发起会话步骤中收到的 upload_url 端点发送 POST 请求，并在请求中加入以下参数：

• file_url，设置为视频文件所在的网址

请求示例

curl -X POST "https://rupload.facebook.com/video-upload/v21.0/video_id" \
	-H "file_url: https://some.cdn.url/video.mp4"

上传本地文件

如要上传本地文件，请向您在发起会话步骤中收到的 upload_url 端点发送 POST 请求，并在请求中加入以下参数：

• offset，设置为 0
• file_size，设置为要上传视频的总大小，以字节为单位

请求示例

curl -X POST "https://rupload.facebook.com/video-upload/v21.0/video_id" \
	-H "offset: 0" \
        -H "file_size: file_size_in_bytes" \
	--data-binary "@/path/to/file/my_video_file.mp4"

若上传成功，应用收到的 JSON 响应中将包含 success，值已设为 true。

上传响应示例

{
    "success": true
}  

上传中断

如果视频上传中断，可重新开始上传或恢复上传。

• 如要重新开始上传，请重新发送 POST 请求，并在请求中将 offset 设为 0。
• 如要恢复上传，请重新发送 POST 请求，并在请求中将 offset 设为状态检查结果中的 bytes_transfered 值。

获取上传状态

如要检查视频的状态，在上传或发布时，请向 /video_id 端点发送 GET 请求，并在请求中加入以下参数：

• fields，设置为 status

请求示例

curl -X GET "https://graph.facebook.com/v21.0/video_id" \
	-d "fields=status"

若请求成功，应用收到的 JSON 响应中将包含：

• 一个 status 对象，其中包含：

  • video_status，值为 ready、processing、expired 或 error
  • uploading_phase 对象，其中包含以下键值对：

    • status，设置为 in_progress、not_started、complete 或 error
    • bytes_transfered，设置为已上传的字节数；如果上传中断，该值可用作 offset 的值。
  • processing_phase 对象，其中包含以下键值对：

    • status，设置为 in_progress、not_started、complete 或 error
  • processing_phase 对象，其中包含以下键值对：

    • status，设置为 in_progress、not_started、complete 或 error
    • publish_status，设置为 published 或 not_published
    • publish_time，设置为实际时间或发布时间的 UNIX 时间戳

响应示例

{
  "status": {
    "video_status": "processing", 
    "uploading_phase": {
      "status": "in_progress", 
      "bytes_transfered": 50002 
    },
    "processing_phase": {
      "status": "not_started"
    }
    "publishing_phase": {
      "status": "not_started",
      "publish_status": "published",
      "publish_time": 234523452 
    }
  }
}

{
  "status": {
    "video_status": "processing", 
    "uploading_phase": {
      "status": "complete"
    },
    "processing_phase": {
      "status": "not_started",
      "error": {
        "message": "Resolution too low. Video must have a minimum resolution of 540p."
      }
    }
    "publishing_phase": {
      "status": "not_started"
    }
  }
}

第 3 步：发布视频快拍

如要在公共主页上发布视频快拍，请向 /page_id/video_stories 端点发送 POST 请求，并在请求中加入以下参数：

• video_id，设置为已上传视频的编号
• upload_phase，设置为 finish

请求示例

curl -X POST "https://graph.facebook.com/v21.0/page_id/video_stories" \
      -d '{
           "video_id": "video_id",
           "upload_phase": "finish"
         }'

若请求成功，应用收到的 JSON 响应中将包含以下键值对：

• success，设置为 true
• post_id，设置为快拍帖子的编号

响应示例

{
  "success": true,
  "post_id": 1234
}

照片快拍

第 1 步：上传照片

访问公共主页帖子指南 ，了解如何使用 /page_id/photos 端点将照片上传至 Meta 服务器。务必在请求中加入 published 参数，并将其设为 false。

第 2 步：发布照片快拍

如要向公共主页发布照片快拍，请向 /page_id/photo_stories 端点发送 POST 请求，并在请求中加入以下参数：

• photo_id，设置为已上传照片的编号

请求示例

curl -X POST "https://graph.facebook.com/v21.0/page_id/photo_stories" \
      -d '{
           "photo_id": "photo_id"
         }'

若请求成功，应用收到的 JSON 响应中将包含以下键值对：

• success，设置为 true
• post_id，设置为快拍帖子的编号

响应示例

{
  "success": true,
  "post_id": 1234
}

获取快拍

如要获取公共主页的完整快拍清单以及有关每个快拍的数据，请向 /page_id/stories 端点发送 GET 请求，其中 page_id 是您要查看的公共主页的编号。

请求示例

    
curl -i -X GET "https://graph.facebook.com/v21.0/page_id/stories"

若请求成功，应用收到的 JSON 响应中将包含一个对象数组，其中每个对象都包含已发布到公共主页的快拍的信息。每个对象都包含以下键值对：

• post_id，设置为已发布快拍帖子的编号
• status，设置为 PUBLISHED、ARCHIVED
• creation_time，设置为快拍发布时的 UNIX 时间戳
• media_type，设置为 video 或 photo
• media_id，设置为快拍帖子中视频或照片的编号
• url，设置为快拍帖子所在的 Facebook 网址，如 https://facebook.com/stories/8283482737484972

响应示例

{
  "data": [
    {
      "post_id": "post_id",
      "status": "PUBLISHED",
      "creation_time": "123456",
      "media_type": "video",
      "media_id": "video_id",
      "url": "https://facebook.com/stories…"
    },
    {
      "post_id": "post_id",
      "status": "PUBLISHED",
      "creation_time": "123456",
      "media_type": "photo",
      "media_id": "photo_id",
      "url": "https://facebook.com/stories…"
    },
    {
      "post_id": "post_id",
      "status": "ARCHIVED",
      "creation_time": "123456",
      "media_type": "photo",
      "media_id": "photo_id",
      "url": "https://facebook.com/stories…"
    },
    ...
  ],
}

您可以根据状态（已发布或已归档）以及日期（使用 since 和 until 参数）来筛选快拍。

另请参阅：

详细了解本指南中讨论的不同端点和概念。

相关指南

• 企业系统用户
• Facebook 登录
• 企业版 Facebook 登录
• 图谱 API – 使用 since 和 until 筛选出的分页结果

端点参考文档

• 公共主页参考文档
• 公共主页视频快拍参考文档
• 公共主页照片快拍参考文档
• 视频参考文档
• 快拍成效分析参考文档