图谱 API 概览

图谱 API 是存取 Facebook 开放平台数据的主要方式。它是一种以 HTTP 为基础的轻量级 API,可用于以编程的方式查询数据、发布新动态、管理广告、上传照片和执行应用可能会实施的各种其他任务。

基本信息

图谱 API 得名于“社交关系图谱”理念 — 该图谱代表由以下部分组成的 Facebook 信息:

  • 节点 — 用户、照片、主页、评论等基本“事物”
  • 连线 — 上述“事物”之间的联系,例如:主页照片或照片的评论
  • 字段 — 关于上述“事物”的信息,例如:用户的生日或主页名称

图谱 API 以 HTTP 为基础,所以可适用于任何有 HTTP 库的语言,例如:cURL 和 urllib。下面的章节将详细介绍图谱 API 的用途,但您也可以直接在浏览器中使用它,例如图谱 API 请求等同于:

GET graph.facebook.com
  /facebook/picture?
    redirect=false

大部分图谱 API 请求需要使用访问口令,访问口令可以由您的应用通过实施 Facebook 登录生成。

本概览将展示图谱 API 读取和发布社交关系图谱数据的方法。

结构

详情请参阅我们的图谱 API 使用指南,但总的来说,向节点或这些节点的连线发出 HTTP GET 请求,即可读取 API。

几乎所有的请求都会传递到 graph.facebook.com 的 API — 唯一的例外是使用 graph-video.facebook.com 的视频上传请求。

对象编号

每个节点都有唯一的编号,使用此编号可通过图谱 API 访问该节点。我们不会特别记录任何节点/对象编号的结构或格式,因为这些结构或格式极有可能会随时改变,且应用不应该根据当前的结构作出假设。

使用编号请求节点的方法如下:

GET graph.facebook.com
  /{node-id}

使用编号请求连线的方法如下:

GET graph.facebook.com
  /{node-id}/{edge-name}

总的来说,您可以通过两种方法发布信息至 API:向节点发出包含参数的 HTTP POST 请求:

POST graph.facebook.com
  /{node-id}

使用编号请求连线的方法如下:

POST graph.facebook.com
  /{node-id}/{edge-name}

向相同的端点发出 HTTP DELETE 请求(并通过 POST 请求执行更新)即可通过 API 执行删除操作。

API 版本

图谱 API 有多个可用的版本,可随时访问。每个版本都包含一组核心字段和连线操作。我们向您保证这些核心 API 在对应版本发布后 2 年内可用且不会发生更改。开放平台更新日志记录了当前可用的版本。

连线内特定的操作(例如发布)或节点内特定的字段可成为核心,而无需将整个连线或节点设为核心。在图谱 API 参考文档内,我们会使用 符号标注这些核心 API。

这些核心 API 以外的所有 API 均称为扩展 API。这类 API 仍然可以通过带版本的路径访问,但随时可能被修改或移除,此类修改或移除受制于 90 天迁移规定,此规定将公布于我们的开放平台计划表内。这类 API 也可能直接包含于下一个可用的 API 版本内。

您可以阅读我们的指南,详细了解版本控制的目的,但在本文中,我们将介绍调用特定版本的图谱 API 的方法。

这实际上是一个非常简单的过程 — 只需在请求路径的开头添加前置的版本标识符。例如,以下是对 v2.2 的调用:

GET graph.facebook.com
  /v2.2/me

以下一般格式适用于所有版本:

GET graph.facebook.com
  /vX.Y/{request-path}

其中 X.Y 是需要的版本号。如需获取可用版本的完整列表,请参阅我们的更新日志。所有 图谱 API 参考文档会提供对应版本的信息,所以请检查以确保您查看的是正确的版本,一些版本移除了节点和连线,而一些版本会添加节点和连线。

接下来,我们来尝试发送 API 请求,向您展示这种简单的操作方法。

加载图谱 API 探索工具

理解图谱 API 最简单的方法是将其与图谱 API 探索工具(可用于查询、添加和移除数据的轻量级工具)结合使用。集成 Facebook 时,这是一种触手可及的便捷资源。所以,接下来请前往图谱 API 探索工具

图谱 API 探索工具

生成基本用户访问口令

开始构建自己的应用时,您必须了解访问口令和使用 Facebook 登录功能生成访问口令的方法,但现在,我们可以通过图谱 API 探索工具快速获得访问口令:

  1. 点击探索工具右上方的 Get Token 按钮。
  2. 选择 Get User Access Token 选项。
  3. 切勿在出现的对话框中选择任何复选框,只需点击蓝色的 Get Access Token 按钮。
  4. 您会看见 Facebook“登录”对话框,点击 OK 即可继续。

发出第一个请求

现在,您即可发出第一个图谱 API 请求,我们首先发送“读取”请求。在“GET”下拉按钮旁边的文本字段中(我们称之为路径字段),删除现有的文本并输入“me”:

然后按“Submit”(提交)按钮。系统需要几秒钟的时间处理,但您现在应该可以在响应面板中看见一组完整的信息。此处显示的信息取决于您个人主页的隐私设置,但至少应该包括以下基本信息字段:

您刚刚在图谱 API 探索工具中完成的操作相当于以下图谱 API“read”(读取)请求:

GET graph.facebook.com
  /me

/me 是一个会转译为用户编号的特殊端点,此编号对应于访问口令被用于发出请求的用户。

恭喜,您刚刚发出了第一个图谱 API 请求!

获取发布权限

接下来,我们来尝试使用图谱 API 向 Facebook 发布内容。只有在以下条件下才可以在应用内进行此操作:您构建自己专属的编辑器,且未使用网页iOSAndroid 版分享对话框。Facebook 分享对话框不需要您实施 Facebook 登录功能或构建专属的用户分享界面。

如需尝试通过图谱 API 发布内容,请再次点击“获取访问口令”按钮,并选择 publish_actions 权限:

然后点击蓝色的“获取访问口令”按钮,即可再次看见“登录”对话框。在这里,系统会向您请求权限,用于通过图谱 API 探索工具以您的名义发布内容。即使想要将此处的分享对象更改为“仅限自己”,以便只有您才能查看帖子,也应接受此对话框并继续执行下一步。

发布帖子

如果已请求 publish_actions 权限,现在就可以点击“GET”按钮,并从显示的下拉选择器中选择“POST”。在路径字段输入 me/feed,然后点击“添加字段”。

在显示的新字段中,将 message 设为“name”(名称),将 Hello, World设为“value”(值)。效果应如下所示:

然后点击蓝色的“Submit”(提交)按钮,几秒钟后,响应面板应显示以下内容:

{
  "id": "{new-post-id}"
}

这意味着您刚刚通过图谱 API 发布了第一个帖子! 您可以前往自己的个人主页,查看此帖子:

您刚刚在图谱 API 探索工具中完成的操作相当于以下图谱 API“publish”(发布)请求:

POST graph.facebook.com
  /me/feed?
    message="Hello, World."&
    access_token={your-access-token}

后续步骤

您已经通过此文了解了基本信息,建议继续详细了解图谱 API 的使用方法。 如果您尚未了解基本信息,建议您首先阅读 Facebook 登录,重点了解如何生成访问口令,帮助您发出更复杂的图谱 API 请求。