Search

项目
12/19/2023

可使用 V3 API 在包源上搜索可用的包。用于搜索的资源是在服务索引中找到的 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

以下 API 的基 URL 是与其中一个上述资源 @type 值关联的 @id 属性的值。在下面的文档中，将使用占位符基 URL {@id}。由于基 URL 可能会根据包源中的实现或基础结构更改而更改，因此客户端软件必须从服务索引动态提取它。

HTTP 方法

注册资源中找到的所有 URL 都支持 HTTP 方法 GET 和 HEAD。

搜索包

搜索 API 允许客户端查询与指定搜索查询匹配的包的页面。搜索查询的解释（例如搜索词的标记化）由服务器实现确定，但一般希望将搜索查询用于匹配包 ID、标题、说明和标记。还可考虑其他包元数据字段。

未列出的包不应出现在搜索结果中。

GET {@id}?q={QUERY}&skip={SKIP}&take={TAKE}&prerelease={PRERELEASE}&semVerLevel={SEMVERLEVEL}&packageType={PACKAGETYPE}

请求参数

名称	在	类型	必须	备注
q	URL	string	否	用于筛选包的搜索词
skip	URL	integer	否	要跳过的结果数，用于分页
take	URL	integer	否	要返回的结果数，用于分页
预发行版	URL	boolean	否	`true` 或 `false` 决定是否包含预发行包
semVerLevel	URL	string	否	SemVer 1.0.0 版本字符串
packageType	URL	string	否	用于筛选包的包类型（已在 `SearchQueryService/3.5.0` 中添加）

搜索查询 q 是按服务器实现所定义的方式来分析的。 nuget.org 支持对各种字段进行基本筛选。如果未提供 q，则应在跳过和采用所施加的边界内返回所有包。这将在 NuGet Visual Studio 体验中启用“浏览”选项卡。

skip 参数默认为 0。

take 参数应为大于零的整数。服务器实现可以规定一个最大值。

注意

nuget.org 将 skip 参数限制为 3,000，并将 take 参数限制为 1,000。

如果没有提供 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 参数，就像没有传递该参数一样。

响应

响应是包含最多 take 个搜索结果的 JSON 文档。搜索结果会按包 ID 分组。

根 JSON 对象具有以下属性：

名称	类型	必须	备注
totalHits	integer	是	匹配项的总数，不考虑 `skip` 和 `take`
data	对象数组	是	与请求匹配的搜索结果

搜索结果

data 数组中的每个项目均为一个 JSON 对象，而该对象由共享同一包 ID 的一组包版本组成。对象具有以下属性：

名称	类型	必须	备注
id	string	是	匹配包的 ID
版本	string	是	包的完整 SemVer 2.0.0 版本字符串（可能包含生成元数据）
description	string	否
versions	对象数组	是	与 `prerelease` 参数匹配的包的所有版本
作者	字符串或字符串数组	否
iconUrl	string	否
licenseUrl	string	否
owners	字符串或字符串数组	否	字符串表示单个所有者的用户名
projectUrl	string	否
注册	string	否	关联注册索引的绝对 URL
summary	string	否
标记	字符串或字符串数组	否
title	string	否
totalDownloads	integer	否	此值可通过 `versions` 数组中的下载总数进行推断
已验证	boolean	否	一个 JSON 布尔值，它指示是否已验证包
packageTypes	对象数组	是	包作者定义的包类型（在 `SearchQueryService/3.5.0` 中添加）

在 nuget.org 中，已验证的包具有与保留 ID 前缀匹配的包 ID，并属于其中某一保留前缀的所有者。有关详细信息，请参阅有关 ID 前缀预留的文档。

搜索结果对象中包含的元数据取自最新包版本。 versions 数组中的每个项目均为具有以下属性的 JSON 对象：

名称	类型	必须	注释
@id	string	是	关联注册叶的绝对 URL
版本	string	是	包的完整 SemVer 2.0.0 版本字符串（可能包含生成元数据）
下载	integer	是	此特定包版本的下载次数

packageTypes 数组始终包含至少一个（1 个）项目。给定包 ID 的包类型被视为由包的最新版本针对其他搜索参数而定义的包类型。 packageTypes 数组中的每个项目均为具有以下属性的 JSON 对象：

名称	类型	必须	备注
name	字符串	是	包类型的名称。

示例请求

GET https://search-sample.nuget.org/query?q=NuGet.Versioning&prerelease=false&semVerLevel=2.0.0

请务必按基 URL 部分所提及的方式从服务索引提取基 URL（在此示例中为 https://search-sample.nuget.org/query）。

示例响应

{
  "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"
        }
      ]
    }
  ]
}

通过