検索する

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