概览

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

基本信息

图谱 API 得名于“社交关系图谱”理念 — Facebook 上的一种信息表示形式。它由以下部分组成:

  • 节点 — 用户、照片、主页或评论等基本的个体对象
  • 连线 — 对象集合与单个对象之间的联系,如主页中的照片或照片的评论
  • 字段 — 关于对象的数据,如用户的生日或主页的名称

一般来说,您可以使用节点获取有关特定对象的数据,使用连线获取与单个对象关联的对象集合,使用字段获取有关单个对象或集合中每个对象的数据。

HTTP

图谱 API 以 HTTP 为基础,所以可适用于任何有 HTTP 库的语言,例如:cURL 和 urllib。这意味着,您可以直接在浏览器中使用图谱 API。例如,在浏览器中请求此网址...

https://graph.facebook.com/facebook/picture?redirect=false

...相当于执行此 cURL 请求:

curl -i -X GET \
 "https://graph.facebook.com/facebook/picture?redirect=false&access_token={valid-access-token-goes-here}"

访问口令

您可能已经注意到上述 cURL 请求中的 access_token 参数和占位符值。大部分图谱 API 请求都需要访问口令。要了解访问口令的工作原理,请阅读我们的访问口令文档,但现在您只需要知道以下两点:

  • 大部分图谱 API 请求都需要特定类型的访问口令;
  • 获取访问口令的最简单方法是使用 Facebook 登录功能。

图谱 API 文档通篇使用的伪代码请求/响应示例不会明确引用访问口令,但您应该假设访问口令已包含在请求中,这样才能收到响应。

架构

我们的“图谱 API 的使用方法”指南详细介绍了图谱 API 的结构,总而言之您可以:

  • 使用节点获取有关个别对象的数据
  • 使用连线获取与节点关联的对象集合,或向这些集合发布对象
  • 使用字段指定想要通过响应获得的数据

托管网址

几乎所有的请求都会传递到 graph.facebook.com 托管网址。唯一的例外是视频上传请求,这类请求会使用 graph-video.facebook.com

对象编号

节点是指个体对象,每个节点都有唯一的编号,所以如果要获取有关某节点的信息,您可以直接查询其编号。例如,官方 Facebook 主页的编号为 20531316728。您可以使用主页编号直接查询主页信息:

GET graph.facebook.com
  /20531316728

如果您想获取关于某节点的特定数据(称为字段),可以添加 fields 参数,并指定您希望响应返回的字段。例如主页节点参考文档中提到,您在读取主页对象时可以获取的一个字段是 cover,它是指主页的封面照片。此查询请求如下所示:

GET graph.facebook.com
  /20531316728?fields=cover

大部分节点都有连线,连线可以返回与对应节点关联的对象集合。要查询连线,要同时使用节点编号和节点名称。主页节点参考文档中列出的其中一个连线是 photos 连线,此连线会返回归主页所有的所有照片对象。因此,要获取某 Facebook 主页拥有的所有照片,您应该查询该节点的 photos 连线:

GET graph.facebook.com
  /20531316728/photos

一些节点允许您通过 POST 操作更新字段。例如,如果您是 Facebook 主页的管理员,可以使用如下所示的请求更新该主页的 description 字段:

POST graph.facebook.com
  /20531316728?description=The%20OFFICIAL%20Facebook%20Page

连线通常允许您执行 POST 操作,向与对应节点关联的集合发布新对象。下面的示例展示了如何向 Facebook 主页拥有的照片集合发布照片:

POST graph.facebook.com
  /20531316728/photos

当然,向集合发布对象通常需要有关此对象的额外字段,如照片的网址、标题或说明。连线参考文档说明了哪些字段是必须提供的,哪些字段可以选择性提供。

最后,一般来说您可以向对象编号执行 DELETE 操作,来删除节点:

DELETE graph.facebook.com
  /20531316728

版本

图谱 API 有多个版本。您可以阅读我们的应用版本指南,详细了解版本管理方式,但在本文中,我们将介绍如何调用特定版本的图谱 API。

这实际上是一个非常简单的过程 — 只需在请求路径的开头添加字母 v,并在该字母后添加版本号。例如,下面的示例将调用版本 2.9:

GET graph.facebook.com
  /v2.9/20531316728/photos

如果您未添加版本号,我们将默认调用最旧的可用版本,因此建议在请求中添加版本号。

图谱 API 更新日志列出了所有可用的版本,且您可以按照版本筛选参考文档的内容。

后续步骤

现在,我们来看看图谱 API 的使用方法,了解一些更详细的请求及其响应,以及您可以使用图谱 API 执行的其他操作。