NuGet 服务器 API

  • 项目

NuGet 服务器 API 是一组 HTTP 终结点，它们可用于下载包、提取元数据、发布新包，以及执行官方 NuGet 客户端中提供的大多数其他操作。

Visual Studio、nuget.exe 和 .NET CLI 中的 NuGet 客户端使用此 API 来执行 NuGet 操作，例如 dotnet restore、在 Visual Studio UI 中进行搜索以及 nuget.exe push。

请注意，在某些情况下，nuget.org 具有其他包源未强制实施的附加要求。 nuget.org 协议记录了这些差异。

有关可用 nuget.exe 版本的简易枚举和下载，请参阅 tools.json 终结点。

如果要实现 NuGet 包存储库，另请参阅针对其他要求和建议的实现指南。

服务索引

API 的入口点是存在于已知位置的 JSON 文档。 此文档被称为服务索引。 nuget.org 服务索引的位置为 https://api.nuget.org/v3/index.json。

此 JSON 文档包含资源列表，而这些资源可提供不同功能并满足不同用例。

支持 API 的客户端应接受其中一个或多个服务索引 URL 以作为连接到相应包源的方法。

有关服务索引的详细信息，请参阅其 API 参考。

版本控制

API 为 NuGet 的 HTTP 协议版本 3。 此协议有时被称为“V3 API”。 这些参考文档将此版本的协议称为“API”。

服务索引架构版本由服务索引中的 version 属性指示。 API 要求版本字符串的主版本号为 3。 由于对服务索引架构进行了非中断性变更，版本字符串的次要版本将增加。

旧客户端（如 nuget.exe 2.x）不支持 V3 API，而仅支持此处未记录的旧 V2 API。

NuGet V3 API 之所以如何命名是因为它是 V2 API 的后续版本，而后者是由官方 NuGet 客户端的 2.x 版本所实现的基于 OData 的协议。 V3 API 首先受官方 NuGet 客户端的 3.0 版本的支持，且仍是 NuGet 客户端 4.0 及更高版本所支持的最新主要协议版本。

自此 API 首次发布以来，已对其进行非重大协议更改。

资源和架构

服务索引描述了各种资源。 当前支持的一组资源如下：

资源名称 必需 说明
Catalog 否 所有包事件的完整记录。
PackageBaseAddress 是 获取包内容 (.nupkg)。
PackageDetailsUriTemplate 否 构造 URL 以访问包详细信息网页。
PackagePublish 是 推送和删除（或取消列出）包。
RegistrationsBaseUrl 是 获取包元数据。
ReportAbuseUriTemplate 否 构造 URL 以访问报告滥用网页。
RepositorySignatures 否 获取用于存储库签名的证书。
SearchAutocompleteService 否 通过子字符串发现包 ID 和版本。
SearchQueryService 是 按关键字筛选和搜索包。
SymbolPackagePublish 否 推送符号包。
VulnerabilityInfo 否 具有已知漏洞的包。

通常，API 资源返回的所有非二进制数据均使用 JSON 进行序列化。 服务索引中每个资源返回的响应架构均针对该资源单独进行定义。 有关每个资源的详细信息，请参阅上方列出的主题。

将来，随着协议的发展，可能会将新属性添加到 JSON 响应中。 要使客户端符合未来趋势，则实现不应假定响应架构为最终架构，且不能包含额外数据。 实现无法理解的所有属性均应忽略。

注意

当源未实现 SearchAutocompleteService 时，所有自动完成行为均应正常禁用。 未实现 ReportAbuseUriTemplate 时，官方 NuGet 客户端会回退到 nuget.org 的报告滥用 URL（由 NuGet/Home#4924 跟踪）。 其他客户端可能会选择不向用户显示报告滥用 URL。

nuget.org 上的未记录资源

nuget.org 上的 V3 服务索引具有上方未记录的某些资源。 未记录资源的原因有几个。

首先，我们不会记录用作 nuget.org 实现详细信息的资源。而 SearchGalleryQueryService 属于此类别。 NuGetGallery 使用此资源将某些 V2 (OData) 查询委托给我们的搜索索引，而不是使用数据库。 由于可伸缩性原因，我们引入了此资源，且未计划供外部使用。

其次，我们不会记录从未在官方客户端的 RTM 版本中提供的资源。 PackageDisplayMetadataUriTemplate 和 PackageVersionDisplayMetadataUriTemplate 均属于此类别。

第三，我们不会记录与 V2 协议紧密耦合的资源，而此类资源自身便故意未进行记录。 LegacyGallery 资源属于此类别。 此资源允许 V3 服务索引指向相应的 V2 源 URL。 此资源支持 nuget.exe list。

如果此处未记录某一资源，则强烈建议不依赖于它们。 我们可能会删除或更改这些未记录资源的行为，而这可能会以意外方式中断实现。

时间戳

API 返回的所有时间戳均为 UTC，或是使用 ISO 8601 表示形式来指定。

HTTP 方法

谓词 使用
GET 执行只读操作，且通常为检索数据。
HEAD 获取相应 GET 请求的响应标头。
PUT 创建不存在的资源；或者，如果资源确实存在，则更新它。 某些资源可能不支持更新。
DELETE 删除或取消列出资源。

HTTP 状态代码

代码 说明
200 成功，且有响应正文。
201 成功，且会创建资源。
202 成功，请求已接受，但某些工作可能仍不完整且会异步完成。
204 成功，但没有响应正文。
301 永久重定向。
302 临时重定向。
400 URL 或请求正文中的参数无效。
401 提供的凭据无效。
403 由于提供的凭据，不允许执行该操作。
404 请求的资源不存在。
409 请求与现有资源冲突。
500 服务出现意外错误。
503 该服务暂时不可用。

对 API 终结点发出的所有 GET 请求均可能会返回 HTTP 重定向（301 或 302）。 客户端应通过观察 Location 标头并发出后续 GET 来正常处理此类重定向。 有关特定终结点的文档不会显式标注可能会使用重定向的位置。

对于 500 级状态代码，客户端可实现合理的重试机制。 遇到任意 500 级状态代码或 TCP/DNS 错误时，官方 NuGet 客户端会重试三次。

HTTP 请求标头

名称 描述
X-NuGet-ApiKey 推送和删除所需的资源，请参阅PackagePublish资源
X-NuGet-Client-Version 已弃用并替换为 X-NuGet-Protocol-Version
X-NuGet-Protocol-Version 某些情况下，仅在 nuget.org 上必需，请参阅 nuget.org 协议
X-NuGet-Session-Id 可选。 NuGet 客户端 v4.7 及以上版本会识别属于同一 NuGet 客户端会话的 HTTP 请求。

对于与 PackageReference 中单个还原相关的所有操作，X-NuGet-Session-Id 均有单个值。 对于其他场景（例如自动完成和 packages.config 还原），由于代码的分解方式，可能会有多个不同会话 ID。

身份验证

身份验证将留给包源实现来定义。 对于 nuget.org，只有 PackagePublish 资源需通过特殊 API 密钥标头进行身份验证。 有关详细信息，请参阅 PackagePublish 资源。