套件中繼資料

您可以使用 NuGet V3 API 來擷取套件來源上可用套件的相關元數據。 您可以使用服務索引中找到的資源來擷取RegistrationsBaseUrl此元數據。

找到的檔 RegistrationsBaseUrl 集合通常稱為「註冊」或「註冊 Blob」。 單 RegistrationsBaseUrl 一下的一組檔稱為「註冊區」。 註冊 Hive 包含套件來源上每個可用套件的相關元數據。

版本控制

使用下列 @type 值：

這代表適用於各種用戶端版本的三個不同的註冊區。

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 是使用 所實作規則所實作的所需套件標識碼小寫。NET 的 System.String.ToLowerInvariant() 方法。

回應

回應是 JSON 檔，其中包含具有下列屬性的根物件：

索引物件陣列中的每個專案都是代表註冊頁面的 items JSON 物件。

註冊頁面物件

註冊索引中找到的註冊頁面物件具有下列屬性：

lower需要特定頁面版本的元數據時，頁面物件的和 upper 界限很有用。 這些界限可用來擷取所需的唯一註冊頁面。 版本字串遵守 NuGet 的版本規則。 版本字串會正規化，且不包含組建元數據。 如同 NuGet 生態系統中的所有版本，版本字串的比較是使用 SemVer 2.0.0 的版本優先順序規則來實作。

parent只有在註冊頁面物件具有 items 屬性時，才會顯示 屬性。

items如果屬性不存在於註冊頁面物件中，則必須使用 中指定的 @id URL來擷取個別套件版本的元數據。 items數位有時會從頁面物件中排除為優化。 如果單一套件標識碼的版本數目非常大，則註冊索引檔將會非常龐大且浪費，以處理只關心特定版本或少量版本的用戶端。

請注意，如果 items 屬性存在， @id 則不需要使用 屬性，因為所有頁面數據都已經內嵌在屬性中 items 。

頁面物件 items 陣列中的每個專案都是代表註冊分葉的 JSON 物件，而且是相關聯的元數據。

在頁面中註冊分葉物件

註冊頁面中找到的註冊分葉物件具有下列屬性：

每個註冊分葉物件都代表與單一套件版本相關聯的數據。

目錄專案

catalogEntry註冊分葉物件中的 屬性具有下列屬性：

package version 屬性是正規化之後的完整版本字串。 這表示 SemVer 2.0.0 組建數據可以包含在這裡。

屬性 dependencyGroups 是對象的陣列，代表封裝的相依性，依目標架構分組。 如果封裝沒有相依性，則 dependencyGroups 屬性遺失、空陣列或 dependencies 所有群組的 屬性都是空的或遺失的。

屬性的值 licenseExpression 符合 NuGet 授權表達式語法。

套件相依性群組

每個相依性群組物件都有下列屬性：

字串 targetFramework 會使用 NuGet 的 .NET 連結庫 NuGet.Frameworks 所實作的格式。 targetFramework如果未指定 ，則相依性群組會套用至所有目標架構。

屬性 dependencies 是 對象的數位，每個物件都代表目前封裝的套件相依性。

套件相依性

每個套件相依性都有下列屬性：

如果排除 屬性 range 或空字串，客戶端應該預設為版本範圍 (, )。 也就是說，允許任何版本的相依性。 屬性不允許 range 的 值*。

套件淘汰

每個封裝取代都有下列屬性：

屬性 reasons 必須至少包含一個字串，而且應該只包含下表中的字串：

reasons如果 屬性包含不是來自已知集合的字串，則應該忽略它們。 字串不區分大小寫，因此 legacy 應該與一樣 Legacy處理。 陣列沒有排序限制，因此字串可以依任意順序排列。 此外，如果屬性只包含不是來自已知集合的字串，它應該被視為只包含 「Other」 字串。

替代套件

替代套件物件具有下列屬性：

弱點

vulnerability 物件的陣列。 每個弱點都有下列屬性：

範例要求

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 不是可預測的，而且應該一律透過索引檔探索。

items當陣列未在註冊索引中提供時，值的 HTTP GET 要求@id會傳回 JSON 檔，此檔具有 物件做為其根目錄。 物件具有下列屬性：

註冊分葉物件的圖形與上述註冊索引相同。

範例要求

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 不是可預測的，而且應該一律透過註冊頁面物件來探索。

註冊分葉是具有下列屬性之根物件的 JSON 檔：

範例要求

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"
}