Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.
 
2022-11-28 (latest)

 

The REST API is now versioned. For more information, see "About API versioning."

検索

この REST API を使い、GitHub で特定のアイテムを検索します。

検索について

この REST API を使って特定の項目を検索できます。 たとえば、リポジトリ内のユーザや特定のファイルを見つけることができます。 Google で検索を実行するのと同じように考えてください。 Search API は、探している 1 つの結果 (または探しているいくつかの結果) を見つけるために役立つよう設計されています。 Google で検索する場合と同じように、ニーズに最も合う項目を見つけるため、検索結果を数ページ表示したい場合もあるでしょう。 こうしたニーズを満たすため、GitHub REST API は、検索ごとに最大 1,000 件の結果を提供します。

クエリを使って、検索を絞り込めます。 検索クエリ構文の詳細については、「検索クエリの構築」を参照してください。

検索結果を順番づける

クエリパラメータとして別のソートオプションが指定されない限り、結果は最も一致するものから降順にソートされます。 最も関連性の高い項目を検索結果の最上位に押し上げるように、複数の要素が組み合わされます。

レート制限

この REST API では、検索にカスタムのレート制限があります。 基本認証、OAuth、またはクライアント ID とシークレットを使用する要求の場合、1 分あたり最大 30 件の要求を作成できます。 認証されていない要求の場合、レート制限を使用すると、1 分あたり最大 10 件の要求を作成できます。

現在のレート制限の状態を特定するための詳細については、レート制限に関するドキュメントを参照してください。

検索クエリの構築

検索の各エンドポイントではクエリ パラメーターを使い、GitHub で検索します。 エンドポイントとクエリ パラメーターを含む例については、個々のエンドポイントを参照してください。

クエリには、GitHub でサポートされている検索修飾子を任意に組み合わせて使用できます。 検索クエリの形式は次のとおりです。

SEARCH_KEYWORD_1 SEARCH_KEYWORD_N QUALIFIER_1 QUALIFIER_N

たとえば、defunkt が所有するリポジトリで、README ファイルに 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 演算子が 5 つ以上ある。

こうした検索クエリを使用すると、「Validation failed」というエラーメッセージが返されます。

検索範囲の制限

すべてのユーザーのために高速な REST API を維持する目的で、クエリによって検索されるリポジトリの数を制限しています。 この REST API では、フィルターに一致するリポジトリが最大 4,000 個検索され、それらのリポジトリから結果が返されます。

タイムアウトと不完全な結果

すべてのユーザーのために高速な REST API を維持する目的で、個々のクエリの実行時間を制限しています。 制限時間を超えるクエリの場合、タイムアウト前に既に見つかった一致を API が返し、応答では incomplete_results プロパティが true に設定されます。

タイムアウトになったことは、必ずしも検索結果が未完了であるということではありません。 もっと多くの検索結果が出たかもしれませんし、出ていないかもしれません。

アクセスエラーまたは検索結果の欠落

検索クエリでリポジトリを正常に認証してアクセスできるようにする必要があります。それ以外の場合は、"検証に失敗しました" というメッセージが表示される 422 Unprocessable Entry エラーが表示されます。 たとえば、GitHub にサインインしたときにアクセスできないリソースを要求する repo:、user:、または org: 修飾子がクエリに含まれている場合、検索は失敗します。

検索クエリが複数のリソースを要求すると、応答にはアクセスできるリソースのみが含まれ、返されなかったリソースを一覧表示するエラー メッセージは表示されません。

たとえば、検索クエリが octocat/test および codertocat/test リポジトリを検索しても、octocat/test へのアクセス権しかない場合は、応答には octocat/test の検索結果が表示され、codertocat/test の検索結果は表示されません。 この振る舞いは、GitHub における検索の仕組みと同じです。

テキスト一致メタデータ

GitHub では、コードスニペットが提供するコンテキストと、検索結果のハイライトが使用できます。 検索のためのエンドポイントからは、検索結果を表示するときに、検索と一致した言葉をハイライトできる付加的なメタデータが返されます。

code-snippet-highlighting

リクエストでは、レスポンスに含まれるテキストフラグメントを受け取ることを選べます。各フラグメントには、一致した各検索用語の正確な場所を特定する数値オフセットが付属しています。

検索結果でこのメタデータを取得するには、Accept ヘッダーで text-match メディアの種類を指定します。

application/vnd.github.text-match+json

text-match メディアの種類を指定すると、JSON ペイロード内にある text_matches と呼ばれる追加のキーを受け取ります。これは、テキスト内の検索用語の位置と、検索用語を含む property についての情報を提供します。 text_matches 配列内では、各オブジェクトに次の属性が含まれます。

名前説明
object_url検索用語のいずれかに一致する文字列プロパティを含むリソースの URL。
object_type指定された object_url に存在するリソースの種類の名前。
propertyobject_url に存在するリソースのプロパティの名前。 このプロパティは、検索用語のいずれかに一致する文字列です。 (object_url から返される JSON では、fragment の完全なコンテンツは、この名前でプロパティから検索できます。)
fragmentproperty の値のサブセット。 これは、1 つ以上の検索用語に一致するテキストフラグメントです。
matchesfragment に存在する 1 つ以上の検索用語の配列。 インデックス (すなわち「オフセット」) は、フラグメントと関連しています。 (それらは 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 配列に 2 つのオブジェクトがあります。

最初のテキスト一致は、issue のbody プロパティで発生しました。 Issue 本文から、テキストのフラグメントが表示されています。 検索用語 (windows) はそのフラグメント内に 2 回表示され、それぞれにインデックスがあります。

2 番目のテキスト一致は、issue のコメントのうちの 1 つの body プロパティで発生しました。 Issue コメントの URL があります。 そしてもちろん、コメント本文から、テキストのフラグメントが表示されています。 そのフラグメント内に検索用語 (windows) が 1 回表示されます。

{
  "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 o