Конечные точки REST API для поиска

О поиске

REST API можно использовать для поиска определенного элемента, который требуется найти. Например, можно найти пользователя или определенный файл в репозитории. Это похоже на поиск в Google. API поиска предназначен для поиска одного результата, который вы ищете (или, возможно, несколько результатов). Так же, как при поиске в Google, иногда требуется просмотреть несколько страниц результатов поиска, чтобы найти элемент, который лучше всего соответствует вашим требованиям. Для удовлетворения этих потребностей REST API GitHub Enterprise Server предоставляет до 1000 результатов для каждого поиска.

Поиск можно сузить с помощью запросов. Дополнительные сведения о синтаксисе поискового запроса см. в разделе "Конечные точки REST API для поиска".

Ранжирование результатов поиска

Если в качестве параметра запроса не указан другой параметр сортировки, результаты сортируются по лучшему совпадению в порядке убывания. Для повышения вероятности появления наиболее релевантного элемента в верхней части списка результатов используется множество факторов.

Ограничение скорости

REST API имеет настраиваемое ограничение скорости для поиска. Для прошедших проверку подлинности запросов можно выполнять до 30 запросов в минуту. Для запросов без проверки подлинности ограничение скорости позволяет выполнять не более 10 запросов в минуту.

Сведения о том, как определить текущее состояние ограничения скорости, см. в разделе "Ограничение скорости".

Создание поискового запроса

Каждая конечная точка для поиска использует параметры запроса для выполнения поиска по GitHub Enterprise Server. Примеры, включающие параметры конечной точки и запроса, см. в отдельных конечных точках.

Запрос может содержать любое сочетание квалификаторов поиска, поддерживаемых в GitHub Enterprise Server. Формат поискового запроса:

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 найдет до 4000 репозиториев, которые соответствуют фильтрам и возвращают результаты из этих репозиториев.

Время ожидания и неполные результаты

Чтобы обеспечить быструю настройку 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можно использовать контекст, предоставленный фрагментами кода и выделениями в результатах поиска. Конечные точки для поиска возвращают дополнительные метаданные, которые позволяют выделить соответствующие условия поиска при отображении результатов поиска.

Запросы могут принимать эти фрагменты текста в ответе, и каждый фрагмент сопровождается числовыми смещениями, определяющими точное расположение каждого соответствующего поискового термина.

Чтобы получить эти метаданные в результатах поиска, укажите тип данных text-match в заголовке Accept.

application/vnd.github.text-match+json

При указании типа данных text-match вы получите дополнительный ключ text_matches в полезных данных JSON, который содержит сведения о позиции поисковых терминов в тексте, и свойство property с поисковым термином. Внутри массива text_matches каждый объект содержит следующие атрибуты:

Имя	Описание
object_url	URL-адрес ресурса, содержащего строковое свойство, соответствующее одному из поисковому термину.
object_type	Имя типа ресурса в этом объекте object_url.
property	Имя свойства ресурса в object_url. Это свойство является строкой, которая соответствует одному из поисковых терминов. (В JSON, возвращенном из object_url, полное содержимое свойства fragment будет находится в свойстве с этим именем.)
fragment	Подмножество значения property. Это фрагмент текста, соответствующий одному или нескольким поисковым терминам.
matches	Массив из одного или нескольких поисковых терминов, присутствующих в свойстве fragment. Индексы (т. е. смещения) относительно фрагмента. (Они не относятся к полному содержимому свойства property.)

Пример

Используя команду и приведенный curl выше пример поиска проблемы, запрос API будет выглядеть следующим образом:

curl -H 'Accept: application/vnd.github.text-match+json' \
'http(s)://<em>HOSTNAME</em>/api/v3/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": "Windows",
          "indices": [
            163,
            170
          ]
        }
      ]
    }
  ]
}