paginate-json

从分页API检索JSON的CLI工具。

该工具针对使用HTTP Link头部进行分页的API。GitHub API是此类的一个例子。

使用此工具的食谱

• 使用jq和paginate-json合并GitHub的发布说明
• 导出Mastodon时间线到SQLite

安装

pip install paginate-json

或者使用pipx

pipx install paginate-json

使用方法

运行此工具针对返回JSON项目列表并使用link: HTTP头部指示下一页结果URL的URL。

它将输出一个包含所有记录的JSON列表，跨越多页。

paginate-json \
  https://api.github.com/users/simonw/events

您可以使用--header选项发送额外的请求头部。例如，如果您有一个GitHub OAuth令牌，可以像这样传递

paginate-json \
  https://api.github.com/users/simonw/events \
  --header Authorization "bearer e94d9e404d86..."

某些API可能会返回一个根级别对象，其中您希望收集的项目存储在一个键中，例如Datasette JSON API中的此示例

{
  "ok": true,
  "rows": [
    {
      "id": 1,
      "name": "San Francisco"
    },
    {
      "id": 2,
      "name": "Los Angeles"
    },
    {
      "id": 3,
      "name": "Detroit"
    },
    {
      "id": 4,
      "name": "Memnonia"
    }
  ]
}

在这种情况下，使用--key rows指定要从中提取项目的键

paginate-json \
  https://latest.datasette.io/fixtures/facet_cities.json \
  --key rows

默认情况下，输出JSON将以美化打印的JSON数组的形式流式传输。

要切换到按行分隔的JSON，每行一个对象，请添加--nl

paginate-json \
  https://latest.datasette.io/fixtures/facet_cities.json \
  --key rows \
  --nl

该命令的输出如下

{"id": 1, "name": "San Francisco"}
{"id": 2, "name": "Los Angeles"}
{"id": 3, "name": "Detroit"}
{"id": 4, "name": "Memnonia"}

与sqlite-utils一起使用

此工具与sqlite-utils配合使用效果很好。例如，以下是将GitHub项目的所有问题加载到本地SQLite数据库中的方法。

paginate-json \
  "https://api.github.com/repos/simonw/datasette/issues?state=all&filter=all" \
  --nl | \
  sqlite-utils upsert /tmp/issues.db issues - --nl --pk=id

您可以使用 sqlite-utils 的其他功能 来增强结果数据库。例如，要启用对问题标题和正文列的全文搜索

sqlite-utils enable-fts /tmp/issues.db issues title body

使用 jq 转换每一页

如果您安装了可选的 jq 或 pyjq 依赖项，您还可以传递 --jq PROGRAM 来使用 jq 程序 转换每一页的结果。您提供的 jq 选项应将每个检索到的结果页转换为对象数组。

例如，从每个问题中提取 id 和 title

paginate-json \
  "https://api.github.com/repos/simonw/datasette/issues" \
  --nl \
  --jq 'map({id, title})'

paginate-json --help

Usage: paginate-json [OPTIONS] URL

  Fetch paginated JSON from a URL

  Example usage:

      paginate-json https://api.github.com/repos/simonw/datasette/issues

Options:
  --version                Show the version and exit.
  --nl                     Output newline-delimited JSON
  --key TEXT               Top-level key to extract from each page
  --jq TEXT                jq transformation to run on each page
  --accept TEXT            Accept header to send
  --sleep INTEGER          Seconds to delay between requests
  --silent                 Don't show progress on stderr - default
  -v, --verbose            Show progress on stderr
  --show-headers           Dump response headers out to stderr
  --ignore-http-errors     Keep going on non-200 HTTP status codes
  --header <TEXT TEXT>...  Send custom request headers
  --help                   Show this message and exit.