Поиск (Search)
Можно искать пакеты, доступные в источнике пакетов, с помощью API версии 3. Ресурс, используемый для поиска, является ресурсомSearchQueryService, найденным в индексе службы.
Управление версиями
Допустимы следующие значения @type:
| Значение @type | Примечания. |
|---|---|
| SearchQueryService | Начальный выпуск |
| SearchQueryService/3.0.0-beta | Псевдоним SearchQueryService |
| SearchQueryService/3.0.0-rc | Псевдоним SearchQueryService |
| SearchQueryService/3.5.0 | Включает поддержку параметра запроса packageType |
SearchQueryService/3.5.0
Эта версия содержит поддержку packageType параметра запроса и packageTypes свойства ответа, позволяя фильтровать по определенным типам пакетов. Для версии реализована полная обратная совместимость с запросами к SearchQueryService.
Базовый URL-адрес
Базовый URL-адрес для следующего API — это значение @id свойства, связанного с одним из указанных выше упоминание значений ресурсов@type. В следующем документе будет использоваться базовый URL-адрес заполнителя {@id}. Базовый URL-адрес может изменяться на основе изменений в реализации или инфраструктуре в источнике пакета, поэтому он должен быть динамически получен из индекса службы клиентским программным обеспечением.
Методы HTTP
Все URL-адреса, содержащиеся в ресурсе регистрации, поддерживают методы HTTP GET и HEAD.
Поиск пакетов
API поиска позволяет клиенту запрашивать страницу пакетов, соответствующих указанному поисковому запросу. Интерпретация поискового запроса (например, маркеризация терминов поиска) определяется реализацией сервера, но общее ожидание заключается в том, что поисковый запрос используется для сопоставления идентификаторов пакетов, заголовков, описаний и тегов. Можно также рассмотреть другие поля метаданных пакета.
Неподписанный пакет никогда не должен отображаться в результатах поиска.
GET {@id}?q={QUERY}&skip={SKIP}&take={TAKE}&prerelease={PRERELEASE}&semVerLevel={SEMVERLEVEL}&packageType={PACKAGETYPE}
Параметры запроса
| Имя. | In | Тип | Обязательное поле | Примечания. |
|---|---|---|---|---|
| к | URL | строка | no | Термины поиска, используемые для фильтрации пакетов |
| skip | URL | integer | no | Число пропускаемых результатов для разбивки на страницы |
| take | URL | integer | no | Число возвращаемых результатов для разбивки на страницы |
| Предварительный выпуск | URL | boolean | no | Значение true или false, определяющее, включать ли пакеты предварительного выпуска |
| semVerLevel | URL | строка | no | Строка версии SemVer 1.0.0 |
| packageType | URL | строка | no | Тип пакета, используемый для фильтрации пакетов (добавлен в SearchQueryService/3.5.0) |
Поисковый запрос q анализируется таким образом, который определяется реализацией сервера. nuget.org поддерживает базовую фильтрацию по различным полям. Если не q указано, все пакеты должны быть возвращены в пределах границ, введенных путем пропуска и принятия. Это позволяет перейти на вкладку "Обзор" в интерфейсе NuGet Visual Studio.
Значение параметра skip по умолчанию — 0.
Параметр take должен быть целым числом больше нуля. Реализация сервера может требовать установки максимального значения.
Примечание.
nuget.org ограничивает skip параметр 3000, а take параметр — 1000.
Если значение prerelease не указано, пакеты предварительного выпуска исключаются.
Параметр запроса semVerLevel применяется для использования пакетов SemVer 2.0.0.
Если этот параметр запроса исключен, будут возвращены только пакеты с совместимыми версиями SemVer 1.0.0 (с стандартными предостережениями по версиям NuGet, такими как строки версий с 4 целыми частями).
Если указано значение semVerLevel=2.0.0, будут возвращены совместимые пакеты SemVer 1.0.0 и SemVer 2.0.0. Дополнительные сведения см. в статье Поддержка SemVer 2.0.0 для nuget.org.
Этот packageType параметр используется для дальнейшего фильтрации результатов поиска только для пакетов, имеющих по крайней мере один тип пакета, соответствующий имени типа пакета.
Если предоставленный тип пакета недопустим, как определено в документе "Тип пакета", будет возвращен пустой результат.
Если предоставлен пустой тип пакета, фильтр применяться не будет. Другими словами, передача значения в параметр packageType не будет вести себя так, как если бы параметр не был передан.
Response
Ответ — это документ JSON, take содержащий результаты поиска. Результаты поиска группируются по идентификатору пакета.
Корневой объект JSON имеет следующие свойства:
| Имя. | Type | Обязательное поле | Примечания. |
|---|---|---|---|
| totalHits | integer | yes | Общее число совпадений, не учитывая skip и take |
| . | массив объектов | yes | Результаты поиска, соответствующие запросу |
Результат поиска
Каждый элемент в массиве data представляет собой объект JSON, состоящий из группы версий пакетов, которые используют один и тот же идентификатор пакета.
Объект имеет следующие свойства.
| Имя. | Type | Обязательное поле | Примечания. |
|---|---|---|---|
| id | string | yes | Идентификатор сопоставленного пакета |
| версия | строка | yes | Полная строка версии SemVer 2.0.0 пакета (может содержать метаданные сборки) |
| описание | строка | no | |
| версии | массив объектов | yes | Все версии пакета, соответствующие параметру prerelease |
| authors | строка или массив строк | no | |
| iconUrl | строка | no | |
| licenseUrl | строка | no | |
| owners | строка или массив строк | no | |
| projectUrl | строка | no | |
| регистрация | строка | no | Абсолютный URL-адрес связанного индекса регистрации |
| Итоги | строка | no | |
| tags | строка или массив строк | no | |
| title | string | no | |
| totalDownloads | integer | no | Это значение можно вывести с помощью суммы загрузки в массиве versions . |
| Проверить | boolean | no | Логическое значение JSON, указывающее, проверяется ли пакет. |
| packageTypes | массив объектов | yes | Типы пакетов, определенные автором пакета (добавлены в SearchQueryService/3.5.0) |
В nuget.org проверенный пакет имеет идентификатор пакета, соответствующий префиксу зарезервированного идентификатора и принадлежащий одному из владельцев зарезервированного префикса. Дополнительные сведения см. в документации по резервированию префикса идентификаторов.
Метаданные, содержащиеся в объекте результатов поиска, взятые из последней версии пакета. Каждый элемент в массиве versions представляет собой объект JSON со следующими свойствами:
| Имя. | Type | Обязательное поле | Примечания. |
|---|---|---|---|
| @id | строка | yes | Абсолютный URL-адрес связанной конечной точки регистрации |
| версия | строка | yes | Полная строка версии SemVer 2.0.0 пакета (может содержать метаданные сборки) |
| загрузки | integer | yes | Количество скачиваемых файлов для конкретной версии пакета |
Массив packageTypes всегда будет состоять из одного элемента (1). Тип пакета для заданного идентификатора пакета считается типами пакетов, определенными последней версией пакета относительно других параметров поиска. Каждый элемент в массиве packageTypes представляет собой объект JSON со следующими свойствами:
| Имя. | Type | Обязательное поле | Примечания. |
|---|---|---|---|
| name | строка | yes | Имя типа пакета. |
Образец запроса
GET https://search-sample.nuget.org/query?q=NuGet.Versioning&prerelease=false&semVerLevel=2.0.0
Обязательно получите базовый URL-адрес (https://search-sample.nuget.org/queryв этом примере) из индекса службы, как упоминание в разделе базового URL-адреса.
Пример ответа
{
"totalHits": 2,
"data": [
{
"registration": "https://api.nuget.org/v3/registration-sample/nuget.versioning/index.json",
"id": "NuGet.Versioning",
"version": "4.4.0",
"description": "NuGet's implementation of Semantic Versioning.",
"summary": "",
"title": "NuGet.Versioning",
"licenseUrl": "https://raw.githubusercontent.com/NuGet/NuGet.Client/dev/LICENSE.txt",
"tags": [ "semver", "semantic", "versioning" ],
"authors": [ "NuGet" ],
"totalDownloads": 141896,
"verified": true,
"packageTypes": [
{
"name": "Dependency"
}
],
"versions": [
{
"version": "3.3.0",
"downloads": 50343,
"@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/3.3.0.json"
},
{
"version": "3.4.3",
"downloads": 27932,
"@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/3.4.3.json"
},
{
"version": "4.0.0",
"downloads": 63004,
"@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/4.0.0.json"
},
{
"version": "4.4.0",
"downloads": 617,
"@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/4.4.0.json"
}
]
},
{
"@id": "https://api.nuget.org/v3/registration-sample/nerdbank.gitversioning/index.json",
"@type": "Package",
"registration": "https://api.nuget.org/v3/registration-sample/nerdbank.gitversioning/index.json",
"id": "Nerdbank.GitVersioning",
"version": "2.0.41",
"description": "Stamps your assemblies with semver 2.0 compliant git commit specific version information and provides NuGet versioning information as well.",
"summary": "Stamps your assemblies with semver 2.0 compliant git commit specific version information and provides NuGet versioning information as well.",
"title": "Nerdbank.GitVersioning",
"licenseUrl": "https://raw.githubusercontent.com/AArnott/Nerdbank.GitVersioning/ed547462f7/LICENSE.txt",
"projectUrl": "http://github.com/aarnott/Nerdbank.GitVersioning",
"tags": [ "git", "commit", "versioning", "version", "assemblyinfo" ],
"authors": [ "Andrew Arnott" ],
"totalDownloads": 11906,
"verified": false,
"versions": [
{
"version": "1.6.35",
"downloads": 10229,
"@id": "https://api.nuget.org/v3/registration-sample/nerdbank.gitversioning/1.6.35.json"
},
{
"version": "2.0.41",
"downloads": 1677,
"@id": "https://api.nuget.org/v3/registration-sample/nerdbank.gitversioning/2.0.41.json"
}
]
}
]
}
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по