次の方法で共有


パッケージ メタデータ

NuGet V3 API を使用して、パッケージ ソースで使用可能なパッケージに関するメタデータをフェッチできます。 このメタデータは、サービス インデックスにある RegistrationsBaseUrl リソースを使用してフェッチできます。

RegistrationsBaseUrl にあるドキュメントのコレクションは、多くの場合、"登録" または "登録 BLOB" と呼ばれます。 1 つの RegistrationsBaseUrl にあるドキュメントのセットは、"登録 Hive" と呼ばれます。 登録 Hive には、パッケージ ソースで使用可能なすべてのパッケージに関するメタデータが含まれています。

Note

パッケージ メタデータ リソースには、パッケージのすべてのメタデータが含まれているわけではありません。 検索リソースを使用して、パッケージの所有者、ダウンロード、またはプレフィックス予約の状態を検索します。

バージョン管理

次の @type の値が使用されます。

@type 値 メモ
RegistrationsBaseUrl 初期リリース
RegistrationsBaseUrl/3.0.0-beta RegistrationsBaseUrl の別名
RegistrationsBaseUrl/3.0.0-rc RegistrationsBaseUrl の別名
RegistrationsBaseUrl/3.4.0 gzip 圧縮された応答
RegistrationsBaseUrl/3.6.0 SemVer 2.0.0 パッケージを含む

これは、さまざまなクライアント バージョンで使用できる 3 つの個別の登録 Hive を表します。

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 の詳細については、「nuget.org による SemVer 2.0.0 のサポート」を参照してください。

ベース URL

次の API のベース URL は、前述のリソースの @type 値に関連付けられている @id プロパティの値です。 次のドキュメントでは、プレースホルダーのベース URL {@id} が使用されます。 ベース URL は、パッケージ ソース内の実装またはインフラストラクチャの変更に基づいて変化する可能性があるため、クライアント ソフトウェアによってサービス インデックスから動的にフェッチする必要があります。

HTTP メソッド

登録リソースにあるすべての URL は、HTTP メソッド GETHEAD をサポートしています。

登録 インデックス

登録リソースは、パッケージ ID ごとにパッケージ メタデータをグループ化します。 一度に複数のパッケージ ID に関するデータを取得することはできません。 このリソースでは、パッケージ ID を検出する方法はありません。 代わりに、クライアントは目的のパッケージ ID を既に認識していると想定されています。 各パッケージ バージョンに関して使用可能なメタデータは、サーバーの実装によって異なります。 パッケージ登録 BLOB の階層構造は次のとおりです。

  • インデックス: パッケージ メタデータのエントリ ポイント。同じパッケージ ID を持つソース上のすべてのパッケージによって共有されます。
  • ページ: パッケージ バージョンのグループ。 ページ内のパッケージ バージョンの数は、サーバーの実装によって定義されます。
  • リーフ: 1 つのパッケージ バージョンに固有のドキュメント。

登録インデックスの URL は予測可能であり、パッケージ ID とサービス インデックスからの登録リソースの @id 値によってクライアントが決定できます。 登録ページとリーフの URL は、登録インデックスを調べることで検出されます。

登録ページとリーフ

サーバーの実装で登録リーフを個別の登録ページ ドキュメントに格納することは厳密には必要ではありませんが、クライアント側のメモリを節約するためにこれをお勧めします。 すべての登録リーフをインデックスにインライン化したり、直ちにページ ドキュメントにリーフを格納したりしないで、サーバーの実装では、パッケージのバージョン数またはパッケージリーフの累積サイズに基づいて 2 つのアプローチを選択するヒューリスティックを定義することをお勧めします。

登録インデックスにすべてのパッケージ バージョン (リーフ) を格納すると、パッケージ メタデータをフェッチするために必要な HTTP 要求の数を節約できますが、ダウンロードする必要があるドキュメントが大きくなり、割り当てる必要があるクライアント メモリが増加することになります。 一方、サーバーの実装で登録リーフを直ちに個別のページ ドキュメントに格納する場合、必要な情報を取得するためにクライアントが実行する必要がある HTTP 要求が多くなります。

nuget.org が使用するヒューリスティックは次のとおりです。パッケージのバージョンの数が 128 以上の場合は、リーフをサイズが 64 のページに分割します。 バージョンの数が 128 未満の場合は、すべてのリーフを登録インデックスにインライン化します。 これにより、65~127 のバージョンがあるパッケージでは、インデックスに 2 つのページがありますが、両方のページがインライン化されることに注意してください。

GET {@id}/{LOWER_ID}/index.json

要求パラメーター

名前 / タイプ 必須 メモ
LOWER_ID URL string はい 小文字にしたパッケージ ID

LOWER_ID 値は、.NET の System.String.ToLowerInvariant() メソッドによって実装されるルールを使用して小文字化された目的のパッケージ ID です。

回答

応答は、次のプロパティがあるルート オブジェクトを含む JSON ドキュメントです。

名前 タイプ 必須 メモ
count 整数 (integer) はい インデックス内の登録ページの数
項目 オブジェクトの配列 はい 登録ページの配列

インデックス オブジェクトの items 配列内の各アイテムは、登録ページを表す JSON オブジェクトです。

登録ページ オブジェクト

登録インデックスにある登録ページ オブジェクトには、次のプロパティがあります。

名前 タイプ 必須 メモ
@id string はい 登録ページの URL
count 整数 (integer) はい ページ内の登録リーフの数
項目 オブジェクトの配列 いいえ 登録リーフの配列とその関連メタデータ
lower string はい ページ内の SemVer 2.0.0 バージョンの下限 (このバージョンを含む)
string いいえ 登録インデックスの URL
upper string はい ページ内の SemVer 2.0.0 バージョンの上限 (このバージョンを含む)

ページ オブジェクトの lower 境界と upper 境界は、特定のページ バージョンのメタデータが必要な場合に便利です。 これらの境界を使用して、必要な登録ページだけをフェッチできます。 バージョン文字列は、NuGet のバージョン ルールに従います。 バージョン文字列は正規化され、ビルド メタデータは含まれません。 NuGet エコシステムのすべてのバージョンと同様に、バージョン文字列の比較は、SemVer 2.0.0 のバージョンの優先順位ルールを使用して実装されます。

parent プロパティは、登録ページ オブジェクトに items プロパティがある場合にのみ表示されます。

登録ページ オブジェクトに items プロパティが存在しない場合は、@id で指定された URL を使用して、個々のパッケージ バージョンに関するメタデータをフェッチする必要があります。 items 配列は、最適化としてページ オブジェクトから除外される場合があります。 1 つのパッケージ ID のバージョン数が非常に多い場合、登録インデックス ドキュメントは、特定のバージョンまたは少数のバージョンのみを扱うクライアントの処理に対して、膨大で無駄になります。

items プロパティが存在する場合は、すべてのページ データが @id プロパティに既にインライン化されているため、items プロパティを使用する必要がないことに注意してください。

ページ オブジェクトの items 配列内の各アイテムは、登録リーフとそれに関連付けられたメタデータを表す JSON オブジェクトです。

ページ内の登録リーフ オブジェクト

登録ページにある登録リーフ オブジェクトには、次のプロパティがあります。

名前 タイプ 必須 メモ
@id string はい 登録リーフの URL
catalogEntry オブジェクト はい パッケージ メタデータを含むカタログ エントリ
packageContent string はい パッケージ内容の URL (.nupkg)

各登録リーフ オブジェクトは、1 つのパッケージ バージョンに関連付けられたデータを表します。

カタログ エントリ

登録リーフ オブジェクトの catalogEntry プロパティには、次のプロパティがあります。

名前 タイプ 必須 メモ
@id string はい このオブジェクトの生成に使用するドキュメントの URL
authors 文字列または文字列の配列 いいえ
dependencyGroups オブジェクトの配列 いいえ ターゲット フレームワーク別にグループ化されたパッケージの依存関係
非推奨 object いいえ パッケージに関連付けられた非推奨
description string いいえ
iconUrl string いいえ
ID string はい パッケージの ID
言語 string いいえ
licenseUrl string いいえ
licenseExpression string いいえ
一覧 boolean いいえ 存在しない場合は、リストに含まれていると見なす必要があります
minClientVersion string いいえ
packageContent string いいえ 親オブジェクト内の同じプロパティの複製 (レガシの理由でのみ含まれています)
projectUrl string いいえ
published string いいえ パッケージが公開されたときの ISO 8601 タイムスタンプを含む文字列
readmeUrl string いいえ パッケージ README のレンダリングされた (HTML Web ページ) ビューの URL
requireLicenseAcceptance boolean いいえ
まとめ string いいえ
tags 文字列または文字列の配列 いいえ
title string いいえ
version string はい 正規化後の完全なバージョン文字列
vulnerabilities オブジェクトの配列 いいえ パッケージのセキュリティ脆弱性

パッケージの version プロパティは、正規化後の完全なバージョン文字列です。 つまり、SemVer 2.0.0 ビルド データをここに含めることができます。

dependencyGroups プロパティは、パッケージの依存関係を表すオブジェクトの配列で、ターゲット フレームワーク別にグループ化されます。 パッケージに依存関係がない場合、dependencyGroups プロパティがないか、空の配列か、すべてのグループの dependencies プロパティが空または存在しないかです。

licenseExpression プロパティの値は、NuGet ライセンス式の構文に準拠しています。

Note

nuget.org では、パッケージがリストに登録されていない場合、published 値は 1900 年に設定されます。

パッケージの依存関係グループ

各依存関係グループ オブジェクトには、次のプロパティがあります。

名前 タイプ 必須 メモ
targetFramework string いいえ これらの依存関係が適用されるターゲット フレームワーク
依存関係 オブジェクトの配列 いいえ

targetFramework 文字列は、NuGet の .NET ライブラリ NuGet.Frameworks によって実装された形式を使用します。 targetFramework を指定しない場合、依存関係グループはすべてのターゲット フレームワークに適用されます。

dependencies プロパティはオブジェクトの配列で、それぞれが現在のパッケージについてパッケージの依存関係を表します。

パッケージの依存関係

パッケージの依存関係のそれぞれには次のプロパティがあります。

名前 タイプ 必須 メモ
id string はい パッケージの依存関係の ID
range object いいえ 依存関係について許可されるバージョン範囲
registration string いいえ この依存関係の登録インデックスの URL

range プロパティが除外されているか、空の文字列の場合、クライアントは既定のバージョン範囲 (, ) に設定する必要があります。 つまり、依存関係の任意のバージョンが許可されます。 range プロパティには * の値は許可されていません。

パッケージの非推奨

各パッケージの非推奨には次のプロパティがあります。

名前 タイプ 必須 メモ
reasons 文字列の配列 はい パッケージが非推奨になった理由
message string いいえ この非推奨に関する追加の詳細
alternatePackage object いいえ 代わりに使用することが望ましい代替候補パッケージ

reasons プロパティには少なくとも 1 つの文字列を含める必要があり、含めるのは次の表の文字列のみにします。

理由 説明
従来 パッケージはメンテナンス対象ではなくなりました
CriticalBugs パッケージにバグがあり、使用は不適切です
その他 このリストにない理由により、パッケージは非推奨です

既知のセットに含まれていない文字列が reasons プロパティに含まれている場合は、無視する必要があります。 文字列では大文字と小文字が区別されないため、legacyLegacy として扱う必要があります。 配列では順序に制限がないため、文字列は任意の順序で並べることができます。 さらに、既知のセットに含まれていない文字列のみがプロパティに含まれている場合は、"Other" 文字列のみが含まれているかのように扱う必要があります。

代替候補パッケージ

代替候補パッケージ オブジェクトには、次のプロパティがあります。

名前 タイプ 必須 メモ
id string はい 代替候補パッケージの ID
範囲 object いいえ 許可されるバージョンの範囲、または * (すべてのバージョンがる許可される場合)

脆弱性

vulnerability オブジェクトの配列。 各脆弱性には以下のプロパティがあります。

名前 タイプ 必須 メモ
advisoryUrl string はい パッケージのセキュリティ アドバイザリの場所
severity string はい アドバイザリの重大度: "0" = Low (低)、"1" = Moderate (中)、"2" = High (高)、"3" = Critical (重大)

サンプル要求

GET https://api.nuget.org/v3/registration-sample/nuget.server.core/index.json

ベース URL」セクションに記載されているように、サービス インデックスからベース URL (このサンプルの https://api.nuget.org/v3/registration-sample/) をフェッチしてください。

サンプル応答

{
  "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 配列が指定されていない場合、@id 値の HTTP GET 要求には、オブジェクトをルートとして持つ JSON ドキュメントが返ります。 オブジェクトには、次のプロパティがあります。

名前 タイプ 必須 メモ
@id string はい 登録ページの URL
count 整数 (integer) はい ページ内の登録リーフの数
項目 オブジェクトの配列 はい 登録リーフの配列とその関連メタデータ
lower string はい ページ内の SemVer 2.0.0 バージョンの下限 (このバージョンを含む)
string はい 登録インデックスの URL
upper 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」セクションに記載されているように、サービス インデックスからベース URL (このサンプルの https://api.nuget.org/v3/registration-sample/) をフェッチしてください。

サンプル応答

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

登録リーフ

登録リーフには、特定のパッケージ ID とバージョンに関する情報が含まれています。 このドキュメントでは、特定のバージョンに関するメタデータを入手できない場合があります。 パッケージ メタデータは、登録インデックスまたは登録ページ (登録インデックスを使用して検出されます) からフェッチする必要があります。

登録リーフをフェッチする URL は、登録インデックスまたは登録ページの登録リーフ オブジェクトの @id プロパティから取得されます。 ページ ドキュメントと同様に、 URL は予測可能なものではありません。登録ページ オブジェクトを使用して常に検出する必要があります。

警告

nuget.org では、たまたま、登録リーフ ドキュメントの URL にパッケージのバージョンが含まれてます。 ただし、クライアントは決してこれを前提とするべきではありません。親ドキュメントに有効なリンクがある限り、サーバーの実装で URL の形状を自由に変更できるためです。

登録リーフは、次のプロパティがあるルート オブジェクトを含む JSON ドキュメントです。

名前 タイプ 必須 メモ
@id string はい 登録リーフの URL
catalogEntry string いいえ これらのリーフを生成したカタログ エントリの URL
一覧 boolean いいえ 存在しない場合は、リストに含まれていると見なす必要があります
packageContent string いいえ パッケージ内容の URL (.nupkg)
published string いいえ パッケージが公開されたときの ISO 8601 タイムスタンプを含む文字列
registration string いいえ 登録インデックスの URL

Note

nuget.org では、パッケージがリストに登録されていない場合、published 値は 1900 年に設定されます。

サンプル要求

GET https://api.nuget.org/v3/registration-sample/nuget.versioning/4.3.0.json

ベース URL」セクションに記載されているように、サービス インデックスからベース URL (このサンプルの https://api.nuget.org/v3/registration-sample/) をフェッチしてください。

サンプル応答

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