検索する
V3 API を使用して、パッケージ ソースで使用可能なパッケージを検索できます。 検索を行うために使用されるリソースは、サービス インデックスにある SearchQueryService リソースです。
バージョン管理
次の @type の値が使用されます。
| @type 値 | メモ |
|---|---|
| SearchQueryService | 初期リリース |
| SearchQueryService/3.0.0-beta | SearchQueryService の別名 |
| SearchQueryService/3.0.0-rc | SearchQueryService の別名 |
| SearchQueryService/3.5.0 | packageType クエリ パラメーターのサポートを含む |
SearchQueryService/3.5.0
このバージョンでは、packageType クエリ パラメーターと packageTypes 応答プロパティのサポートが導入され、作成者が定義したパッケージの種類によるフィルター処理が可能です。 SearchQueryService へのクエリとの完全な下位互換性があります。
ベース URL
次の API のベース URL は、前述のリソース の @type 値に関連付けられている @id プロパティの値です。 次のドキュメントでは、プレースホルダーのベース URL {@id} が使用されます。 ベース URL は、パッケージ ソース内の実装またはインフラストラクチャの変更に基づいて変化する可能性があるため、クライアント ソフトウェアによってサービス インデックスから動的にフェッチする必要があります。
HTTP メソッド
登録リソースにあるすべての URL は、HTTP メソッド GET と HEAD をサポートしています。
パッケージを検索する
検索 API を使用すると、クライアントは、指定された検索クエリに一致するパッケージのページをクエリできます。 検索クエリの解釈 (検索用語のトークン化など) はサーバーの実装によって決まりますが、一般的な期待は、一般的には、検索クエリはパッケージ ID、タイトル、説明、タグの照合に使用されることが期待されます。 他のパッケージ メタデータ フィールドも考慮される場合があります。
リストにないパッケージが検索結果に表示されることはありません。
GET {@id}?q={QUERY}&skip={SKIP}&take={TAKE}&prerelease={PRERELEASE}&semVerLevel={SEMVERLEVEL}&packageType={PACKAGETYPE}
要求パラメーター
| 名前 | / | タイプ | 必須 | メモ |
|---|---|---|---|---|
| q | URL | string | いいえ | パッケージのフィルター処理に使用する検索語 |
| skip | URL | integer | いいえ | 改ページのためにスキップする結果の数 |
| take | URL | integer | いいえ | 改ページのために戻す結果の数 |
| プレリリース | URL | boolean | いいえ | プレリリース パッケージを含めるかどうかを決定する true または false |
| semVerLevel | URL | string | いいえ | SemVer 1.0.0 バージョン文字列 |
| packageType | URL | string | いいえ | パッケージのフィルター処理に使用するパッケージの種類 (SearchQueryService/3.5.0 に追加) |
検索クエリ q は、サーバー実装によって定義された方法で解析されます。 nuget.org は、さまざまなフィールドに対する基本的なフィルター処理をサポートしています。 q が指定されていない場合は、skip と take によって課される境界内ですべてのパッケージを返す必要があります。 これにより、NuGet Visual Studio エクスペリエンスの [参照] タブが有効になります。
skip パラメーターの既定値は 0 です。
take パラメーターは、0 より大きい整数にする必要があります。 サーバーの実装では、最大値が課される場合があります。
Note
nuget.org は、skip パラメーターを 3,000 に、take パラメーターを 1,000 に制限します。
prerelease が指定されていない場合、プレリリース パッケージは除外されます。
semVerLevel クエリ パラメーターは、SemVer 2.0.0 パッケージにオプトインするために使用されます。
このクエリ パラメーターが除外された場合、SemVer 1.0.0 と互換性のあるバージョンを持つパッケージのみが返されます (4 つの整数部分を含むバージョン文字列など、標準の NuGet バージョン管理に関する注意点があります)。
semVerLevel=2.0.0 を指定すると、SemVer 1.0.0 と SemVer 2.0.0 の両方と互換性のあるパッケージが返されます。 詳しくは、nuget.org のための SemVer 2.0.0 サポートを参照してください。
packageType パラメーターを使用すると、検索結果をさらにフィルター処理し、パッケージの種類名に一致するパッケージの種類を少なくとも 1 つ含むパッケージに限定されます。
指定されたパッケージの種類が、パッケージの種類ドキュメントで定義されている有効なパッケージの種類ではない場合は、空の結果が返されます。
指定されたパッケージの種類が空の場合、フィルターは適用されません。 つまり、packageType パラメーターに値を渡さない場合、パラメーターが渡されていない場合と同様に動作します。
回答
応答は、最大 take 件の検索結果を含む JSON ドキュメントです。 検索結果はパッケージ ID ごとにグループ化されます。
ルートの JSON オブジェクトには、以下のプロパティがあります。
| 名前 | タイプ | 必須 | メモ |
|---|---|---|---|
| totalHits | integer | はい | skip および take を無視した一致の総数 |
| data | オブジェクトの配列 | はい | 要求に一致した検索結果 |
検索結果
data 配列の各項目は、同じパッケージ ID を共有するパッケージ バージョンのグループで構成される JSON オブジェクトです。
オブジェクトには、次のプロパティがあります。
| 名前 | タイプ | 必須 | メモ |
|---|---|---|---|
| id | string | はい | 一致したパッケージの ID |
| version | string | はい | パッケージの完全な SemVer 2.0.0 バージョン文字列 (ビルド メタデータを含む可能性があります) |
| description | string | いいえ | |
| versions | オブジェクトの配列 | はい | prerelease パラメーターに一致するパッケージのすべてのバージョン |
| authors | 文字列または文字列の配列 | いいえ | |
| iconUrl | string | いいえ | |
| licenseUrl | string | いいえ | |
| owners | 文字列または文字列の配列 | いいえ | |
| projectUrl | string | いいえ | |
| registration | string | いいえ | 関連付けられている 登録インデックスへの絶対 URL |
| summary | string | いいえ | |
| tags | 文字列または文字列の配列 | いいえ | |
| title | string | いいえ | |
| totalDownloads | integer | いいえ | この値は、versions 配列内のダウンロードの合計によって推論できます |
| verified | boolean | いいえ | パッケージ が検証されているかどうかを示す JSON ブール値 |
| packageTypes | オブジェクトの配列 | はい | パッケージ作成者によって定義されたパッケージの種類 (SearchQueryService/3.5.0 に追加) |
nuget.org では、検証済みパッケージは、予約 ID プレフィックスと一致し、予約済みプレフィックスの所有者のいずれかが所有するパッケージ ID を持つパッケージです。 詳細については、ID プレフィックス予約に関するドキュメントを参照してください。
検索結果オブジェクトに含まれるメタデータは、最新のパッケージ バージョンから取得されます。 versions 配列の各アイテムは、次のプロパティを持つ JSON オブジェクトです。
| 名前 | タイプ | 必須 | メモ |
|---|---|---|---|
| @id | string | はい | 関連する 登録リーフ への絶対URL |
| version | string | はい | パッケージの完全な SemVer 2.0.0 バージョン文字列 (ビルド メタデータを含む可能性があります) |
| ダウンロード | integer | はい | この特定のパッケージ バージョンのダウンロード数 |
packageTypes 配列は常に少なくとも 1 つの項目で構成されます。 特定のパッケージ ID のパッケージの種類は、他の検索パラメーターに関してパッケージの最新バージョンで定義されているパッケージの種類と見なされます。 packageTypes 配列の各アイテムは、次のプロパティを持つ JSON オブジェクトです。
| 名前 | タイプ | 必須 | メモ |
|---|---|---|---|
| name | string | はい | パッケージの種類の名前です。 |
サンプル要求
GET https://search-sample.nuget.org/query?q=NuGet.Versioning&prerelease=false&semVerLevel=2.0.0
「ベース URL」セクションに記載されているように、サービス インデックスからベース URL (このサンプルの https://search-sample.nuget.org/query) をフェッチしてください。
サンプル応答
{
"totalHits": 2,
"data": [
{
"registration": "https://api.nuget.org/v3/registration-sample/nuget.versioning/index.json",
"id": "NuGet.Versioning",
"version": "4.4.0",
"description": "NuGet's implementation of Semantic Versioning.",
"summary": "",
"title": "NuGet.Versioning",
"licenseUrl": "https://raw.githubusercontent.com/NuGet/NuGet.Client/dev/LICENSE.txt",
"tags": [ "semver", "semantic", "versioning" ],
"authors": [ "NuGet" ],
"totalDownloads": 141896,
"verified": true,
"packageTypes": [
{
"name": "Dependency"
}
],
"versions": [
{
"version": "3.3.0",
"downloads": 50343,
"@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/3.3.0.json"
},
{
"version": "3.4.3",
"downloads": 27932,
"@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/3.4.3.json"
},
{
"version": "4.0.0",
"downloads": 63004,
"@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/4.0.0.json"
},
{
"version": "4.4.0",
"downloads": 617,
"@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/4.4.0.json"
}
]
},
{
"@id": "https://api.nuget.org/v3/registration-sample/nerdbank.gitversioning/index.json",
"@type": "Package",
"registration": "https://api.nuget.org/v3/registration-sample/nerdbank.gitversioning/index.json",
"id": "Nerdbank.GitVersioning",
"version": "2.0.41",
"description": "Stamps your assemblies with semver 2.0 compliant git commit specific version information and provides NuGet versioning information as well.",
"summary": "Stamps your assemblies with semver 2.0 compliant git commit specific version information and provides NuGet versioning information as well.",
"title": "Nerdbank.GitVersioning",
"licenseUrl": "https://raw.githubusercontent.com/AArnott/Nerdbank.GitVersioning/ed547462f7/LICENSE.txt",
"projectUrl": "http://github.com/aarnott/Nerdbank.GitVersioning",
"tags": [ "git", "commit", "versioning", "version", "assemblyinfo" ],
"authors": [ "Andrew Arnott" ],
"totalDownloads": 11906,
"verified": false,
"versions": [
{
"version": "1.6.35",
"downloads": 10229,
"@id": "https://api.nuget.org/v3/registration-sample/nerdbank.gitversioning/1.6.35.json"
},
{
"version": "2.0.41",
"downloads": 1677,
"@id": "https://api.nuget.org/v3/registration-sample/nerdbank.gitversioning/2.0.41.json"
}
]
}
]
}
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示