用于搜索的 REST API 端点

关于搜索

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

您可以使用查询缩小搜索范围。要了解有关搜索查询语法的更多信息，请参阅“用于搜索的 REST API 端点”。

搜索结果排名

除非作为查询参数提供了其他排序选项，否则结果将按最佳匹配降序排序。将多个因素结合起来，以将最相关的项目提升到结果列表的顶部。

速率限制

REST API 对搜索有自定义速率限制。对于已认证的请求，您可以对所有搜索端点每分钟最多发出 30 个请求，但“搜索代码”端点除外。“搜索代码”端点要求您进行身份验证，并限制您每分钟最多发出 10 个请求。对于未经身份验证的请求，速率限制允许您每分钟最多发出 10 个请求。

有关如何确定您当前速率限制状态的信息，请参阅“速率限制”。

构建搜索查询

每个用于搜索的端点都使用查询参数在 GitHub 上执行搜索。请参阅各个端点以获取包含端点和查询参数的示例。

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

SEARCH_KEYWORD_1 SEARCH_KEYWORD_N QUALIFIER_1 QUALIFIER_N

例如，如果您想搜索由defunkt拥有的所有包含GitHub和Octocat这两个词的README文件中的仓库，则可以使用以下查询与搜索仓库端点一起使用

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命令和上面Issue 搜索示例，我们的 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数组中有两个对象。

第一个文本匹配发生在 Issue 的body属性中。我们看到了来自 Issue 正文的一部分文本。搜索词（windows）在该片段中出现两次，我们有每次出现的索引。

第二个文本匹配发生在 Issue 的其中一条评论的body属性中。我们有 Issue 评论的 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": "Windows",
          "indices": [
            163,
            170
          ]
        }
      ]
    }
  ]
}