图谱 API 参考文档

概览

Workplace 图谱 API 可用于以编程方式存取 Workplace 数据。这是一个基于 HTTP 的低级别 API，您可以用其查询有关 Workplace 图谱中的对象的数据。

图谱 API 得名于“图谱数据模型”理念，其中的对象由节点及相关联的连线表示。在 API 级别，这是应用访问 Workplace 中信息的方式。Workplace 图谱 API 支持 Facebook 图谱 API 的功能子集。此功能仅限与 Workplace 社群的互动，可能在某些情况下为提高性能或易用性而有所不同。

Workplace 图谱 API 对象

您可以借助自定义集成或第三方应用访问口令，通过 Workplace 图谱 API 访问以下节点。

Community

Workplace 社群。Workplace 图谱 API 调用的根小组。

Groups

Workplace 小组。

Posts

小组中或成员的个人主页上发布的帖子。

Members

特定 Workplace 用户的帐户。此节点还可用于查看和编辑相应用户接收和发送的消息。

Skills

添加到成员个人主页的技能。

Event

Workplace 社群或小组活动。

Category

资料库中存储公司重要内容的类别。

People Set

使用条件或清单定义的一组用户。

Reported Content

Workplace 中已报告给管理员审核的内容。

Shift

Workplace 中小时工的代班安排数据。

Survey

已在 Workplace 中创建的问卷。

Data Export

从 Workplace 中批量导出数据的数据导出作业。

如需查看通过使用多个图谱 API 调用解决具体问题的示例，请查看示例应用清单。

使用图谱 API

图谱 API 对象

图谱 API 是 Workplace 中信息的表示方式，由以下部分组成：

• 节点 - 用户、照片、帖子或评论等对象
• 连线 - 上述元素之间的关联，例如帖子的文件或照片的评论
• 字段 - 关于对象的元数据，例如用户的姓名或小组的隐私设置

Workplace 图谱中每项内容均由独立编号表示。小组、成员、帖子，甚至评论都有其编号，这些编号可用于从图谱 API 中检索特定内容的相关信息。

管理社群

各个 Workplace 社群之间相互独立，您仅可以使用图谱 API 访问您所属社群中的内容，以及您所属社群的成员已加入的公司间合作小组中的内容。

为便于管理图谱 API 访问权限，您所属的社群会被视为小组。您可以将所属社群视为根小组，将其中所有小组添加为子组。如要在图谱 API 中检索关于您所属社群的信息，您将需要社群编号。您可以向 graph.facebook.com/community 发出 HTTP GET 请求，并提供有效的应用访问口令，从而以编程方式从图谱 API 检索此编号。

图谱 API 版本管理

Workplace 图谱 API 依托于 Facebook 开放平台图谱 API 而构建。这意味着，该 API 会继承 Facebook 上使用的相同 API 版本管理行为。

图谱 API 版本每 3 个月左右发布一次，各个 Workplace API 和 Facebook API 的更改将在图谱 API 更新日志中发布。

向图谱 API 发出 API 调用时，您可以在 API 路径中指定版本，如下所示：

      https://graph.facebook.com/v2.11/community/groups
    

不过，可用版本也有一些限制：

• 新版本发布时，该版本将成为当前 API 版本，并保证在发布后 2 年内有效。
• 创建应用时，将默认使用创建时的当前 API 版本，此版本将成为该应用可用的最低 API 版本。
• 应用发出 API 调用时可以任意指定 API 版本，但无法向已停用的 API 版本或低于应用最低 API 版本的版本发出调用。
• 无版本号的 API 调用将默认使用应用的最低 API 版本。

新的自定义集成创建后，系统会将其可用的最低 API 版本作为创建时的当前 API 版本。此最低版本将影响图谱 API 调用和 Webhooks 订阅。

查看图谱 API 版本

如果您不确定自己使用的是哪个版本，可以通过一些方式查看。如要查看您的应用支持使用哪些版本的图谱 API，可以向 API 调用添加 debug 参数。

      https://graph.facebook.com/community?debug=all
    

这将额外返回调试信息，用以确认所使用的版本。

      {
         "name": "Example Community",
         "privacy": "CLOSED",
         "id": "855210357923606",
         "__debug__": {
            "messages": [
               {
                  "link": "https://developers.facebook.com/docs/apps/versions/",
                  "message": "No API version was specified. This request defaulted to version v2.8.",
                  "type": "warning"
               }
            ]
         }
      }
    

如果您尝试使用的版本低于应用的最低 API 版本，debug 消息将出现提示。

      https://graph.facebook.com/v2.6/community?debug=all
      
      {
         "name": "Example Community",
         "privacy": "CLOSED",
         "id": "855210357923606",
         "__debug__": {
            "messages": [
               {
                  "link": "https://developers.facebook.com/docs/apps/versions/",
                  "message": "The app tried to call version v2.6. This app can only call versions v2.8 and higher, so the request defaulted to version v2.8.",
                  "type": "warning"
               }
            ]
         }
      }
    

查看 Webhooks 版本

如果 Webhooks 订阅是通过自定义集成弹出式对话框完成，或指定 API 版本的订阅是通过图谱 API 订阅端点 /app/subscriptions 完成，则 Webhooks 订阅使用最低 API 版本。

您可以使用订阅端点确认每个 Webhooks 字段和主题所应用的 Webhooks 版本。此端点需要应用访问口令。

      https://graph.facebook.com/v2.11/app/subscriptions
      
      {
        "data": [
          {
            "object": "group",
            "callback_url": "https://www.example.com/callback",
            "active": true,
            "fields": [
              {
                "name": "comments",
                "version": "v2.8"
              },
      ...
    

使用访问口令

获取应用访问口令

如需为您的社群发出任何图谱 API 调用，您将需要创建应用，并检索访问口令。您将需要创建新的自定义集成，然后为其授予您要构建的功能所需的权限。

如需详细了解如何创建应用和权限模型，请参阅权限指南。

获取成员访问口令

应用访问口令可让应用访问并社群范围内的对象并与之互动，而成员访问口令可让服务代表特定帐户发出调用。

您可以按以下方法获取成员访问口令：向给定成员的 /member_id 端点发出 GET 请求，使用管理员访问口令并请求额外字段 impersonate_token。

此功能需要发出调用的应用的模拟权限。