Facebook oEmbed

Facebook oEmbed 端点可用来获取主页、帖子和视频的嵌入式 HTML 和基本元数据，以便在其他网站或应用中显示。

我们已将 oEmbed 产品替换为 oEmbed Read 功能。如果您在 2021 年 6 月 8 日之前实施 oEmbed 产品，则必须在 2021 年 9 月 7 日之前就 oEmbed Read 功能完成应用审核。如果您在 2021 年 9 月 7 日之前尚未获准使用 oEmbed Read 功能，则您实施的 oEmbed 将无法加载。

常见用途

在消息应用中展示 Facebook 公共主页、帖子和视频。
在网站和博客中嵌入 Facebook 公共主页、帖子和视频。
在内容管理系统中展示 Facebook 公共主页、帖子和视频。

端点

端点	描述
`GET /oembed_page`	获取 Facebook 公共主页的嵌入式 HTML 和基本元数据。
`GET /oembed_post`	获取 Facebook 帖子的嵌入式 HTML 和基本元数据。
`GET /oembed_video`	获取 Facebook 视频的嵌入式 HTML 和基本元数据。

要求

限制

Facebook oEmbed 端点仅用于在网站和应用中嵌入 Facebook 内容。不可将其用于任何其他用途。严禁将来自端点的元数据、主页、帖子或视频内容（或其衍生内容）用于除提供主页、帖子或视频前端视图以外的任何其他用途。此限制涵盖使用、操纵、提取或保留元数据和内容的行为，包括但不限于从元数据中获取关于主页、帖子和视频的信息以供分析。

应用审核

要使用 oEmbed，您的应用必须完成针对 oEmbed Read 功能的应用审核。

在填写提供用于测试 Oembed Read 的网址表单字段时，请使用 oEmbed 端点获取我们官方 Facebook 公共主页或 Instagram 公共主页上任一公共主页帖子或视频的嵌入式 HTML（或获取其中一个公共主页的嵌入式 HTML）。将返回的嵌入式 HTML 添加到您自己的网页，以便显示 oEmbed 内容，然后在表单字段中输入该网页的网址。

在您获准使用 oEmbed Read 功能后，您可以使用相应网址嵌入您的公共主页、帖子或视频。

访问口令

Facebook oEmbed 端点需要使用应用访问口令（推荐）或客户端访问口令。

应用访问口令

如果您的应用需要使用后端服务器，推荐您使用应用访问口令来访问 oEmbed 端点。流量限制取决于请求中的口令类型，应用口令流量限制为每天 500 万次请求。

如需应用访问口令生成说明，请查阅访问口令文档中的应用口令版块。

请注意，应用访问口令不可用于客户端。口令必须始终在您的服务器上加密存储。如果您的应用必须使用客户端口令，请改为使用客户端访问口令。

客户端访问口令

如果应用必须通过移动设备、网页浏览器等用户代理访问 oEmbed 端点，则应用须使用客户端访问口令，并需遵循客户端口令流量限制。

要获取客户端访问口令，请登录应用面板，并前往设置 > 高级 > 帐户安全 > 客户端口令。

不同于应用访问口令，客户端访问口令无法单独在 oEmbed 端点请求中使用，而须配合应用编号使用。如要执行此操作，请在应用编号末尾附加口令，并使用竖线 (|) 分隔：

{app-id}|{client-token}

例如：

access_token=1234|5678

流量限制

流量限制取决于每次请求中包含的应用访问口令类型。

应用口令流量限制

使用应用访问口令的应用每 24 小时最多可发出 500 万次请求。

客户端口令流量限制

客户端口令流量限制显著低于应用口令流量限制。由于实际的流量限制会因应用活动而异，所以我们没有列出实际数值。然而，应用一般不会达到此限制，除非其展示出类似于机器人的行为，例如批量发送数千次请求，或每个代理或应用用户均发出数千次请求。

获取嵌入式 HTML

要获取主页、帖子或视频的嵌入式 HTML，请向相应主页、帖子或视频的 oEmbed 端点发送请求：

目标	端点和查询结构
公共主页	`GET /oembed_page?url={url}&access_token={access-token}`
帖子	`GET /oembed_post?url={url}&access_token={access-token}`
视频	`GET /oembed_video?url={url}&access_token={access-token}`

将 {url} 替换为想要查询的主页、帖子或视频的网址，并将 {access-token} 替换为您的应用或客户端访问口令（或使用 HTTP 标头向我们传送口令）。如果您使用的是客户端访问口令，请务必将口令与应用编号结合使用，并用竖线分隔，否则请求将失败。

成功后，API 将在响应中返回 JSON 对象，其中包含主页、帖子或视频的嵌入式 HTML 和有关主页、帖子或视频的其他数据。嵌入式 HTML 将指定为 html 属性。

如需获取可用于扩展请求的查询字符串参数列表，请参阅各个端点的参考文档。您还可在任意请求中添加 fields 查询字符串参数，以指定需要返回的字段。如不指定，响应中将包含所有默认字段。

主页请求示例

curl -i -X GET \
 "https://graph.facebook.com/v19.0/oembed_page?url=https%3A%2F%2Fwww.facebook.com%2FCDC&access_token=96481..."

响应示例

使用省略号 (...) 截断了某些值以方便阅读。

{
  "provider_url": "https://www.facebook.com",
  "provider_name": "Facebook",
  "height": 500,
  "html": "<div id=\"fb-root\"></div><script async=\"1\" defer=...",
  "type": "rich",
  "version": "1.0",
  "width": 340
}

网址格式

url 查询字符串参数接受下列网址格式：

公共主页

https://www.facebook.com/{page-name}
https://www.facebook.com/{page-id}

帖子

https://www.facebook.com/{page-name}/posts/{post-id}
https://www.facebook.com/{username}/posts/{post-id}
https://www.facebook.com/{username}/activity/{activity-id}
https://www.facebook.com/photo.php?fbid={photo-id}
https://www.facebook.com/photos/{photo-id}
https://www.facebook.com/permalink.php?story_fbid={post-id}&id={page-or-user-id}
https://www.facebook.com/media/set?set={set-id}
https://www.facebook.com/questions/{question-id}
https://www.facebook.com/notes/{username}/{note-url}/{note-id}

视频

https://www.facebook.com/{page-name}/videos/{video-id}/
https://www.facebook.com/{username}/videos/{video-id}/
https://www.facebook.com/video.php?id={video-id}
https://www.facebook.com/video.php?v={video-id}

SDK JS

嵌入式 HTML 默认包含对 sdk.js JavaScript 库的引用。如需获取不包含引用的嵌入式 HTML 以将其单独加载，请添加 omitscript=true 查询字符串参数。

使用标头传送访问口令

如果不想在请求的查询字符串中添加访问口令，您可改为使用 Authorization HTTP 标头将其传送给我们。

Authorization: Bearer {access-token}

例如：

curl -i -X GET \
  "https://graph.facebook.com/v19.0/oembed_page?url=https%3A%2F%2Fwww.facebook.com%2FCDC" \
  --header "Authorization: Bearer 96481..."