Search

可使用 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 方法 GETHEAD

搜索包

搜索 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 truefalse 决定是否包含预发行包
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 匹配项的总数,不考虑 skiptake
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"
        }
      ]
    }
  ]
}