パッケージ メタデータ
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 メソッド GET と HEAD をサポートしています。
登録 インデックス
登録リソースは、パッケージ 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 プロパティに含まれている場合は、無視する必要があります。 文字列では大文字と小文字が区別されないため、legacy を Legacy として扱う必要があります。 配列では順序に制限がないため、文字列は任意の順序で並べることができます。 さらに、既知のセットに含まれていない文字列のみがプロパティに含まれている場合は、"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"
}
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示