让我们利用Annict的GraphQL API获取动漫数据

「Annict」动漫观赏记录网络服务的GraphQL API已经发布。虽然还不够完善，但已经能够实现几乎与现有的REST API相同的功能。

Annict博客已发布GraphQL API（Beta版）。

我們將以教程形式介紹如何使用GraphQL API獲取動畫數據。

环境

• macOS Sierra 10.12.5

 

GraphiQL.app 0.5.1

生成访问令牌

要访问GraphQL API，需要Annict的访问令牌。生成访问令牌有两种方法。

创建一个应用并进行OAuth认证，使用“个人访问令牌”。

这次将使用2个个人访问令牌进行生成。

首先，访问https://annict.com/settings/apps。然后，点击“个人访问令牌”下的“新建”按钮。

打开页面后，会显示如下图所示的输入框。在“令牌说明”中，您可以输入适当的用途等内容。选择“只读”作为“作用域”。这是因为本次只需要获取动画数据，不需要进行写入操作。

当您点击“创建”按钮时，将显示如下的访问令牌。请复制到剪贴板，因为如果页面重新加载等操作，访问令牌将不再显示。

通过这个，获得了访问令牌。

安装GraphiQL.app。

当编写和执行 GraphQL 查询时，使用”GraphiQL”工具非常方便。这是一个运行在Web浏览器上的 GraphQL IDE。本次我们将使用 “GraphiQL.app” 作为 Mac 客户端。GraphiQL.app 可以使用 Homebrew 进行安装。

$ brew cask install graphiql

配置GraphiQL.app以使GraphQL API可调用。

我将以下两个设置到GraphiQL.app中。

1. 请指定GraphQL API的端点URL

 

将最初获取的访问令牌注册到请求头中

打开GraphiQL.app后会显示如下图所示的窗口。左侧栏写着“Welcome to GraphiQL”，那是用来输入GraphQL查询的地方，而右侧栏则是用来展示查询结果的地方。顺便提一下，“Welcome to GraphiQL”是一条注释，可以删除它并不会有问题。（尽管截图上右侧出现了错误，请不要在意…）

将下面的端点输入到「GraphQL Endpoint」的输入框中。

https://api.annict.com/graphql

当向GraphQL API发出请求时，端点始终为此URL。

下面是一种可能的中文翻译：
接下来将访问令牌注册到标头中。点击名为“编辑HTTP标头”的蓝色按钮，您就可以设置请求标头。

点击「添加头」，然后按照以下方式设置 Authorization 头。

• Header name: Authorization

Header value: Bearer (アクセストークン)

以上是GraphiQL.app的配置已經完成。

从Annict获取数据

既经完成了一系列的设定，现在只需要编写GraphQL查询并获取数据了。首先，我们先尝试获取生成访问令牌的用户（也就是我自己）的信息。

我试着在左侧的查询输入栏中写下以下查询。

query {
  viewer {
    username
    name
  }
}

查看者在Annict提供的查询中返回执行查询的用户信息 (User类型)。(关于查看者的文档)
在上面的示例中，只获取了用户名(username)和姓名(name)。

在输入查询后，点击输入框上方类似播放按钮的东西，右侧会显示获取结果。

在用户类型中，除了用户名和姓名之外，还存在各种不同的字段。请查看文档以获取更多详细信息。

获取动漫数据

由于已经对GraphQL查询进行了一番操作，现在进入到最后一步，即获取动漫数据。这次我希望获取以下类似的数据。

1. 从2017年春季动画中

 

1. 提取动画的标题和“正在观看”“想观看”的人数（观看者数）

 

1. 按观看者数从高到低获取3个动画

 

同时获取每个动画的每一集。

可以根据条件分条列出。要通过Annict的REST API获取满足这些条件的数据，请：

1. 调用 GET /v1/works 一次，获取符合条件1至3的动画片。

调用 GET /v1/episodes 三次（与已获取的动画片数量相同），获取第四集的剧集数据。

使用GraphQL API，可以在一次请求中获取上述的动画数据。

由於話題稍微偏離，我們回到正題。我們將逐一將四個條件轉化為查詢。

首先，可以这样表述第一项“从2017年春季动漫中”。

query {
  searchWorks(seasons: ["2017-spring"]) {
  }
}

searchWorks是由Annict提供的查询，可以获取符合各种条件的动画。这些”各种条件”可以通过参数来指定，这次我们使用了名为seasons的选项来获取”2017年春季动画”。值得一提的是，由于seasons的值可以传递一个数组，因此也可以同时获取2017年冬季动画和春季动画。

query {
  searchWorks(seasons: ["2017-winter", "2017-spring"]) {
  }
}

以下是用中文可以表达为：可以按以下方式提取动漫的标题以及“正在观看”和“想要观看”的人数（观看者数量）。

query {
  searchWorks(seasons: ["2017-spring"]) {
    edges {
      node {
        title
        watchersCount
      }
    }
  }
}

邊緣和節點等相關元素被提及，這是符合GraphQL所推薦的分頁資料結構的欄位。詳細資訊請參閱「分頁 | GraphQL」。

基本上，在 node 中指定每种类型的字段。searchWorks 通过 WorkConnection 类型返回 Work 类型，因此可以指定表示动漫标题的 title 和表示观看人数的 watchersCount。

可以执行上述查询。执行后，您可能会获得2017年春季动画的标题和观看人数等信息。

可以通过在searchWorks的参数中指定orderBy和first选项，来获得按观看次数降序排列的3个条目。

query {
  searchWorks(
    seasons: ["2017-spring"],
    orderBy: { field: WATCHERS_COUNT, direction: DESC },
    first: 3
  ) {
    edges {
      node {
        title
        watchersCount
      }
    }
  }
}

首先，orderBy选项需要一个包含field和direction键的对象作为值。在field中指定希望排序的字段，在direction中指定排序顺序。在本例中，传递的值分别是WATCHERS_COUNT和DESC，所以意思是“按照关注者数量从多到少排序”。

第一个选项可以指定一个数字作为值。您可以获取与指定数字相对应的最初数据。由于使用orderBy选项进行排序，条件变为“按照观看人数从多到少获取前3条数据”。

执行上述命令后，我认为只能获得Annict上观看人数最多的3部动画。小沙雾太可爱了，小沙雾。

在使用GraphiQL.app编写查询的人可能已经注意到了，GraphiQL的查询编辑功能可以自动补全字段和参数等。这非常方便，即使不熟悉GraphQL API的情况下，也可以凭直觉编写查询，大致了解内部的数据结构。

即使用代码编写比较困难的情况下，你也可以通过文档参考功能快速查看该类型有哪些字段等信息。

我又跑题了。实现最后一个条件，即”获取每个剧集”，可以按以下方式进行。

query {
  searchWorks(
    seasons: ["2017-spring"],
    orderBy: { field: WATCHERS_COUNT, direction: DESC },
    first: 3
  ) {
    edges {
      node {
        title
        watchersCount
        episodes(
          orderBy: { field: SORT_NUMBER, direction: ASC },
          first: 2
        ) {
          edges {
            node {
              number
              title
            }
          }
        }
      }
    }
  }
}

由于可以从Work类型中引用episodes字段，因此我调用了它。我设置了选项，以按顺序获取前2个，并且还可以通过指定参数来调整episodes字段的排序和获取数量，就像searchWorks一样。当然，还可以对number或title字段进行筛选。

终结

教程至此结束。实际上，获取数据不仅仅是获取数据，还需要对获取到的数据进行处理，并在网站或应用程序上进行显示。在这种情况下，我们需要使用各种语言的GraphQL客户端库。例如，在Ruby中，“github/graphql-client”似乎是最常用的选项。每种语言的库可以在“awesome-graphql”等地方进行确认。

如果这个文件能够成为使用Annict的GraphQL API的应用程序或服务的初始条件，那就再好不过了。

链接

• https://annict.com

 

AnnictのGraphQL APIの概要