套件中繼資料
您可以使用 NuGet V3 API 來擷取套件來源上可用套件的相關元數據。 您可以使用服務索引中找到的資源來擷取RegistrationsBaseUrl
此元數據。
找到的檔 RegistrationsBaseUrl
集合通常稱為「註冊」或「註冊 Blob」。 單 RegistrationsBaseUrl
一下的一組檔稱為「註冊區」。 註冊 Hive 包含套件來源上每個可用套件的相關元數據。
注意
套件元數據資源不包含套件的所有元數據。 使用搜尋資源來尋找套件的擁有者、下載或前置詞保留狀態。
版本控制
使用下列 @type
值:
@type 值 | 備註 |
---|---|
RegistrationsBaseUrl | 初始版本 |
RegistrationsBaseUrl/3.0.0-beta | 的別名 RegistrationsBaseUrl |
RegistrationsBaseUrl/3.0.0-rc | 的別名 RegistrationsBaseUrl |
RegistrationsBaseUrl/3.4.0 | Gzipped 回應 |
RegistrationsBaseUrl/3.6.0 | 包含 SemVer 2.0.0 套件 |
這代表適用於各種用戶端版本的三個不同的註冊區。
RegistrationsBaseUrl
這些註冊不會壓縮(這表示它們使用隱含 Content-Encoding: identity
的 )。 SemVer 2.0.0 套件 會 從這個 Hive 中排除。
RegistrationsBaseUrl/3.4.0
這些註冊會使用 Content-Encoding: gzip
壓縮。 SemVer 2.0.0 套件 會 從這個 Hive 中排除。
RegistrationsBaseUrl/3.6.0
這些註冊會使用 Content-Encoding: gzip
壓縮。 SemVer 2.0.0 套件 包含在 此 Hive 中。
如需 SemVer 2.0.0 的詳細資訊,請參閱 SemVer 2.0.0 支援 nuget.org。
基礎 URL
下列 API 的基底 URL 是 @id
與上述資源 @type
值相關聯的屬性值。 在下列檔中,將會使用佔位元基底 URL {@id}
。 基底 URL 可能會根據套件來源內的實作或基礎結構變更而變更,因此用戶端軟體必須以動態方式從 服務索引 擷取。
HTTP 方法
註冊資源中找到的所有 URL 都支援 HTTP 方法和 GET
HEAD
。
註冊索引
註冊資源群組套件元數據的套件標識碼。 一次無法取得多個套件標識碼的相關數據。 此資源無法探索套件識別碼。 相反地,用戶端會假設已經知道所需的套件識別碼。 每個套件版本的可用元數據會因伺服器實作而異。 套件註冊 Blob 具有下列階層式結構:
- 索引:套件元數據的進入點,由來源上具有相同套件標識碼的所有套件共用。
- 頁面:套件版本的群組。 頁面中的套件版本數目是由伺服器實作所定義。
- 分葉:單一套件版本特定的檔。
註冊索引的 URL 是可預測的,而且可由用戶端指定套件識別碼,以及服務索引中的註冊資源 @id
值來決定。 註冊頁面和離開的 URL 會藉由檢查註冊索引來探索。
註冊頁面和離開
雖然伺服器實作並非嚴格要求將註冊分葉儲存在個別註冊頁面檔中,但建議的做法是節省用戶端記憶體。 建議伺服器實作會根據套件版本數目或套件離開的累計大小,在兩種方法之間選擇一些啟發學習法,而不是將所有註冊留在索引中,或立即儲存在分頁檔中。建議伺服器實作定義一些啟發學習法,以在兩種方法之間選擇。
將所有套件版本儲存在註冊索引中,會儲存擷取套件元數據所需的 HTTP 要求數目,但表示必須下載較大的檔,而且必須配置更多用戶端記憶體。 另一方面,如果伺服器實作立即將註冊儲存在不同的頁面檔中,客戶端必須執行更多 HTTP 要求,以取得所需的資訊。
nuget.org 使用的啟發學習法如下:如果有 128 個以上的套件版本,請將分葉分成大小為 64 的頁面。 如果版本少於 128 個,內嵌全部會留在註冊索引中。 請注意,這表示具有 65 到 127 版本的套件在索引中會有兩個頁面,但兩個頁面都會內嵌。
GET {@id}/{LOWER_ID}/index.json
要求參數
名稱 | 位於 | 類型 | 必要 | 備註 |
---|---|---|---|---|
LOWER_ID | URL | string | 是 | 封裝標識碼,小寫 |
值 LOWER_ID
是使用 所實作規則所實作的所需套件標識碼小寫。NET 的 System.String.ToLowerInvariant()
方法。
回應
回應是 JSON 檔,其中包含具有下列屬性的根物件:
名稱 | 類型 | 必要 | 備註 |
---|---|---|---|
計數 | 整數 | 是 | 索引中的註冊頁數 |
項目 | 物件陣列 | 是 | 註冊頁面的陣列 |
索引物件陣列中的每個專案都是代表註冊頁面的 items
JSON 物件。
註冊頁面物件
註冊索引中找到的註冊頁面物件具有下列屬性:
名稱 | 類型 | 必要 | 備註 |
---|---|---|---|
@id | string | 是 | 註冊頁面的 URL |
計數 | 整數 | 是 | 在頁面中留下的註冊數目 |
項目 | 物件陣列 | 否 | 註冊陣列及其關聯的元數據 |
降低 | string | 是 | 頁面的最低 SemVer 2.0.0 版本(含) |
parent | string | 否 | 註冊索引的 URL |
上方 | string | 是 | 頁面中最高的 SemVer 2.0.0 版本(含) |
lower
需要特定頁面版本的元數據時,頁面物件的和 upper
界限很有用。
這些界限可用來擷取所需的唯一註冊頁面。 版本字串遵守 NuGet 的版本規則。 版本字串會正規化,且不包含組建元數據。 如同 NuGet 生態系統中的所有版本,版本字串的比較是使用 SemVer 2.0.0 的版本優先順序規則來實作。
parent
只有在註冊頁面物件具有 items
屬性時,才會顯示 屬性。
items
如果屬性不存在於註冊頁面物件中,則必須使用 中指定的 @id
URL來擷取個別套件版本的元數據。 items
數位有時會從頁面物件中排除為優化。 如果單一套件標識碼的版本數目非常大,則註冊索引檔將會非常龐大且浪費,以處理只關心特定版本或少量版本的用戶端。
請注意,如果 items
屬性存在, @id
則不需要使用 屬性,因為所有頁面數據都已經內嵌在屬性中 items
。
頁面物件 items
陣列中的每個專案都是代表註冊分葉的 JSON 物件,而且是相關聯的元數據。
在頁面中註冊分葉物件
註冊頁面中找到的註冊分葉物件具有下列屬性:
名稱 | 類型 | 必要 | 備註 |
---|---|---|---|
@id | string | 是 | 註冊分葉的 URL |
catalogEntry | object | 是 | 包含套件元數據的目錄專案 |
packageContent | string | 是 | 套件內容的 URL (.nupkg) |
每個註冊分葉物件都代表與單一套件版本相關聯的數據。
目錄專案
catalogEntry
註冊分葉物件中的 屬性具有下列屬性:
名稱 | 類型 | 必要 | 備註 |
---|---|---|---|
@id | string | 是 | 用來產生這個物件的檔的 URL |
作者 | 字串或字串串數位 | 否 | |
dependencyGroups | 物件陣列 | 否 | 套件的相依性,依目標架構分組 |
折舊 | object | 否 | 與封裝相關聯的取代 |
description | string | 否 | |
iconUrl | string | 否 | |
id | string | 是 | 封裝的標識碼 |
language | string | 否 | |
licenseUrl | string | 否 | |
licenseExpression | string | 否 | |
列出的 | boolean | 否 | 如果不存在,應該視為已列出 |
minClientVersion | string | 否 | |
packageContent | string | 否 | 父物件中相同屬性的重複專案,僅因舊版原因而包含 |
projectUrl | string | 否 | |
發表 | string | 否 | 字串,包含發佈封裝時之 的 ISO 8601 時間戳 |
readmeUrl | string | 否 | 封裝自述文件轉譯之 [HTML 網頁] 檢視的 URL |
requireLicenseAcceptance | boolean | 否 | |
摘要 | string | 否 | |
標記 | 字串或字串串數位 | 否 | |
title | string | 否 | |
version | string | 是 | 正規化之後的完整版本字串 |
漏洞 | 物件陣列 | 否 | 套件的安全性弱點 |
package version
屬性是正規化之後的完整版本字串。 這表示 SemVer 2.0.0 組建數據可以包含在這裡。
屬性 dependencyGroups
是對象的陣列,代表封裝的相依性,依目標架構分組。 如果封裝沒有相依性,則 dependencyGroups
屬性遺失、空陣列或 dependencies
所有群組的 屬性都是空的或遺失的。
屬性的值 licenseExpression
符合 NuGet 授權表達式語法。
注意
在 nuget.org 上,當套件取消列出時,此值 published
會設定為 1900 年。
套件相依性群組
每個相依性群組物件都有下列屬性:
名稱 | 類型 | 必要 | 備註 |
---|---|---|---|
targetFramework | string | 否 | 這些相依性適用的目標架構 |
相依性 | 物件陣列 | 否 |
字串 targetFramework
會使用 NuGet 的 .NET 連結庫 NuGet.Frameworks 所實作的格式。 targetFramework
如果未指定 ,則相依性群組會套用至所有目標架構。
屬性 dependencies
是 對象的數位,每個物件都代表目前封裝的套件相依性。
套件相依性
每個套件相依性都有下列屬性:
名稱 | 類型 | 必要 | 備註 |
---|---|---|---|
id | string | 是 | 套件相依性標識碼 |
range | object | 否 | 相依性允許的版本範圍 |
註冊 | string | 否 | 此相依性之註冊索引的URL |
如果排除 屬性 range
或空字串,客戶端應該預設為版本範圍 (, )
。 也就是說,允許任何版本的相依性。 屬性不允許 range
的 值*
。
套件淘汰
每個封裝取代都有下列屬性:
名稱 | 類型 | 必要 | 備註 |
---|---|---|---|
原因 | 字串陣列 | 是 | 套件已被取代的原因 |
message | string | 否 | 此取代的其他詳細數據 |
alternatePackage | object | 否 | 應該改用的替代套件 |
屬性 reasons
必須至少包含一個字串,而且應該只包含下表中的字串:
原因 | 描述 |
---|---|
舊版 | 不再維護套件 |
CriticalBugs | 套件有錯誤,使其不適合使用 |
其他 | 由於此列表沒有原因,套件已被取代 |
reasons
如果 屬性包含不是來自已知集合的字串,則應該忽略它們。 字串不區分大小寫,因此 legacy
應該與一樣 Legacy
處理。 陣列沒有排序限制,因此字串可以依任意順序排列。 此外,如果屬性只包含不是來自已知集合的字串,它應該被視為只包含 「Other」 字串。
替代套件
替代套件物件具有下列屬性:
名稱 | 類型 | 必要 | 備註 |
---|---|---|---|
id | string | 是 | 替代套件的標識碼 |
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 (https://api.nuget.org/v3/registration-sample/
在此範例中),如基底 URL 一節中所述。
範例回應
{
"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
當陣列未在註冊索引中提供時,值的 HTTP GET 要求@id
會傳回 JSON 檔,此檔具有 物件做為其根目錄。 物件具有下列屬性:
名稱 | 類型 | 必要 | 備註 |
---|---|---|---|
@id | string | 是 | 註冊頁面的 URL |
計數 | 整數 | 是 | 在頁面中留下的註冊數目 |
項目 | 物件陣列 | 是 | 註冊陣列及其關聯的元數據 |
降低 | string | 是 | 頁面的最低 SemVer 2.0.0 版本(含) |
parent | string | 是 | 註冊索引的 URL |
上方 | 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 (https://api.nuget.org/v3/registration-sample/
在此範例中),如基底 URL 一節中所述。
範例回應
{
"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"
}
]
}
註冊分葉
註冊分葉包含特定套件標識碼和版本的相關信息。 本檔可能無法取得特定版本的元數據。 套件元數據應該從 註冊索引 或 註冊頁面 擷取(使用註冊索引探索)。
擷取註冊分葉的 URL 是從註冊索引或註冊頁面中註冊分葉對象的 屬性取得 @id
。 和頁面檔一樣。 URL 不是可預測的,而且應該一律透過註冊頁面物件來探索。
警告
在 nuget.org,註冊分葉檔的 URL 會巧合地包含套件版本。 不過,客戶端不應該進行此假設,因為只要父檔具有有效的連結,伺服器實作就可以自由變更 URL 的形狀。
註冊分葉是具有下列屬性之根物件的 JSON 檔:
名稱 | 類型 | 必要 | 備註 |
---|---|---|---|
@id | string | 是 | 註冊分葉的 URL |
catalogEntry | string | 否 | 產生這些分葉之目錄專案的URL |
列出的 | boolean | 否 | 如果不存在,應該視為已列出 |
packageContent | string | 否 | 套件內容的 URL (.nupkg) |
發表 | string | 否 | 字串,包含發佈封裝時之 的 ISO 8601 時間戳 |
註冊 | string | 否 | 註冊索引的 URL |
注意
在 nuget.org 上,當套件取消列出時,此值 published
會設定為 1900 年。
範例要求
GET https://api.nuget.org/v3/registration-sample/nuget.versioning/4.3.0.json
請務必從服務索引擷取基底 URL (https://api.nuget.org/v3/registration-sample/
在此範例中),如基底 URL 一節中所述。
範例回應
{
"@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"
}