套件中繼資料

文章
12/14/2023

您可以使用 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 方法和 GETHEAD。

註冊索引

註冊資源群組套件元數據的套件標識碼。一次無法取得多個套件標識碼的相關數據。此資源無法探索套件識別碼。相反地，用戶端會假設已經知道所需的套件識別碼。每個套件版本的可用元數據會因伺服器實作而異。套件註冊 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"
}

套件中繼資料

版本控制

RegistrationsBaseUrl

RegistrationsBaseUrl/3.4.0

RegistrationsBaseUrl/3.6.0

基礎 URL

HTTP 方法

註冊索引

註冊頁面和離開

要求參數

回應

註冊頁面物件

在頁面中註冊分葉物件

目錄專案

套件相依性群組

套件相依性

套件淘汰

替代套件

弱點

範例要求

範例回應

註冊頁面

範例要求

範例回應

註冊分葉

範例要求

範例回應

意見反映

意見反映

更多資源