目錄
目錄是記錄封裝來源上所有封裝作業的資源,例如建立和刪除。 目錄資源具有Catalog
服務索引中的類型。 您可以使用此資源來 查詢所有已發佈的套件。
注意
因為官方 NuGet 用戶端不會使用目錄,並非所有套件來源都會實作目錄。
注意
目前,nuget.org 目錄不適用於中國。 如需詳細資訊,請參閱 NuGet/NuGetGallery#4949。
使用下列 @type
值:
@type 值 | 備註 |
---|---|
Catalog/3.0.0 | 初始版本 |
下列 API 的進入點 URL 是 @id
與上述資源 @type
值相關聯的屬性值。 本主題使用佔位元 URL {@id}
。
目錄中找到的所有 URL 僅支援 HTTP 方法與 GET
HEAD
。
目錄索引是已知位置中的檔,其中包含目錄專案清單,依時間順序排序。 它是目錄資源的進入點。
索引是由目錄頁面所組成。 每個目錄頁面都包含目錄專案。 每個目錄專案都代表某個時間點上單一封裝的相關事件。 目錄專案可以代表從套件來源建立、取消列出、重新列出或刪除的套件。 藉由依時間順序處理目錄專案,用戶端可以建置 V3 套件來源上每個套件的最新檢視。
簡言之,目錄 Blob 具有下列階層式結構:
- 索引:目錄的進入點。
- 頁面:目錄專案的群組。
- 分葉:代表目錄項目的檔,這是單一套件狀態的快照集。
每個目錄物件都有一個屬性,稱為 commitTimeStamp
,表示專案新增至目錄時。 類別目錄專案會以批次的方式新增至目錄頁面,稱為認可。 相同認可中的所有目錄專案都有相同的認可時間戳 (commitTimeStamp
) 和認可標識碼 (commitId
)。 放在相同認可中的目錄專案代表封裝來源上相同時間點發生的事件。 目錄認可內沒有順序。
因為每個套件標識碼和版本都是唯一的,所以認可中永遠不會有一個以上的目錄專案。 這可確保單一封裝的目錄專案一律可以明確排序,以認可時間戳。
每個 commitTimeStamp
目錄永遠不會有一個以上的認可。 換句話說, commitId
是與 重複的 commitTimeStamp
。
相較於 封裝元數據資源,該資源是以套件標識符編製索引,目錄只會依時間編製索引(且可查詢)。
目錄專案一律會以單調遞增的時間順序新增至目錄。 這表示,如果在 X 時新增目錄認可,則不會以小於或等於 X 的時間新增任何目錄認可。
下列要求會擷取目錄索引。
GET {@id}
目錄索引是 JSON 檔,其中包含具有下列屬性的物件:
名稱 | 類型 | 必要 | 備註 |
---|---|---|---|
commitId | string | 是 | 與最近認可相關聯的唯一標識符 |
commitTimeStamp | string | 是 | 最新認可的時間戳 |
計數 | 整數 | 是 | 索引中的頁數 |
項目 | 物件陣列 | 是 | 對象的陣列,每個代表頁面的物件 |
陣列中的每個 items
元素都是一個物件,每個頁面都有一些最少的詳細數據。 這些頁面物件不包含目錄分葉(專案)。 未定義這個陣列中的項目順序。 頁面可以使用其 commitTimeStamp
屬性,由記憶體中的用戶端排序。
隨著新頁面的導入, count
將會遞增,而且新的物件會出現在數位中 items
。
當專案新增至目錄時,索引將會 commitId
變更,且 commitTimeStamp
將會增加。 這兩個屬性基本上是陣列中items
所有頁面commitId
和commitTimeStamp
值的摘要。
在目錄索引的屬性中找到的 items
目錄頁面物件具有下列屬性:
名稱 | 類型 | 必要 | 備註 |
---|---|---|---|
@id | string | 是 | 要擷取類別目錄頁面的URL |
commitId | string | 是 | 與此頁面中最近認可相關聯的唯一標識符 |
commitTimeStamp | string | 是 | 此頁面中最近認可的時間戳 |
計數 | 整數 | 是 | 目錄頁面中的項目數 |
相較於套件元數據資源,在某些情況下,內嵌會留在索引中,目錄葉永遠不會內嵌到索引中,而且必須使用頁面的 @id
URL 一律擷取。
GET https://api.nuget.org/v3/catalog0/index.json
{
"commitId": "3d698852-eefb-48ed-8f55-9ee357540d20",
"commitTimeStamp": "2017-10-31T23:33:17.0954363Z",
"count": 3,
"items": [
{
"@id": "https://api.nuget.org/v3/catalog0/page0.json",
"commitId": "3a4df280-3d86-458e-a713-4c91ca261fef",
"commitTimeStamp": "2015-02-01T06:30:11.7477681Z",
"count": 540
},
{
"@id": "https://api.nuget.org/v3/catalog0/page1.json",
"commitId": "8bcd3cbf-74f0-47a2-a7ae-b7ecc50005d3",
"commitTimeStamp": "2015-02-01T06:39:53.9553899Z",
"count": 540
},
{
"@id": "https://api.nuget.org/v3/catalog0/page2.json",
"commitId": "3d698852-eefb-48ed-8f55-9ee357540d20",
"commitTimeStamp": "2017-10-31T23:33:17.0954363Z",
"count": 47
}
]
}
目錄頁面是目錄專案的集合。 這是使用目錄索引中找到的 @id
其中一個值擷取的檔。 目錄頁面的 URL 不是可預測的,而且應該只使用目錄索引來探索。
新的目錄專案只會以最高的認可時間戳或新頁面,新增至目錄索引中的頁面。 將具有較高認可時間戳的頁面新增至目錄之後,永遠不會將舊版頁面新增至或變更。
目錄頁面檔是具有下列屬性的 JSON 物件:
名稱 | 類型 | 必要 | 備註 |
---|---|---|---|
commitId | string | 是 | 與此頁面中最近認可相關聯的唯一標識符 |
commitTimeStamp | string | 是 | 此頁面中最近認可的時間戳 |
計數 | 整數 | 是 | 頁面中的項目數 |
項目 | 物件陣列 | 是 | 此頁面中的目錄專案 |
parent | string | 是 | 目錄索引的 URL |
陣列中的每個 items
元素都是物件,其中包含目錄項目的相關一些最小詳細數據。 這些項目物件不包含所有目錄項目的數據。 未定義頁面 items
陣列中項目的順序。 專案可以使用其 commitTimeStamp
屬性,由記憶體中的用戶端排序。
頁面中的目錄項目數目是由伺服器實作所定義。 對於 nuget.org,每個頁面最多有550個專案,不過某些頁面的實際數目可能較小,視時間點下一個認可批次的大小而定。
隨著新項目的導入,會 count
遞增,而且新的目錄項目物件會出現在陣列中 items
。
當專案新增至頁面時, commitId
變更和增加 commitTimeStamp
。 這兩個屬性基本上是陣列中items
所有 commitId
和 commitTimeStamp
值的摘要。
在目錄頁面的屬性中找到的 items
目錄項目物件具有下列屬性:
名稱 | 類型 | 必要 | 備註 |
---|---|---|---|
@id | string | 是 | 要擷取目錄專案的URL |
@type | string | 是 | 目錄專案的型別 |
commitId | string | 是 | 與此目錄項目相關聯的認可標識符 |
commitTimeStamp | string | 是 | 此目錄項目的認可時間戳 |
nuget:id | string | 是 | 此分葉與這個分葉相關的套件標識碼 |
nuget:version | string | 是 | 此分葉與這個分葉相關的套件版本 |
此值 @type
將是下列兩個值的其中一個:
nuget:PackageDetails
:這會對應至PackageDetails
型錄分葉檔中的類型。nuget:PackageDelete
:這會對應至PackageDelete
目錄分葉檔中的類型。
如需每個類型的意義詳細資訊,請參閱 下面的對應項目類型 。
GET https://api.nuget.org/v3/catalog0/page2926.json
{
"commitId": "616117f5-d9dd-4664-82b9-74d87169bbe9",
"commitTimeStamp": "2017-10-31T23:30:32.4197849Z",
"count": 5,
"parent": "https://api.nuget.org/v3/catalog0/index.json",
"items": [
{
"@id": "https://api.nuget.org/v3/catalog0/data/2017.10.31.23.30.32/util.biz.payments.0.0.4-preview.json",
"@type": "nuget:PackageDetails",
"commitId": "616117f5-d9dd-4664-82b9-74d87169bbe9",
"commitTimeStamp": "2017-10-31T23:30:32.4197849Z",
"nuget:id": "Util.Biz.Payments",
"nuget:version": "0.0.4-preview"
},
{
"@id": "https://api.nuget.org/v3/catalog0/data/2017.10.31.23.28.02/util.biz.0.0.4-preview.json",
"@type": "nuget:PackageDetails",
"commitId": "820340b2-97e3-4f93-b82e-bc85550a6560",
"commitTimeStamp": "2017-10-31T23:28:02.788239Z",
"nuget:id": "Util.Biz",
"nuget:version": "0.0.4-preview"
},
{
"@id": "https://api.nuget.org/v3/catalog0/data/2017.10.31.22.31.22/sourcecode.clay.data.1.0.0-preview1-00258.json",
"@type": "nuget:PackageDetails",
"commitId": "cae34527-ffc7-4e96-884f-7cf95a32dbdd",
"commitTimeStamp": "2017-10-31T22:31:22.5169519Z",
"nuget:id": "SourceCode.Clay.Data",
"nuget:version": "1.0.0-preview1-00258"
},
{
"@id": "https://api.nuget.org/v3/catalog0/data/2017.10.31.22.31.22/sourcecode.clay.1.0.0-preview1-00258.json",
"@type": "nuget:PackageDetails",
"commitId": "cae34527-ffc7-4e96-884f-7cf95a32dbdd",
"commitTimeStamp": "2017-10-31T22:31:22.5169519Z",
"nuget:id": "SourceCode.Clay",
"nuget:version": "1.0.0-preview1-00258"
},
{
"@id": "https://api.nuget.org/v3/catalog0/data/2017.10.31.22.31.22/sourcecode.clay.json.1.0.0-preview1-00258.json",
"@type": "nuget:PackageDetails",
"commitId": "cae34527-ffc7-4e96-884f-7cf95a32dbdd",
"commitTimeStamp": "2017-10-31T22:31:22.5169519Z",
"nuget:id": "SourceCode.Clay.Json",
"nuget:version": "1.0.0-preview1-00258"
}
]
}
目錄分葉包含特定套件標識碼和某個時間點版本的相關元數據。 這是使用 @id
在目錄頁面中找到的值擷取的檔。 目錄分葉的 URL 不是可預測的,而且應該只使用目錄頁面來探索。
目錄分葉檔是具有下列屬性的 JSON 物件:
名稱 | 類型 | 必要 | 備註 |
---|---|---|---|
@type | 字串或字串串數位 | 是 | 目錄專案的 type(s) |
catalog:commitId | string | 是 | 與此目錄項目相關聯的認可標識符 |
catalog:commitTimeStamp | string | 是 | 此目錄項目的認可時間戳 |
id | string | 是 | 目錄專案的套件識別碼 |
發表 | string | 是 | 套件目錄項目的發佈日期 |
version | string | 是 | 目錄專案的套件版本 |
屬性 @type
是字串或字串數位。 為了方便起見,如果 @type
值是字串,它應該視為第一個大小的任何陣列。 並非所有可能的值 @type
都會記錄。 不過,每個目錄專案只有下列兩個字串類型值之一:
PackageDetails
:表示封裝元數據的快照集PackageDelete
:表示已刪除的套件
具有 型 PackageDetails
別的目錄專案包含特定套件的套件元數據快照集(標識符和版本組合)。 當套件來源遇到下列任何案例時,會產生套件詳細數據目錄專案:
- 已推送套件。
- 已重新列出套件。
- 套件未列出。
- 套件已被取代。
- 套件尚未 淘汰。
- 已重排套件。
- 套件的 弱點狀態 已更新。
套件重排是系統管理手勢,基本上會產生現有套件的假推送,且套件本身不會有任何變更。 在 nuget.org,修正其中一個取用目錄的背景作業中的 Bug 之後,就會使用重排。
取用類別目錄專案的客戶端不應該嘗試判斷這些案例中的哪一個會產生類別目錄專案。 相反地,客戶端應該只要使用目錄專案中包含的元數據來更新任何維護的檢視或索引。 此外,應正常處理重複或備援目錄專案(等冪)。
除了所有目錄分葉中包含的屬性之外,套件詳細數據目錄項目還有下列屬性。
名稱 | 類型 | 必要 | 備註 |
---|---|---|---|
作者 | string | 否 | |
created | string | 否 | 第一次建立封裝時的時間戳。 後援屬性: published 。 |
dependencyGroups | 物件陣列 | 否 | 套件的相依性,依目標架構分組(與套件元數據資源的格式相同) |
折舊 | object | 否 | 與封裝相關聯的取代 (與套件元數據資源的格式相同) |
description | string | 否 | |
iconUrl | string | 否 | |
isPrerelease | boolean | 否 | 套件版本是否為發行前版本。 可以從 偵測到 version 。 |
language | string | 否 | |
licenseUrl | string | 否 | |
列出的 | boolean | 否 | 是否列出套件 |
minClientVersion | string | 否 | |
packageHash | string | 是 | 封裝的哈希,使用 標準基底 64 編碼 |
packageHashAlgorithm | string | 是 | |
packageSize | 整數 | 是 | 套件 .nupkg 的大小,以位元組為單位 |
packageTypes | 物件陣列 | 否 | 作者指定的封裝類型。 |
projectUrl | string | 否 | |
releaseNotes | string | 否 | |
requireLicenseAgreement | boolean | 否 | 假設 false 已排除 |
摘要 | string | 否 | |
標記 | 字串陣列 | 否 | |
title | string | 否 | |
verbatimVersion | string | 否 | 版本字串,因為它最初在 .nuspec 中找到 |
漏洞 | 物件陣列 | 否 | 套件的安全性弱點 |
package version
屬性是正規化之後的完整版本字串。 這表示 SemVer 2.0.0 組建數據可以包含在這裡。
created
時間戳是封裝來源第一次收到封裝的時間,這通常是目錄專案認可時間戳之前的短時間。
packageHashAlgorithm
是伺服器實作所定義的字串,表示用來產生的packageHash
哈希演算法。 nuget.org 一律使用 packageHashAlgorithm
的值 SHA512
。
packageTypes
只有當作者指定封裝類型時,屬性才會存在。 如果存在,它一律會有至少一個 (1) 個專案。 陣列中的每個 packageTypes
專案都是具有下列屬性的 JSON 物件:
名稱 | 類型 | 必要 | 注意 |
---|---|---|---|
NAME | 字串 | 是 | 封裝類型的名稱。 |
version | string | 否 | 套件類型的版本。 只有在作者在 nuspec 中明確指定版本時才存在。 |
時間戳 published
是上次列出封裝的時間。
注意
在 nuget.org 上,當套件取消列出時,此值 published
會設定為 1900 年。
vulnerability
物件的陣列。 每個弱點都有下列屬性:
名稱 | 類型 | 必要 | 備註 |
---|---|---|---|
advisoryUrl | string | 是 | 套件的安全性諮詢位置 |
severity | string | 是 | 諮詢嚴重性:「0」 = 低,“1” = 中度,“2” = 高,“3” = 重大 |
severity
如果 屬性包含此處所列以外的值,則諮詢的嚴重性會被視為低。
GET https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json
{
"@type": [
"PackageDetails",
"catalog:Permalink"
],
"authors": "NuGet.org Team",
"catalog:commitId": "49fe04d8-5694-45a5-9822-3be61bda871b",
"catalog:commitTimeStamp": "2015-02-01T11:18:40.8589193Z",
"created": "2011-12-02T20:21:23.74Z",
"description": "This package is an example for the V3 protocol.",
"deprecation": {
"reasons": [
"Legacy",
"HasCriticalBugs",
"Other"
],
"message": "This package is an example--it should not be used!",
"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",
"isPrerelease": false,
"language": "en-US",
"licenseUrl": "http://www.opensource.org/licenses/ms-pl",
"packageHash": "2edCwKLcbcgFJpsAwa883BLtOy8bZpWwbQpiIb71E74k5t2f2WzXEGWbPwntRleUEgSrcxJrh9Orm/TAmgO4NQ==",
"packageHashAlgorithm": "SHA512",
"packageSize": 118348,
"packageTypes": [
{
"@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json#packagetypes/DotnetTool",
"@type": "PackageType",
"name": "DotnetTool"
}
],
"projectUrl": "https://github.com/NuGet/NuGetGallery",
"published": "1900-01-01T00:00:00Z",
"requireLicenseAcceptance": false,
"title": "NuGet V3 Protocol Example",
"version": "1.0.0",
"dependencyGroups": [
{
"@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json#dependencygroup",
"@type": "PackageDependencyGroup",
"dependencies": [
{
"@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json#dependencygroup/aspnet.suppressformsredirect",
"@type": "PackageDependency",
"id": "aspnet.suppressformsredirect",
"range": "[0.0.1.4, )"
},
{
"@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json#dependencygroup/webactivator",
"@type": "PackageDependency",
"id": "WebActivator",
"range": "[1.4.4, )"
},
{
"@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json#dependencygroup/webapi.all",
"@type": "PackageDependency",
"id": "WebApi.All",
"range": "[0.5.0, )"
}
],
"targetFramework": ".NETFramework4.6"
}
],
"tags": [
"NuGet",
"V3",
"Protocol",
"Example"
],
"vulnerabilities": [
{
"@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json#vulnerability/GitHub/999",
"@type": "Vulnerability",
"advisoryUrl": "https://github.com/advisories/ABCD-1234-5678-9012",
"severity": "2"
}
]
}
具有 型 PackageDelete
別的類別目錄專案包含一組最少的資訊,指出封裝已從封裝來源中刪除封裝,而且無法再用於任何封裝作業(例如還原)。
注意
您可以使用相同的套件識別碼和版本來刪除和更新版本來刪除和重新發佈套件。 在 nuget.org,這是非常罕見的情況,因為它會中斷官方用戶端假設套件標識碼和版本暗示特定套件內容。 如需 nuget.org 上套件刪除的詳細資訊,請參閱 我們的原則。
除了所有目錄分葉中包含的專案之外,套件刪除目錄項目沒有其他屬性。
屬性 version
是套件 .nuspec 中找到的原始版本字串。
屬性 published
是刪除封裝的時間,通常是目錄項目認可時間戳之前的短時間。
GET https://api.nuget.org/v3/catalog0/data/2017.11.02.00.40.00/netstandard1.4_lib.1.0.0-test.json
{
"@type": [
"PackageDelete",
"catalog:Permalink"
],
"catalog:commitId": "19fec5b4-9335-4e4b-bd50-8d5d3f734597",
"catalog:commitTimeStamp": "2017-11-02T00:40:00.1969812Z",
"id": "netstandard1.4_lib",
"originalId": "netstandard1.4_lib",
"published": "2017-11-02T00:37:43.7181952Z",
"version": "1.0.0-test"
}
本節描述用戶端概念,雖然不一定是通訊協定所授權,但應該是任何實際類別目錄用戶端實作的一部分。
因為目錄是依時間編製索引的附加數據結構,客戶端應該在本機儲存 數據指標 ,最多代表用戶端已處理目錄項目的時間點。 請注意,絕對不應該使用用戶端的計算機時鐘產生這個數據指標值。 相反地,值應該來自目錄物件的 commitTimestamp
值。
每次用戶端想要處理套件來源上的新事件時,它只需要查詢所有具有大於其預存數據指標的認可時間戳目錄。 用戶端成功處理所有新的目錄項目之後,它會記錄目錄專案的最新認可時間戳,只是當做其新的數據指標值處理。
使用此方法時,客戶端絕對不會遺漏封裝來源上發生的任何套件事件。 此外,客戶端絕對不需要在數據指標的記錄認可時間戳之前重新處理舊事件。
這個強大的數據指標概念可用於許多 nuget.org 背景工作,並用來讓 V3 API 本身保持最新狀態。
當目錄用戶端第一次啟動時(因此沒有數據指標值),它應該使用的預設數據指標值。 System.DateTimeOffset.MinValue
NET 或一些類似最小可表示時間戳的概念。
若要查詢要處理的下一組目錄專案,客戶端應該:
- 從本地存儲擷取記錄的數據指標值。
- 下載並還原串行化目錄索引。
- 尋找認可時間戳 大於 數據指標的所有目錄頁面。
- 宣告要處理的目錄專案空白清單。
- 針對步驟 3 中相符的每個類別目錄頁面:
- 下載並還原串行化目錄頁面。
- 尋找認可時間戳 大於 數據指標的所有目錄專案。
- 將所有相符的目錄專案新增至步驟 4 中宣告的清單。
- 依認可時間戳排序目錄項目清單。
- 依序處理每個目錄專案:
- 下載並還原串行化目錄專案。
- 適當地回應目錄項目的類型。
- 以用戶端特定方式處理目錄項目檔。
- 將最後一個目錄項目的認可時間戳記錄為新的數據指標值。
透過這個基本演算法,用戶端實作可以建置套件來源上所有可用套件的完整檢視。 用戶端只需要定期執行此演算法,才能隨時留意封裝來源的最新變更。
注意
這是 nuget.org 用來讓套件元數據、套件內容、搜尋和自動完成資源保持在最新狀態的演算法。
假設有兩個類別目錄用戶端具有固有相依性,其中一個客戶端的輸出相依於另一個客戶端的輸出。
例如,在 nuget.org 新發行的套件不應該出現在搜尋資源中,才會出現在套件元數據資源中。 這是因為官方 NuGet 用戶端執行的「還原」作業會使用套件元數據資源。 如果客戶使用搜尋服務探索套件,他們應該能夠使用套件元數據資源成功還原該套件。 換句話說,搜尋資源取決於套件元數據資源。 每個資源都有更新該資源的目錄用戶端背景作業。 每個用戶端都有自己的數據指標。
由於這兩個資源都是建置在目錄之外,因此更新搜尋資源的 目錄客戶端數據指標不能超出 封裝元數據目錄客戶端的數據指標。
若要實作這項限制,只要修改上述演算法即可:
- 從本地存儲擷取記錄的數據指標值。
- 下載並還原串行化目錄索引。
- 尋找認可時間戳 大於數據 指標小於或等於相依性數據指標 的所有目錄頁面。
- 宣告要處理的目錄專案空白清單。
- 針對步驟 3 中相符的每個類別目錄頁面:
- 下載並還原串行化目錄頁面。
- 尋找認可時間戳 大於數據 指標小於或等於相依性數據指標 的所有目錄專案。
- 將所有相符的目錄專案新增至步驟 4 中宣告的清單。
- 依認可時間戳排序目錄項目清單。
- 依序處理每個目錄專案:
- 下載並還原串行化目錄專案。
- 適當地回應目錄項目的類型。
- 以用戶端特定方式處理目錄項目檔。
- 將最後一個目錄項目的認可時間戳記錄為新的數據指標值。
使用此修改的演算法,您可以建置相依類別目錄客戶端的系統,這些客戶端都會產生自己的特定索引、成品等。