NuGet 伺服器 API

文章
12/14/2023

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 第一次發行以來，已對 API 進行非中斷的通訊協議變更。

資源和架構

服務索引描述各種資源。目前支援的一組資源如下所示：

資源名稱	必要	描述
目錄	否	所有封裝事件的完整記錄。
PackageBaseAddress	是	取得套件內容（.nupkg）。
PackageDetailsUriTemplate	否	建構 URL 以存取套件詳細數據網頁。
PackagePublish	是	推送和刪除（或取消列出）套件。
RegistrationsBaseUrl	是	取得套件元數據。
ReportAbuseUriTemplate	否	建構 URL 以存取報告濫用網頁。
RepositorySignatures	否	取得用於存放庫簽署的憑證。
SearchAutocompleteService	否	依子字串探索套件標識碼和版本。
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 通訊協定緊密結合的資源，而 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 要求。

X-NuGet-Session-Id對於中PackageReference單一還原相關的所有作業，都有單一值。針對其他案例，例如自動完成和 packages.config 還原，可能會因為程式代碼的分解方式而有數個不同的會話標識碼。

驗證

驗證會保留至要定義的套件來源實作。針對 nuget.org，只有 PackagePublish 資源需要透過特殊的 API 金鑰標頭進行驗證。如需詳細資訊，請參閱 PackagePublish 資源。