検索

[アーティクル]
04/08/2022

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

バージョン管理

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

@type 値	メモ
SearchQueryService	初期リリース
SearchQueryService/3.0.0-ベータ	`SearchQueryService` の別名
SearchQueryService/3.0.0	`SearchQueryService` の別名
SearchQueryService/3.5.0	`packageType` クエリパラメーターのサポートを含む

SearchQueryService/3.5.0

このバージョンでは、クエリパラメーターと packageTypes 応答プロパティのサポートが導入されており、作成者が定義したパッケージの packageType 種類でフィルター処理できます。 SearchQueryService へのクエリとの完全な下位互換性があります。

ベース URL

次の API のベース URL は、前述のいずれかのリソース @type 値に関連付けられているプロパティの @id 値です。次のドキュメントでは、プレースホルダーのベース URL {@id} が使用されます。

HTTP メソッド

登録リソースにあるすべての URL は、HTTP メソッド GET と HEAD をサポートしています。

パッケージの検索

検索 API を使用すると、クライアントは、指定された検索クエリに一致するパッケージのページを照会できます。検索クエリの解釈 (検索用語のトークン化など) はサーバーの実装によって決定されますが、一般的には、検索クエリがパッケージ Id、タイトル、説明、タグの照合に使用されることを想定しています。その他のパッケージメタデータフィールドも考慮することができます。

一覧にないパッケージは、検索結果に表示されません。

GET {@id}?q={QUERY}&skip={SKIP}&take={TAKE}&prerelease={PRERELEASE}&semVerLevel={SEMVERLEVEL}&packageType={PACKAGETYPE}

要求パラメーター

名前	/	Type	必須	Notes
q	URL	string	no	パッケージをフィルター処理するために使用する検索語句
skip	[URL]	integer	no	改ページのためにスキップする結果の数
take	[URL]	integer	no	改ページのために戻す結果の数
プレリリース	[URL]	boolean	no	プレリリースパッケージを含めるかどうかを決定する `true` または `false`
semVerLevel	URL	string	no	SemVer 1.0.0 バージョン文字列
packageType	URL	string	no	パッケージのフィルター処理に使用するパッケージの種類 (`SearchQueryService/3.5.0` に追加)

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

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

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

注意

nuget.org は、 skip パラメーターを 3000 take に、パラメーターを1000に制限します。

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 パラメーターに値を渡さないと、パラメーターが渡されなかったかのように動作します。

Response

応答は、最大検索結果を take 含む JSON ドキュメントです。検索結果はパッケージ ID 別にグループ化されます。

ルートの JSON オブジェクトには、以下のプロパティがあります。

名前	型	必須	Notes
totalHits	integer	yes	`skip` および `take` を無視した一致の総数
data	オブジェクトの配列	はい	要求に一致する検索結果

Search result

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

Name	型	必須	Notes
id	string	yes	一致したパッケージの ID
version	string	yes	パッケージの完全な SemVer 2.0.0 バージョン文字列 (ビルドメタデータを含む可能性があります)
description	string	no
versions	オブジェクトの配列	はい	パラメーターに `prerelease` 一致するパッケージのすべてのバージョン
作成者	文字列または文字列の配列	Ｘ
iconUrl	string	no
licenseUrl	string	no
owners	文字列または文字列の配列	Ｘ
projectUrl	string	no
登録	string	no	関連付けられている登録インデックスの絶対 URL
まとめ	string	no
tags	文字列または文字列の配列	Ｘ
title	string	no
totalDownloads	integer	no	この値は、 `versions` 配列内のダウンロードの合計によって推論できます。
れ	boolean	no	パッケージが検証されているかどうかを示す JSON ブール値
packageTypes	オブジェクトの配列	はい	パッケージ作成者によって定義されたパッケージの種類 (で `SearchQueryService/3.5.0` 追加)

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

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

Name	型	必須	メモ
@id	string	yes	関連付けられている登録リーフへの絶対 URL
version	string	yes	パッケージの完全な SemVer 2.0.0 バージョン文字列 (ビルドメタデータを含む可能性があります)
ダウンロード	integer	yes	この特定のパッケージバージョンのダウンロード回数

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

Name	型	必須	メモ
name	string	yes	パッケージの種類の名前。

要求のサンプル

GET https://azuresearch-usnc.nuget.org/query?q=NuGet.Versioning&prerelease=false&semVerLevel=2.0.0

応答のサンプル

{
  "totalHits": 2,
  "data": [
    {
      "registration": "https://api.nuget.org/v3/registration3/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/registration3/nuget.versioning/3.3.0.json"
        },
        {
          "version": "3.4.3",
          "downloads": 27932,
          "@id": "https://api.nuget.org/v3/registration3/nuget.versioning/3.4.3.json"
        },
        {
          "version": "4.0.0",
          "downloads": 63004,
          "@id": "https://api.nuget.org/v3/registration3/nuget.versioning/4.0.0.json"
        },
        {
          "version": "4.4.0",
          "downloads": 617,
          "@id": "https://api.nuget.org/v3/registration3/nuget.versioning/4.4.0.json"
        }
      ]
    },
    {
      "@id": "https://api.nuget.org/v3/registration3/nerdbank.gitversioning/index.json",
      "@type": "Package",
      "registration": "https://api.nuget.org/v3/registration3/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/registration3/nerdbank.gitversioning/1.6.35.json"
        },
        {
          "version": "2.0.41",
          "downloads": 1677,
          "@id": "https://api.nuget.org/v3/registration3/nerdbank.gitversioning/2.0.41.json"
        }
      ]
    }
  ]
}