nuget.org 协议nuget.org protocols

若要与 nuget.org 进行交互,客户端需要遵守某些协议。To interact with nuget.org, clients need to follow certain protocols. 由于这些协议,让不断演变,客户端必须标识调用特定 nuget.org Api 时,它们使用的协议版本。Because these protocols keep evolving, clients must identify the protocol version they use when calling specific nuget.org APIs. 这样,nuget.org 的旧客户端不间断的方式引入的更改。This allows nuget.org to introduce changes in a non-breaking way for the old clients.

备注

此页上所述的 Api 是特定于 nuget.org 并且没有任何其他 NuGet 服务器上实现来引入这些 Api 的假定条件。The APIs documented on this page are specific to nuget.org and there is no expectation for other NuGet server implementations to introduce these APIs.

有关在 NuGet 生态系统中实施广泛 NuGet API 的信息,请参阅API 概述For information about the NuGet API implemented broadly across the NuGet ecosystem, see the API overview.

本主题列出了作为各种协议和时它们可以直接对存在。This topic lists various protocols as and when they come to existence.

NuGet 协议版本 4.1.0NuGet protocol version 4.1.0

4.1.0 协议指定验证范围密钥与 nuget.org 中,若要验证包对 nuget.org 帐户以外的服务进行交互的用法。The 4.1.0 protocol specifies usage of verify-scope keys to interact with services other than nuget.org, to validate a package against a nuget.org account. 请注意,4.1.0数目是不透明的字符串,但恰好官方 NuGet 客户端支持此协议的第一个版本的版本。Note that the 4.1.0 version number is an opaque string but happens to coincide with the first version of the official NuGet client that supported this protocol.

验证可确保用户创建 API 密钥仅用于 nuget.org 中,并通过使用一次验证作用域键处理该验证或通过第三方服务的验证。Validation ensures that the user-created API keys are used only with nuget.org, and that other verification or validation from a third-party service is handled through a one-time use verify-scope keys. 这些验证范围密钥可以用于验证包属于 nuget.org 上的特定用户 (帐户)。These verify-scope keys can be used to validate that the package belongs to a particular user (account) on nuget.org.

客户端要求Client requirement

要求客户端时它们向发出 API 调用传递以下标头推送到 nuget.org 的包:Clients are required to pass the following header when they make API calls to push packages to nuget.org:

X-NuGet-Protocol-Version: 4.1.0

请注意,X-NuGet-Client-Version标头具有类似语义,但将其保留仅供官方 NuGet 客户端。Note that the X-NuGet-Client-Version header has similar semantics but is reserved to only be used by the official NuGet client. 第三方客户端应使用X-NuGet-Protocol-Version标头和值。Third party clients should use the X-NuGet-Protocol-Version header and value.

推送协议本身中的文档所述PackagePublish资源The push protocol itself is described in the documentation for the PackagePublish resource.

如果客户端与外部服务,需要验证是否属于特定用户 (帐户) 的包进行交互,它应使用以下协议,并使用作用域的验证密钥和不从 nuget.org 的 API 密钥。If a client interacts with external services and needs to validate whether a package belongs to a particular user (account), it should use the following protocol and use the verify-scope keys and not the API keys from nuget.org.

API 请求作用域的验证密钥API to request a verify-scope key

此 API 用于获取 nuget.org 作者可以验证拥有的他/她的包的作用域的验证密钥。This API is used to get a verify-scope key for a nuget.org author to validate a package owned by him/her.

POST api/v2/package/create-verification-key/{ID}/{VERSION}

请求参数Request parameters

nameName In 类型Type 必需Required 说明Notes
IdID URLURL 字符串string yes 为其请求验证作用域键包 identidierThe package identidier for which the verify scope key is requested
VERSIONVERSION URLURL 字符串string no 包版本The package version
X-NuGet-ApiKeyX-NuGet-ApiKey HeaderHeader 字符串string yes 例如,X-NuGet-ApiKey: {USER_API_KEY}For example, X-NuGet-ApiKey: {USER_API_KEY}

响应Response

{
    "Key": "{Verify scope key from nuget.org}",
    "Expires": "{Date}"
}

若要验证验证作用域键的 APIAPI to verify the verify scope key

此 API 用于验证归 nuget.org 作者的包的作用域的验证密钥。This API is used to validate a verify-scope key for package owned by the nuget.org author.

GET api/v2/verifykey/{ID}/{VERSION}

请求参数Request parameters

nameName In 类型Type 必需Required 说明Notes
IdID URLURL 字符串string yes 为其请求验证作用域键包标识符The package identifier for which the verify scope key is requested
VERSIONVERSION URLURL 字符串string no 包版本The package version
X-NuGet-ApiKeyX-NuGet-ApiKey HeaderHeader 字符串string yes 例如,X-NuGet-ApiKey: {VERIFY_SCOPE_KEY}For example, X-NuGet-ApiKey: {VERIFY_SCOPE_KEY}

备注

此验证作用域 API 密钥将在某一天的时间后过期,或在首次使用准。This verify scope API key expires in a day's time or on first use, whichever occurs first.

响应Response

状态代码Status Code 含义Meaning
200200 API 密钥无效The API key is valid
403403 API 密钥是无效或未授权,以对包推送The API key is invalid or not authorized to push against the package
404404 由包引用IDVERSION(可选) 不存在The package referred to by ID and VERSION (optional) does not exist