概览

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

“社交关系图谱”是一种 Facebook 中信息的表示形式，图谱 API 得名于这种概念。图谱 API 由节点、连线和字段组成。通常要用节点获取有关特定对象的数据，用连线获取有关单个对象的对象集合，用字段获取有关单个对象或集合中每个对象的数据。在文献资料中，我们可能会将节点和连线统称为“端点”。例如，“向用户端点发送 GET 请求”。

HTTP

所有数据传输都必须遵循 HTTP/1.1 协议，而且必须对所有端点使用 HTTPS。因为图谱 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"

我们还对 facebook.com 启用了 includeSubdomains HSTS 指令，但这不会对图谱 API 调用产生不利影响。

托管网址

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

访问口令

通过访问口令，您的应用可以访问图谱 API。几乎对所有图谱 API 端点都必须使用某种访问口令，因此每当访问端点时，都可能需要对您的请求使用访问口令。访问口令通常发挥以下这两种功能：

您的应用可用其访问用户信息，无须使用用户的密码。例如，您的应用需要使用用户的电子邮件才能发挥某种功能。如果用户同意允许您的应用通过 Facebook 检索他们的电子邮件地址，则用户无须为让您的应用获取其电子邮件地址而输入其 Facebook 密码。
通过访问口令，我们可识别您的应用，使用您应用的用户，以及用户已允许您应用访问的数据的类型。

要了解详细信息，请查看我们的访问口令相关文献资料。

节点

节点是有唯一编号的单个对象。例如，用户节点对象有许多，但用户节点对象各有各的编号，各代表一名 Facebook 中的用户。页面、小组、帖子、照片和评论都只是 Facebook 社交关系图谱中的一些节点。

以下 cURL 示例反映的是对用户节点的调用。

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?access_token=ACCESS-TOKEN"

此请求默认情况下会返回以下数据（已用 JSON 设置好格式）：

{
  "name": "Your Name",
  "id": "YOUR-USER-ID"
}

节点元数据

您可以获取节点对象（如用户、页面或照片）的所有字段的清单，包括字段名称、说明和数据类型。对对象编号发送 GET 请求并添加 metadata=1 参数：

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?
    metadata=1&access_token=ACCESS-TOKEN"

得到的 JSON 响应将包含 metadata 属性，可列出指定节点的所有受支持字段：

{
  "name": "Jane Smith",
  "metadata": {
    "fields": [
      {
        "name": "id",
        "description": "The app user's App-Scoped User ID. This ID is unique to the app and cannot be used by other apps.",
        "type": "numeric string"
      },
      {
        "name": "age_range",
        "description": "The age segment for this person expressed as a minimum and maximum age. For example, more than 18, less than 21.",
        "type": "agerange"
      },
      {
        "name": "birthday",
        "description": "The person's birthday.  This is a fixed format string, like `MM/DD/YYYY`.  However, people can control who can see the year they were born separately from the month and day so this string can be only the year (YYYY) or the month + day (MM/DD)",
        "type": "string"
      },
...

/me

/me 节点是可转化成用户或页面（其访问口令目前用于进行 API 调用）对象编号的特殊端点。如果您有用户访问口令，则可用以下方式检索用户的姓名和编号：

curl -i -X GET \
  "https://graph.facebook.com/me?access_token=ACCESS-TOKEN"

连线

连线是两个节点之间的连接。例如，用户节点可与照片相连，照片节点可与评论相连。以下 cURL 示例将返回用户已发布到 Facebook 中的照片的列表。

curl -i -X GET \
  "https://graph.facebook.com/USER-ID/photos?access_token=ACCESS-TOKEN"

返回的每个编号都可以反映出照片节点及其上传到 Facebook 的时间。

    {
  "data": [
    {
      "created_time": "2017-06-06T18:04:10+0000",
      "id": "1353272134728652"
    },
    {
      "created_time": "2017-06-06T18:01:13+0000",
      "id": "1353269908062208"
    }
  ],
}

字段

字段是节点属性。查询节点或连线时，默认情况下会返回一系列字段，如以上示例所示。但可用 fields 参数并列出想要返回的每个字段，从而指定想要返回的字段。这会取代默认字段，仅返回您指定的字段，但始终都会返回对象编号。

以下 cURL 请求中有 fields 参数和用户的姓名、电子邮件地址和头像。

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?fields=id,name,email,picture&access_token=ACCESS-TOKEN"

返回的数据

{
  "id": "USER-ID",
  "name": "EXAMPLE NAME",
  "email": "EXAMPLE@EMAIL.COM",
  "picture": {
    "data": {
      "height": 50,
      "is_silhouette": false,
      "url": "URL-FOR-USER-PROFILE-PICTURE",
      "width": 50
    }
  }
}

复杂参数

大部分参数类型都简单明了，如 bool、string 和 int，但也有可在请求中指定的 list 和 object 类参数。

list 类参数用 JSON 语法指定，例如 ["firstitem", "seconditem", "thirditem"]

object 类参数也用 JSON 语法指定，例如 {"firstkey": "firstvalue", "secondKey": 123}

发布、更新和删除

请查看我们的 Facebook 分享指南，了解如何发布到用户的 Facebook 中，或查看我们的公共主页 API 文档，了解如何发布到页面的 Facebook 动态中。

某些节点允许用 POST 操作更新字段。例如，可按如下方式更新 email 字段：

curl -i -X POST \
  "https://graph.facebook.com/USER-ID?email=YOURNEW@EMAILADDRESS.COM&access_token=ACCESS-TOKEN"

先写后读

对于创建和更新端点，图谱 API 可以立即读取成功发布或更新的对象，并返回相应读取端点支持的所有字段。

默认情况下，将返回创建或更新的对象的编号。要在响应中包含更多信息，请在请求中包含 fields 参数并列出要返回的字段。例如，要向页面动态中发布消息“Hello”，您可以发出以下请求：

curl -i - X POST "https://graph.facebook.com/PAGE-ID/feed?message=Hello&
  fields=created_time,from,id,message&access_token=ACCESS-TOKEN"

以上代码示例的格式是为便于阅读设置的。

此请求会以 JSON 格式的响应返回指定字段，如下所示：

{
  "created_time": "2017-04-06T22:04:21+0000",
  "from": {
    "name": "My Facebook Page",
    "id": "PAGE-ID"
  },
  "id": "POST_ID",
  "message": "Hello",
}

请参阅每个端点的参考文献资料，了解各个端点是否支持先写后读功能，以及可使用哪些字段。

错误

如果读取因故失败（例如，请求返回不存在的字段时失败），则图谱 API 会用标准错误响应作出回应。请查看我们的错误处理指南了解更多信息。

通常可以通过对对象编号执行 DELETE 操作删除节点，如帖子或照片节点：

curl -i -X DELETE \
  "https://graph.facebook.com/PHOTO-ID?access_token=ACCESSS-TOKEN"

通常仅可删除自己创建的节点，但请参阅每个节点的参考指南，了解删除操作相关要求。

Webhooks

通过订阅 Webhooks，您可以接收有关节点更改或与节点互动的通知。请参阅 Webhooks。

版本

图谱 API 有多个版本，每个季度都会发布新版本。通过在请求路径的开头添加“v”和版本号，可在调用中指定版本。例如，下面的示例调用的是版本 4.0：

curl -i -X GET \
  "https://graph.facebook.com/v4.0/USER-ID/photos
    ?access_token=ACCESS-TOKEN"

如果您不添加版本号，我们默认情况下会调用最旧的可用版本，因此建议在请求中添加版本号。

您可以在我们的版本控制指南中详细了解版本，也可在图谱 API 变更日志中了解所有可用版本。

Facebook API、SDK 和平台

可用 Facebook 的各种 API、SDK 和平台连接接口及进行跨平台开发。

后续步骤

开始使用图谱 API — 我们来用图谱探索工具探究 Facebook 社交关系图谱，以及为获取数据而发出几项请求。