検索する

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 メソッド GETHEAD をサポートしています。

パッケージを検索する

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