包元数据

项目
12/19/2023

可使用 NuGet V3 API 提取有关包源上所提供包的元数据。可使用在服务索引中找到的 RegistrationsBaseUrl 资源来提取此元数据。

在 RegistrationsBaseUrl 下找到的文档集合通常被称为“注册”或“注册 Blob”。单个 RegistrationsBaseUrl 下的文档集被称为“注册配置单元”。注册配置单元包含有关包源上所提供每个包的元数据。

注意

包元数据资源不含包的所有元数据。使用搜索资源查找包的所有者、下载次数或前缀预留状态。

版本控制

使用了以下 @type 值：

值@type	说明
RegistrationsBaseUrl	初始版本
RegistrationsBaseUrl/3.0.0-beta	`RegistrationsBaseUrl` 的别名
RegistrationsBaseUrl/3.0.0-rc	`RegistrationsBaseUrl` 的别名
RegistrationsBaseUrl/3.4.0	Gzip 压缩的响应
RegistrationsBaseUrl/3.6.0	包括 SemVer 2.0.0 包

这表示可用于各种客户端版本的三个不同注册配置单元。

RegistrationsBaseUrl

这些注册未经压缩（这意味着它们使用隐式 Content-Encoding: identity）。 SemVer 2.0.0 包会从此配置单元中排除。

RegistrationsBaseUrl/3.4.0

这些注册会使用 Content-Encoding: gzip 进行压缩。 SemVer 2.0.0 包会从此配置单元中排除。

RegistrationsBaseUrl/3.6.0

这些注册会使用 Content-Encoding: gzip 进行压缩。此配置单元包含 SemVer 2.0.0 包。有关 SemVer 2.0.0 的详细信息，请参阅针对 nuget.org 的 SemVer 2.0.0 支持。

基 URL

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

HTTP 方法

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

注册索引

注册资源组会按包 ID 打包元数据。一次无法获取多个包 ID 的相关数据。此资源无法发现包 ID。相反，会假定客户端已知道所需包 ID。每个包版本的可用元数据因服务器实现而异。包注册 Blob 具有以下分层结构：

索引：包元数据的入口点，它由源上具有相同包 ID 的所有包共享。
页面：包版本的分组。页面中的包版本数由服务器实现定义。
叶：特定于单个包版本的文档。

注册索引的 URL 可预测，且可由客户端根据服务索引中的包 ID 和注册资源的 @id 的值来确定。通过检查注册索引可发现注册页和叶的 URL。

注册页和叶

尽管服务器实现未严格要求将注册叶存储在单独的注册页文档中，但建议节省客户端内存。建议服务器实现根据包版本数或包叶的累积大小来定义一些启发，从而在这两种方法之间进行选择，而不是将所有注册保留在索引中或立即将叶存储在页文档中。

将所有包版本（叶）存储在注册索引中可保存提取包元数据所需的 HTTP 请求数，但这意味着须下载更大的文档，且必须分配更多客户端内存。另一方面，如果服务器实现立即将注册存储在单独的页文档中，则客户端须执行更多 HTTP 请求以获取所需信息。

nuget.org 使用的启发如下：如果有 128 个或更多版本的包，则将叶分解为 64 个页面。如果版本数少于 128 个，则将所有版本内联到注册索引中。请注意，这意味着包含 65 到 127 版本的包会在索引中有两个页面，但这两个页面都将进行内联。

GET {@id}/{LOWER_ID}/index.json

请求参数

名称	在	类型	必须	说明
LOWER_ID	URL	string	是	小写的包 ID

LOWER_ID 值是使用 .NET 的 System.String.ToLowerInvariant() 方法所实现规则的所需包 ID（小写）。

响应

响应是一个 JSON 文档，其中包含具有以下属性的根对象：

名称	类型	必须	说明
count	integer	是	索引中的注册页数
items	对象数组	是	注册页数组

索引对象的items 数组中的每个项目均为表示注册页的 JSON 对象。

注册页对象

在注册索引中找到的注册页对象具有以下属性：

名称	类型	必须	注释
@id	string	是	注册页的 URL
count	integer	是	页中的注册叶数
items	对象数组	否	注册叶及其关联元数据的数组
lower	string	是	页中最低 SemVer 2.0.0 版本（含）
parent	string	否	注册索引的 URL
upper	string	是	页中最高 SemVer 2.0.0 版本（含）

需要特定页面版本的元数据时，页面对象的 lower 和 upper 边界非常有用。这些边界可用于提取所需的唯一注册页。版本字符串遵循 NuGet 的版本规则。版本字符串已规范化，且不含生成元数据。与 NuGet 生态系统中的所有版本一样，SemVer 2.0.0 的版本优先规则被用于实现版本字符串比较。

仅当注册页对象具有 items 属性时，才会显示 parent 属性。

如果注册页对象中不存在 items 属性，则须使用在 @id 中指定的 URL 来获取有关各包版本的元数据。 items 数组有时会从页面对象中排除，以作为优化。如果单个包 ID 的版本数非常大，则注册索引文档对于只关心特定版本或少量版本的客户端会十分巨大且造成浪费。

请注意，如果 items 属性存在，则需使用 @id 属性，因为所有页面数据均已内联到 items 属性中。

页面对象的 items 数组中的每个项目均为表示注册叶及其关联元数据的 JSON 对象。

页中的注册叶对象

在注册页中找到的注册叶对象具有以下属性：

名称	类型	必须	注释
@id	string	是	注册叶的 URL
catalogEntry	object	是	包含包元数据的目录项
packageContent	string	是	包内容 (.nupkg) 的 URL

每个注册叶对象均表示与单个包版本关联的数据。

目录条目

注册叶对象中的 catalogEntry 属性具有以下属性：

名称	类型	必须	注释
@id	string	是	用于生成此对象的文档的 URL
作者	字符串或字符串数组	否
dependencyGroups	对象数组	否	按目标框架分组的包的依赖项
弃用	object	否	与包关联的弃用
description	string	否
iconUrl	string	否
id	string	是	包的 ID
language	string	否
licenseUrl	string	否
licenseExpression	string	否
列出	boolean	否	如果不存在，则应被视为已列出
minClientVersion	string	否
packageContent	string	否	父对象中同一属性的副本（仅出于历史原因而包含）
projectUrl	string	否
published	string	否	包含包发布时间的 ISO 8601 时间戳的字符串
readmeUrl	string	否	包自述文件已呈现（HTML 网页）视图的 URL
requireLicenseAcceptance	boolean	否
summary	string	否
标记	字符串或字符串数组	否
title	string	否
版本	string	是	规范化后的完整版本字符串
vulnerabilities	对象数组	否	包的安全漏洞

包 version 属性为规范化后的完整版本字符串。这意味着，可在此处包含 SemVer 2.0.0 生成数据。

dependencyGroups 属性是表示包依赖项（按目标框架分组）的对象的数组。如果包没有依赖项，dependencyGroups 属性则会缺失、为空数组，或是所有组的 dependencies 属性均为空或缺失。

licenseExpression 属性的值符合 NuGet 许可证表达式语法。

注意

在 nuget.org 中，当包未列出时，published 值将设为 1900 年。

包依赖项组

每个依赖项组对象均具有以下属性：

名称	类型	必须	说明
targetFramework	string	否	这些依赖项适用的目标框架
dependencies	对象数组	否

targetFramework 字符串使用 NuGet 的 .NET 库 NuGet.Frameworks 所实现的格式。如果未指定 targetFramework，依赖项组将应用于所有目标框架。

dependencies 属性为对象数组，且每个对象均表示当前包的某一包依赖项。

包依赖项

每个包依赖项均具有以下属性：

名称	类型	必须	说明
id	string	是	包依赖项的 ID
range	object	否	依赖项的允许版本范围
注册	string	否	此依赖项的注册索引的 URL

如果 range 属性被排除或为空字符串，客户端应默认采用版本范围 (, )。换言之，允许使用任意版本的依赖项。不允许为 range 属性使用 * 值。

包弃用

每个包弃用均具有以下属性：

名称	类型	必须	说明
原因	字符串的数组	是	弃用包的原因
message	string	否	有关此弃用的其他详细信息
alternatePackage	object	否	应改用的备用包

reasons 属性必须至少包含一个字符串，且应只包含下表中列出的字符串：

Reason	说明
旧的	包不再进行维护
CriticalBugs	包存在 bug，从而使其不适合使用
其他	由于此列表中未列出的某一原因而弃用包

如果 reasons 属性包含的字符串不是来自已知集，则应忽略它们。字符串不区分大小写，因此 legacy 应被视为与 Legacy 相同。数组没有排序限制，因此字符串可按任意顺序排列。此外，如果该属性仅包含不是来自已知集的字符串，则应将其视为仅包含“其他”字符串。

备用包

备用包具有以下属性：

名称	类型	必须	说明
id	string	是	备用包的 ID
range	object	否	允许的版本范围，或 `*`（如果允许使用任意版本）

漏洞

一个 vulnerability 对象数组。每个漏洞均具有以下属性：

名称	类型	必须	说明
advisoryUrl	string	是	针对包的安全公告位置
severity	string	是	公告的严重性：“0”= 低、“1”= 中等、“2”= 高、“3”= 严重

示例请求

GET https://api.nuget.org/v3/registration-sample/nuget.server.core/index.json

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

示例响应

{
  "count": 1,
  "items": [
    {
      "@id": "https://api.nuget.org/v3/registration-sample/nuget.server.core/index.json#page/3.0.0-beta/3.0.0-beta",
      "count": 1,
      "items": [
        {
          "@id": "https://api.nuget.org/v3/registration-sample/nuget.server.core/3.0.0-beta.json",
          "catalogEntry": {
            "@id": "https://api.nuget.org/v3/catalog0/data/2017.10.05.18.41.33/nuget.server.core.3.0.0-beta.json",
            "authors": ".NET Foundation",
            "dependencyGroups": [
              {
                "@id": "https://api.nuget.org/v3/catalog0/data/2017.10.05.18.41.33/nuget.server.core.3.0.0-beta.json#dependencygroup",
                "dependencies": [
                  {
                    "@id": "https://api.nuget.org/v3/catalog0/data/2017.10.05.18.41.33/nuget.server.core.3.0.0-beta.json#dependencygroup/nuget.core",
                    "id": "NuGet.Core",
                    "range": "[2.14.0, )",
                    "registration": "https://api.nuget.org/v3/registration-sample/nuget.core/index.json"
                  }
                ]
              }
            ],
            "description": "Core library for creating a Web Application used to host a simple NuGet feed",
            "iconUrl": "",
            "id": "NuGet.Server.Core",
            "language": "",
            "licenseUrl": "https://raw.githubusercontent.com/NuGet/NuGet.Server/dev/LICENSE.txt",
            "listed": true,
            "minClientVersion": "2.6",
            "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.server.core/3.0.0-beta/nuget.server.core.3.0.0-beta.nupkg",
            "projectUrl": "https://github.com/NuGet/NuGet.Server",
            "published": "2017-10-05T18:40:32.43+00:00",
            "requireLicenseAcceptance": false,
            "summary": "",
            "tags": [ "" ],
            "title": "",
            "version": "3.0.0-beta",
            "vulnerabilities": [
              {
                "advisoryUrl": "https://github.com/advisories/ABCD-1234-5678-9012",
                "severity": "2"
              }
            ]
          },
          "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.server.core/3.0.0-beta/nuget.server.core.3.0.0-beta.nupkg",
          "registration": "https://api.nuget.org/v3/registration-sample/nuget.server.core/index.json"
        }
      ],
      "lower": "3.0.0-beta",
      "upper": "3.0.0-beta"
    }
  ]
}

在此特定情况下，注册索引包含内联的注册页，因此无需额外请求来获取有关单个包版本的元数据。

注册页

注册页包含注册叶。用于提取注册页的 URL 由上文提及的注册页面对象中的 @id 属性来确定。 URL 不应可预测，而应始终通过索引文档来发现。

警告

在 nuget.org 中，注册页文档的 URL 恰巧包含页面的下限和上限。但是，客户端不应做出此假设，因为只要索引文档具有有效链接，服务器实现便可随意更改 URL 的形状。

如果未在注册索引中提供 items 数组，@id 值的 HTTP GET 请求则会返回一个 JSON 文档，其中包含一个对象作为其根。对象具有以下属性：

名称	类型	必须	注释
@id	string	是	注册页的 URL
count	integer	是	页中的注册叶数
items	对象数组	是	注册叶及其关联元数据的数组
lower	string	是	页中最低 SemVer 2.0.0 版本（含）
parent	string	是	注册索引的 URL
upper	string	是	页中最高 SemVer 2.0.0 版本（含）

注册叶对象的形状与上文注册索引中的形状相同。

示例请求

GET https://api.nuget.org/v3/registration-sample/ravendb.client/page/1.0.531/1.0.729-unstable.json

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

示例响应

{
  "count": 2,
  "lower": "1.0.531",
  "parent": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/index.json",
  "upper": "1.0.729-unstable",
  "items": [
    {
      "@id": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/1.0.531.json",
      "@type": "Package",
      "commitId": "e0b9ca79-75b5-414f-9e3e-de9534b5cfd1",
      "commitTimeStamp": "2017-10-26T14:12:19.3439088Z",
      "catalogEntry": {
        "@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.38.37/nuget.protocol.v3.example.1.0.531.json",
        "@type": "PackageDetails",
        "authors": "NuGet.org Team",
        "iconUrl": "https://www.nuget.org/Content/gallery/img/default-package-icon.svg",
        "id": "NuGet.Protocol.V3.Example",
        "licenseUrl": "http://www.opensource.org/licenses/ms-pl",
        "listed": false,
        "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.protocol.v3.example/1.0.531/nuget.protocol.v3.example.1.0.531.nupkg",
        "projectUrl": "https://github.com/NuGet/NuGetGallery",
        "published": "1900-01-01T00:00:00+00:00",
        "requireLicenseAcceptance": true,
        "title": "NuGet V3 Protocol Example",
        "version": "1.0.531"
      },
      "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.protocol.v3.example/1.0.531/nuget.protocol.v3.example.1.0.531.nupkg",
      "registration": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/index.json"
    },
    {
      "@id": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/1.0.729-unstable.json",
      "@type": "Package",
      "commitId": "e0b9ca79-75b5-414f-9e3e-de9534b5cfd1",
      "commitTimeStamp": "2017-10-26T14:12:19.3439088Z",
      "catalogEntry": {
        "@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.18.22.05/nuget.protocol.v3.example.1.0.729-unstable.json",
        "@type": "PackageDetails",
        "authors": "NuGet.org Team",
        "deprecation": {
          "reasons": [
            "CriticalBugs"
          ],
          "message": "This package is unstable and broken!",
          "alternatePackage": {
            "id": "Newtonsoft.JSON",
            "range": "12.0.2"
          }
        },
        "iconUrl": "https://www.nuget.org/Content/gallery/img/default-package-icon.svg",
        "id": "NuGet.Protocol.V3.Example",
        "licenseUrl": "http://www.opensource.org/licenses/ms-pl",
        "listed": false,
        "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.protocol.v3.example/1.0.729-unstable/nuget.protocol.v3.example.1.0.729-unstable.nupkg",
        "projectUrl": "https://github.com/NuGet/NuGetGallery",
        "published": "1900-01-01T00:00:00+00:00",
        "requireLicenseAcceptance": true,
        "summary": "This package is an example for the V3 protocol.",
        "title": "NuGet V3 Protocol Example",
        "version": "1.0.729-Unstable"
      },
      "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.protocol.v3.example/1.0.729-unstable/nuget.protocol.v3.example.1.0.729-unstable.nupkg",
      "registration": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/index.json"
    }
  ]
}

注册叶

注册叶包含有关特定包 ID 和版本的信息。本文档中可能不提供有关特定版本的元数据。应从注册索引或注册页（使用注册索引来发现）提取包元数据。

用于获取注册叶的 URL 是通过注册索引或注册页中注册叶对象的 @id 属性获取的。与页面文档一样。 URL 应不可预测，且应始终通过注册页对象来发现。

警告

在 nuget.org 中，注册叶文档的 URL 恰巧包含包版本。但是，客户端不应做出此假设，因为只要父文档具有有效链接，服务器实现便可随意更改 URL 的形状。

注册叶是一个 JSON 文档，其中包含具有以下属性的根对象：

名称	类型	必须	注释
@id	string	是	注册叶的 URL
catalogEntry	string	否	生成这些叶的目录条目的 URL
列出	boolean	否	如果不存在，则应被视为已列出
packageContent	string	否	包内容 (.nupkg) 的 URL
published	string	否	包含包发布时间的 ISO 8601 时间戳的字符串
注册	string	否	注册索引的 URL

注意

在 nuget.org 中，当包未列出时，published 值将设为 1900 年。

示例请求

GET https://api.nuget.org/v3/registration-sample/nuget.versioning/4.3.0.json

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

示例响应

{
  "@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/4.3.0.json",
  "catalogEntry": "https://api.nuget.org/v3/catalog0/data/2017.08.11.18.24.22/nuget.versioning.4.3.0.json",
  "listed": true,
  "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.versioning/4.3.0/nuget.versioning.4.3.0.nupkg",
  "published": "2017-08-11T18:24:14.36+00:00",
  "registration": "https://api.nuget.org/v3/registration-sample/nuget.versioning/index.json"
}

通过

包元数据

版本控制

RegistrationsBaseUrl

RegistrationsBaseUrl/3.4.0

RegistrationsBaseUrl/3.6.0

基 URL

HTTP 方法

注册索引

注册页和叶

请求参数

响应

注册页对象

页中的注册叶对象

目录条目

包依赖项组

包依赖项

包弃用

备用包

漏洞

示例请求

示例响应

注册页

示例请求

示例响应

注册叶

示例请求

示例响应

反馈

其他资源