14 KiB
title, intro, versions, topics, miniTocMaxHeadingLevel, redirect_from, ms.openlocfilehash, ms.sourcegitcommit, ms.translationtype, ms.contentlocale, ms.lasthandoff, ms.locfileid
| title | intro | versions | topics | miniTocMaxHeadingLevel | redirect_from | ms.openlocfilehash | ms.sourcegitcommit | ms.translationtype | ms.contentlocale | ms.lasthandoff | ms.locfileid | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Поиск | API поиска позволяет искать определенные элементы в {% data variables.product.product_name %}. |
|
|
3 |
|
71f21fc712f7c2121b780d79d20eb9615ad82c90 | 47bd0e48c7 |
HT | ru-RU | 09/05/2022 | 147110364 |
Сведения об API поиска
API поиска помогает найти определенный элемент. Например, можно найти пользователя или определенный файл в репозитории. Это похоже на поиск в Google. API поиска предназначен для поиска одного результата, который вы ищете (или, возможно, несколько результатов). Так же, как при поиске в Google, иногда требуется просмотреть несколько страниц результатов поиска, чтобы найти элемент, который лучше всего соответствует вашим требованиям. Для решения этой задачи API поиска {% data variables.product.product_name %} предоставляет до 1000 результатов для каждого поиска.
Поиск можно сузить с помощью запросов. Дополнительные сведения о синтаксисе поисковых запросов см. в разделе Создание поискового запроса.
Ранжирование результатов поиска
Если в качестве параметра запроса не указан другой параметр сортировки, результаты сортируются по лучшему совпадению в порядке убывания. Для повышения вероятности появления наиболее релевантного элемента в верхней части списка результатов используется множество факторов.
Ограничение скорости
{% data reusables.enterprise.rate_limit %}
API поиска имеет настраиваемое ограничение скорости. Для запросов с использованием обычной проверки подлинности, OAuth или идентификатора клиента и секрета можно выполнять не более 30 запросов в минуту. Для запросов без проверки подлинности ограничение скорости позволяет выполнять не более 10 запросов в минуту.
Дополнительные сведения об определении текущего состояния ограничения скорости см. в документации по ограничению скорости.
Создание поискового запроса
Каждая конечная точка в API поиска использует параметры запроса для выполнения поиска в {% data variables.product.product_name %}. Пример, включающий параметры конечной точки и запроса, см. в отдельной конечной точке API поиска.
Запрос может содержать любое сочетание квалификаторов поиска, поддерживаемых в {% data variables.product.product_name %}. Формат поискового запроса:
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. Сведения об использовании операторов для сопоставления определенных количеств и дат или для исключения результатов см. в разделе Общие сведения о синтаксисе поиска.
Ограничения на длину запроса
API поиска не поддерживает запросы, которые:
- длиннее 256 символов (не включая операторы и квалификаторы);
- имеют более пяти операторов
AND,ORиNOT.
Эти поисковые запросы возвращают сообщение об ошибке "Сбой проверки".
Время ожидания и неполные результаты
Чтобы обеспечить быструю работу API поиска для всех пользователей, мы ограничиваем время выполнения каждого отдельного запроса. Для запросов, превышающих ограничение времени, API возвращает совпадения, которые уже были найдены до истечения времени ожидания, и в ответе свойство incomplete_results имеет значение true.
Превышение времени ожидания не обязательно означает, что результаты поиска будут неполными. Возможно, были бы найдены другие результаты, а возможно и нет.
Доступ к ошибкам и недостающим результатам поиска
Вам нужно успешно пройти проверку подлинности и получить доступ к репозиториям в поисковых запросах. В противном случае появится ошибка 422 Unprocessable Entry с сообщением "Сбой проверки". Например, поиск завершится ошибкой, если запрос содержит квалификаторы repo:, user: или org:, запрашивающие ресурсы, к которым у вас нет доступа после входа на {% data variables.product.prodname_dotcom %}.
Когда поисковый запрос запрашивает несколько ресурсов, ответ будет содержать только те ресурсы, к которым у вас есть доступ, и не предоставит сообщение об ошибке со списком ресурсов, которые не были возвращены.
Например, если поисковый запрос ищет в репозиториях octocat/test и codertocat/test, а у вас есть доступ только к octocat/test, в ответе будут результаты для octocat/test, но не для codertocat/test. Это поведение имитирует работу поиска на {% data variables.product.prodname_dotcom %}.
Метаданные сопоставления текста
На GitHub можно использовать контекст, предоставляемый фрагментами кода и выделениями в результатах поиска. API поиска предлагает дополнительные метаданные, позволяющие выделять соответствующие поисковые термины при отображении результатов поиска.
Запросы могут принимать эти фрагменты текста в ответе, и каждый фрагмент сопровождается числовыми смещениями, определяющими точное расположение каждого соответствующего поискового термина.
Чтобы получить эти метаданные в результатах поиска, укажите тип данных 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' \
'{% data variables.product.api_url_pre %}/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
]
}
]
}
]
}