搜索 - GitHub Docs

使用 REST API 在 GitHub 上搜索特定项。

关于搜索

可以使用 REST API 搜索要查找的特定项。例如，您可以在仓库中找到用户或特定文件。就像您在 Google 上执行搜索一样。它旨在帮助您找到要查找的一个或几个结果。就像在 Google 上搜索一样，有时您希望查看几页搜索结果，以便找到最能满足您需求的条目。为了满足这一需求，GitHub REST API 为每个搜索提供最多 1,000 个结果。

您可以使用查询缩小搜索范围。若要详细了解搜索查询语法，请参阅“构造搜索查询”。

排列搜索结果

除非提供另一个排序选项作为查询参数，否则将按照最佳匹配的原则对结果进行降序排列。多种因素相结合，将最相关的条目顶到结果列表的顶部。

速率限制

REST API 具有用于搜索的自定义速率限制。对于使用基本身份验证、OAuth 或客户端 ID 和机密的请求，每分钟最多可发出 30 个请求。对于未经身份验证的请求，速率限制允许每分钟最多发出 10 个请求。

有关确定当前速率限制状态的详细信息，请参阅速率限制文档。

构造搜索查询

每个搜索终结点使用查询参数对 GitHub 执行搜索。有关包含终结点和查询参数的示例，请参阅各个终结点。

查询可以包含在 GitHub 上支持的搜索限定符的任意组合中。搜索查询的格式为：

SEARCH_KEYWORD_1 SEARCH_KEYWORD_N QUALIFIER_1 QUALIFIER_N

例如，如果要搜索 defunkt 拥有的在自述文件中包含单词 GitHub 和 Octocat 的所有存储库，可在“搜索存储库”终结点中使用以下查询：

GitHub Octocat in:readme user:defunkt

注意：请务必使用语言的首选 HTML 编码器构造查询字符串。例如：

// JavaScript
const queryString = 'q=' + encodeURIComponent('GitHub Octocat in:readme user:defunkt');

有关可用限定符及其格式的完整列表和使用示例，请参阅“在 GitHub 上搜索”。有关如何使用运算符匹配特定数量、日期或排除结果，请参阅“了解搜索语法”。

查询长度限制

不能使用满足以下条件的查询：

超过 256 个字符（不包括运算符或限定符）。
拥有超过五个 AND、OR 或 NOT 运算符。

这些搜索查询将返回“验证失败”错误消息。

搜索范围限制

为了让所有人都能快速使用 REST API，我们限制了查询将搜索的存储库数。 REST API 将查找最多 4,000 个与筛选器匹配的存储库，并从这些存储库返回结果。

超时和不完整的结果

为了让所有人都能快速使用 REST API，我们限制了任何单个查询能够运行的时长。对于超出时间限制的查询，API 将返回超时之前已找到的匹配项，并且响应的 incomplete_results 属性设为 true。

达到超时并不意味着搜索结果不完整，可能已找到更多结果，也可能没有找到。

访问错误或缺少搜索结果

需要成功完成身份验证并对搜索查询中的存储库具有访问权限，否则，你将看到 422 Unprocessable Entry 错误和“验证失败”消息。例如，如果查询中包含 repo:、user: 或 org: 限定符，但这些限定符请求的资源是你登录 GitHub 后无权访问的资源，则搜索将失败。

当搜索查询请求多个资源时，响应将只包含你有权访问的资源，并且不会提供列出未返回资源的错误消息。

例如，如果搜索查询要搜索 octocat/test 和 codertocat/test 存储库，但你只拥有对 octocat/test 的访问权限，则响应将显示对 octocat/test 的搜索结果，而不会显示对 codertocat/test 的搜索结果。此行为类似于 GitHub 上的搜索方式。

文本匹配元数据

在 GitHub 上，可使用搜索结果中的代码片段和突出显示内容提供的上下文。搜索终结点返回额外的元数据，允许你在显示搜索结果突出显示匹配搜索词。

请求可以选择在响应中接收这些文本片段，并且每个片段都附带数字偏移，以标识每个匹配搜索词的确切位置。

若要在搜索结果中获取这种元数据，请在 Accept 标头中指定 text-match 媒体类型。

application/vnd.github.text-match+json

提供 text-match 媒体类型时，你将在 JSON 有效负载中收到一个额外的键，名为 text_matches，它提供有关搜索词在文本中的位置以及包含该搜索词的 property 的信息。在 text_matches 数组中，每个对象都包含以下属性：

名称	说明
`object_url`	包含匹配某个搜索词的字符串属性的资源 URL。
`object_type`	在给定 `object_url` 中存在的资源类型的名称。
`property`	在 `object_url` 中存在的资源属性的名称。属性是与某个搜索词相匹配的字符串。（在从 `object_url` 返回的 JSON 中，`fragment` 的完整内容存在于具有此名称的属性中。）
`fragment`	`property` 值的子集。这是与一个或多个搜索词匹配的文本片段。
`matches`	存在于 `fragment` 中的一个或多个搜索词组成的数组。索引（即“偏移量”）与片段相关。（它们与 `property` 的完整内容无关。）

示例

使用 curl 命令和上面的示例问题搜索时，API 请求如下所示：

curl -H 'Accept: application/vnd.github.text-match+json' \
'https://api.github.com/search/issues?q=windows+label:bug \
+language:python+state:open&sort=created&order=asc'

对于每个搜索结果，响应将包含一个 text_matches 数组。在下面的 JSON 中，text_matches 数组中有两个对象。

第一个文本匹配出现在问题的 body 属性中。我们从议题正文中看到了文本片段。搜索词 (windows) 在该片段中出现了两次，我们有每次出现时的索引。

第二个文本匹配出现在其中一个问题注释的 body 属性中。我们有议题注释的 URL。当然，我们从注释正文中看到了文本片段。搜索词 (windows) 在该片段中出现了一次。

{
  "text_matches": [
    {
      "object_url": "https://api.github.com/repositories/215335/issues/132",
      "object_type": "Issue",
      "property": "body",
      "fragment": "comprehensive windows font I know of).\n\nIf we can find a commonly
      distributed windows font that supports them then no problem (we can use html
      font tags) but otherwise the '(21)' style is probably better.\n",
      "matches": [
        {
          "text": "windows",
          "indices": [
            14,
            21
          ]
        },
        {
          "text": "windows",
          "indices": [
            78,
            85
          ]
        }
      ]
    },
    {
      "object_url": "https://api.github.com/repositories/215335/issues/comments/25688",
      "object_type": "IssueComment",
      "property": "body",
      "fragment": " right after that are a bit broken IMHO :). I suppose we could
      have some hack that maxes out at whatever the font does...\n\nI'll check
      what the state of play is on Windows.\n",
      "matches": [
        {
          "text": "W