Поиск (Search)

Статья
10/23/2023

Можно искать пакеты, доступные в источнике пакетов, с помощью 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"
        }
      ]
    }
  ]
}

Поделиться через