NuGet 服务器 API

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

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

请注意,在某些情况下,nuget.org 其他包源不强制执行的其他要求。 这些差异由协议 nuget.org 记录

有关可用版本的简单枚举和nuget.exe,请参阅 tools.json 终结点。

服务索引

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 和 on 支持的最新主要协议版本。

自首次发布 API 以来,已对 API 进行了非中断性协议更改。

资源和架构

服务索引描述各种资源。 当前支持的资源集如下所示:

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

一般情况下,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 版本中提供的资源。 PackageDisplayMetadataUriTemplatePackageVersionDisplayMetadataUriTemplate 属于此类别。

第三,我们不会记录与 V2 协议紧密耦合的资源,该协议本身是有意未记录的。 资源 LegacyGallery 属于此类别。 此资源允许 V3 服务索引指向相应的 V2 源 URL。 此资源支持 nuget.exe list

如果此处未记录资源,我们强烈建议不要依赖它们。 我们可能会删除或更改这些未记录资源的行为,这可能以意外的方式破坏实现。

时间戳

API 返回的所有时间戳都是 UTC,或者使用 ISO 8601 表示形式指定。

HTTP 方法

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

HTTP 状态代码

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

GET API 终结点的任何请求都可能会返回 HTTP 重定向 (301 或 302) 。 客户端应该通过观察 标头并 Location 发出后续 的 来正常处理此类重定向 GET。 有关特定终结点的文档不会明确指出可能使用重定向的地方。

对于 500 级别状态代码,客户端可以实施合理的重试机制。 当NuGet 500 级别状态代码或 TCP/DNS 错误时,客户端会重试三次。

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 请求。

对于 X-NuGet-Session-Id 与 中的单个还原相关的所有操作, 具有单个值 PackageReference。 对于其他方案(如自动完成 packages.config 和还原)可能有几个不同的会话 ID,因为代码是如何因素考虑的。

身份验证

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