検索する

V3 API を使用して、パッケージ ソースで使用可能なパッケージを検索できます。 検索を行うために使用されるリソースは、サービス インデックスにある SearchQueryService リソースです。

バージョン管理

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

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 は、サーバー実装によって定義された方法で解析されます。 nuget.org は、さまざまなフィールドに対する基本的なフィルター処理をサポートしています。 q が指定されていない場合は、skip と take によって課される境界内ですべてのパッケージを返す必要があります。 これにより、NuGet Visual Studio エクスペリエンスの [参照] タブが有効になります。

skip パラメーターの既定値は 0 です。

take パラメーターは、0 より大きい整数にする必要があります。 サーバーの実装では、最大値が課される場合があります。

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 オブジェクトには、以下のプロパティがあります。

検索結果

data 配列の各項目は、同じパッケージ ID を共有するパッケージ バージョンのグループで構成される JSON オブジェクトです。 オブジェクトには、次のプロパティがあります。

nuget.org では、検証済みパッケージは、予約 ID プレフィックスと一致し、予約済みプレフィックスの所有者のいずれかが所有するパッケージ ID を持つパッケージです。 詳細については、ID プレフィックス予約に関するドキュメントを参照してください。

検索結果オブジェクトに含まれるメタデータは、最新のパッケージ バージョンから取得されます。 versions 配列の各アイテムは、次のプロパティを持つ JSON オブジェクトです。

packageTypes 配列は常に少なくとも 1 つの項目で構成されます。 特定のパッケージ ID のパッケージの種類は、他の検索パラメーターに関してパッケージの最新バージョンで定義されているパッケージの種類と見なされます。 packageTypes 配列の各アイテムは、次のプロパティを持つ JSON オブジェクトです。

サンプル要求

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