パッケージメタデータ

[アーティクル]
12/26/2023

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

サンプル応答

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

サンプル応答

{
  "@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 メソッド

登録インデックス

登録ページとリーフ

要求パラメーター

回答

登録ページオブジェクト

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

カタログエントリ

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

パッケージの依存関係

パッケージの非推奨

代替候補パッケージ

脆弱性

サンプル要求

サンプル応答

[登録] ページ

サンプル要求

サンプル応答

登録リーフ

サンプル要求

サンプル応答

フィードバック

その他のリソース

次の方法で共有

パッケージ メタデータ

バージョン管理

RegistrationsBaseUrl

RegistrationsBaseUrl/3.4.0

RegistrationsBaseUrl/3.6.0

ベース URL

HTTP メソッド

登録 インデックス

登録ページとリーフ

要求パラメーター

回答

登録ページ オブジェクト

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

カタログ エントリ

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

パッケージの依存関係

パッケージの非推奨

代替候補パッケージ

脆弱性

サンプル要求

サンプル応答

[登録] ページ

サンプル要求

サンプル応答

登録リーフ

サンプル要求

サンプル応答

フィードバック

その他のリソース

パッケージメタデータ

登録インデックス

登録ページオブジェクト

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

カタログエントリ