低级 GitHub API 请求界面。

摘要

hub api [-it] [-X METHOD] [-H HEADER] [--cache TTL] ENDPOINT [-F FIELD|--input FILE]

选项

-X, --method METHOD

用于请求的 HTTP 方法（默认："GET"）。如果使用 --field、--raw-field 或 --input，方法会自动设置为 "POST"。

使用 -XGET 针对 GET 请求强制序列化字段到查询字符串中，而不是 POST 请求的 JSON 正文中。

-F, --field KEY=VALUE

用请求序列化的数据。对于 VALUE 有一些特殊的处理；对发送任意字符串值使用 --raw-field。

如果 VALUE 以 "@" 开头，那么值的其余部分会被解释为要从中读取该值的的文件名。使用 "@" 以从标准输入读取。

如果 VALUE 是 "true"、"false"、"null" 或看起来像一个数字，那么会使用一个合适的 JSON 类型来代替一个字符串。

不能将 VALUE 序列化为嵌套的 JSON 数组或哈希。相反，请外部构建请求有效负载并通过 --input 传递它。

除非使用了 -XGET，否则所有字段都会被序列化并作为 JSON 发送到请求正文中。当 ENDPOINT 为 "graphql" 时，除 "query" 之外的所有字段都会被归到 "variables" 下。请参阅 https://graphql.net.cn/learn/queries/#variables

-f, --raw-field KEY=VALUE

与 --field 相同，除了它允许以 "@" 开头的值、字面字符串 "true"、"false" 和 "null"，以及看起来像数字的字符串。

--input FILE

文件名，用于从中读取原始请求正文。使用 "-" 以从标准输入读取。当要手动构建请求有效负载时使用此选项。

-H, --header KEY:VALUE

设置一个 HTTP 请求头。

-i, --include

在输出中包含 HTTP 响应头。

-t, --flat

解析响应 JSON，并以行分隔键值格式输出数据，这些格式适合在 shell 脚本中使用。

--paginate

自动请求并输出下一页结果，直到列出所有资源。对于 GET 请求，这会跟随 "Link" 响应头中指示的 <next> 资源。对于 GraphQL 查询，这会利用 pageInfo，它必须存在于查询中；请参阅示例。

请注意，多个 JSON 文档将作为结果输出。如果 API 速率限制已达到，则输出的最终文档将是 HTTP 403 通知，该进程将以非零状态退出。避免这种情况的一种方法是启用 --obey-ratelimit。

--color[=WHEN]

即使 stdout 不是一个终端，也会启用彩色输出。 WHEN 可以是“always”（--color 的默认值）、“never”或“auto”（默认值）。

--cache TTL

对 GET 请求的有效响应进行缓存 TTL 秒。

当使用“graphql”作为 ENDPOINT 时，缓存也适用于对 POST 请求的响应。只需确保不为任何 GraphQL 突变使用 --cache。

--obey-ratelimit

在超过 API 速率限制后，暂停进程，直到当前速率限制窗口的重置时间并重试请求。请注意，这可能会导致进程挂起很长时间（最大 1 小时）。

ENDPOINT

向其发送 HTTP 请求的 GitHub API 端点（默认值：/）。

要了解可用的端点，请参阅 https://developer.github.com/v3/。要执行 GraphQL 查询，请使用“graphql”作为 ENDPOINT 并传递 -F query=QUERY。

如果字符串常量“{owner}”或“{repo}”出现在 ENDPOINT 或 GraphQL “query”字段中，请使用从当前 git 存储库的 git 远程配置中读取的值来填充这些占位符。

示例

# fetch information about the currently authenticated user as JSON
$ hub api user

# list user repositories as line-based output
$ hub api --flat users/octocat/repos

# post a comment to issue #23 of the current repository
$ hub api repos/{owner}/{repo}/issues/23/comments --raw-field 'body=Nice job!'

# perform a GraphQL query read from a file
$ hub api graphql -F query=@path/to/myquery.graphql

# perform pagination with GraphQL
$ hub api --paginate graphql -f query='
  query($endCursor: String) {
    repositoryOwner(login: "USER") {
      repositories(first: 100, after: $endCursor) {
        nodes {
          nameWithOwner
        }
        pageInfo {
          hasNextPage
          endCursor
        }
      }
    }
  }
'

另请参阅

hub(1)