@type 值	備註
Catalog/3.0.0	初始版本

索引是由目錄頁面所組成。每個目錄頁面都包含目錄專案。每個目錄專案都代表某個時間點上單一封裝的相關事件。目錄專案可以代表從套件來源建立、取消列出、重新列出或刪除的套件。藉由依時間順序處理目錄專案，用戶端可以建置 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 中相符的每個類別目錄頁面：
1. 下載並還原串行化目錄頁面。
2. 尋找認可時間戳大於數據指標的所有目錄專案。
3. 將所有相符的目錄專案新增至步驟 4 中宣告的清單。
依認可時間戳排序目錄項目清單。
依序處理每個目錄專案：
1. 下載並還原串行化目錄專案。
2. 適當地回應目錄項目的類型。
3. 以用戶端特定方式處理目錄項目檔。
將最後一個目錄項目的認可時間戳記錄為新的數據指標值。

透過這個基本演算法，用戶端實作可以建置套件來源上所有可用套件的完整檢視。用戶端只需要定期執行此演算法，才能隨時留意封裝來源的最新變更。

注意

這是 nuget.org 用來讓套件元數據、套件內容、搜尋和自動完成資源保持在最新狀態的演算法。

相依數據指標

假設有兩個類別目錄用戶端具有固有相依性，其中一個客戶端的輸出相依於另一個客戶端的輸出。

範例

例如，在 nuget.org 新發行的套件不應該出現在搜尋資源中，才會出現在套件元數據資源中。這是因為官方 NuGet 用戶端執行的「還原」作業會使用套件元數據資源。如果客戶使用搜尋服務探索套件，他們應該能夠使用套件元數據資源成功還原該套件。換句話說，搜尋資源取決於套件元數據資源。每個資源都有更新該資源的目錄用戶端背景作業。每個用戶端都有自己的數據指標。

由於這兩個資源都是建置在目錄之外，因此更新搜尋資源的 目錄客戶端數據指標不能超出 封裝元數據目錄客戶端的數據指標。

演算法

若要實作這項限制，只要修改上述演算法即可：

從本地存儲擷取記錄的數據指標值。
下載並還原串行化目錄索引。
尋找認可時間戳 大於數據 指標小於或等於相依性數據指標 的所有目錄頁面。
宣告要處理的目錄專案空白清單。
針對步驟 3 中相符的每個類別目錄頁面：
1. 下載並還原串行化目錄頁面。
2. 尋找認可時間戳 大於數據 指標小於或等於相依性數據指標 的所有目錄專案。
3. 將所有相符的目錄專案新增至步驟 4 中宣告的清單。
依認可時間戳排序目錄項目清單。
依序處理每個目錄專案：
1. 下載並還原串行化目錄專案。
2. 適當地回應目錄項目的類型。
3. 以用戶端特定方式處理目錄項目檔。
將最後一個目錄項目的認可時間戳記錄為新的數據指標值。

使用此修改的演算法，您可以建置相依類別目錄客戶端的系統，這些客戶端都會產生自己的特定索引、成品等。

意見反應

此頁面對您有幫助嗎？

Last updated on 2023-12-14

目錄

版本控制

基礎 URL

HTTP 方法

目錄索引

索引中的目錄頁面物件

範例要求

範例回應

目錄頁面

頁面中的目錄項目物件

範例要求

範例回應

目錄分葉

項目類型

套件詳細資料目錄專案

弱點

範例要求

範例回應

封裝刪除目錄專案

範例要求

範例回應

資料指標

概觀

初始值

逐一查看目錄專案

相依數據指標

範例

演算法

意見反應

其他資源