オートコンプリート

  • [アーティクル]

V3 API を使用して、パッケージ ID とバージョンのオートコンプリート エクスペリエンスを構築できます。 オートコンプリート クエリを行うために使用されるリソースは、サービス インデックスにある SearchAutocompleteService リソースです。

バージョン管理

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

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

SearchAutocompleteService/3.5.0

このバージョンでは、packageType クエリ パラメーターのサポートが導入され、作成者が定義したパッケージの種類によるフィルター処理が可能です。 SearchAutocompleteService へのクエリとの完全な下位互換性があります。

ベース URL

次の API のベース URL は、前述のいずれかのリソースの @type 値に関連付けられている @id プロパティの値です。 次のドキュメントでは、プレースホルダーのベース URL {@id} が使用されます。 ベース URL は、パッケージ ソース内の実装またはインフラストラクチャの変更に基づいて変化する可能性があるため、クライアント ソフトウェアによってサービス インデックスから動的にフェッチする必要があります。

HTTP メソッド

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

パッケージの ID の検索

最初のオートコンプリート API では、パッケージ ID 文字列の一部の検索がサポートされています。 これは、NuGet パッケージ ソースと統合されたユーザー インターフェイスでパッケージ先行入力機能を提供する場合に最適です。

一覧に表示されていないバージョンのみを含むパッケージは、結果に表示されません。

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

要求パラメーター

名前 / タイプ 必須 メモ
q URL string いいえ パッケージ ID と比較する文字列
skip URL integer いいえ 改ページのためにスキップする結果の数
take URL integer いいえ 改ページのために戻す結果の数
プレリリース URL boolean いいえ プレリリース パッケージを含めるかどうかを決定する true または false
semVerLevel URL string いいえ SemVer 1.0.0 バージョン文字列
packageType URL string いいえ パッケージのフィルター処理に使用するパッケージの種類 (SearchAutocompleteService/3.5.0 に追加)

オートコンプリート クエリ q は、サーバー実装によって定義された方法で解析されます。 nuget.org では、パッケージ ID トークンのプレフィックスのクエリがサポートされています。これは、キャメル ケースとシンボル文字で元のものを分割することで生成される ID の各部分です。

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

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

prerelease が指定されていない場合、プレリリース パッケージは除外されます。

semVerLevel クエリ パラメーターは、SemVer 2.0.0 パッケージにオプトインするために使用されます。 このクエリ パラメーターを除外すると、SemVer 1.0.0 と互換性のあるバージョンのパッケージ ID だけが返されます (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 ドキュメントです。

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

名前 タイプ 必須 メモ
totalHits integer はい skip および take を無視した一致の総数
data 文字列の配列 はい 要求と一致するパッケージ ID

サンプル要求

GET https://search-sample.nuget.org/autocomplete?q=storage&prerelease=true

「ベース URL」セクションに記載されているように、サービス インデックスからベース URL (このサンプルの https://search-sample.nuget.org/autocomplete) をフェッチしてください。

サンプル応答

{
  "totalHits": 571,
  "data": [
    "WindowsAzure.Storage",
    "Storage.Net",
    "CK.Storage",
    "NCL.Storage",
    "DK.Storage",
    "Nine.Storage.Test",
    "Touch.Storage.Aws",
    "StorageAPIClient",
    "StorageAccess",
    "Storage.Net.Microsoft.Azure.Storage",
    "UnofficialAzure.StorageClient",
    "StorageAccess12",
    "AWSSDK.StorageGateway",
    "StorageExtensions",
    "Cloud.Storage",
    "lighthouse.storage",
    "ZU.Storage.Redis",
    "Magicodes.Storage",
    "Masticore.Storage",
    "hq.storage"
  ]
}

パッケージのバージョンの列挙

以前の API を使用してパッケージ ID が検出された後、クライアントはオートコンプリート API を使用して、指定されたパッケージ ID のパッケージ バージョンを列挙できます。

一覧に含まれていないパッケージ バージョンは結果に表示されません。

GET {@id}?id={ID}&prerelease={PRERELEASE}&semVerLevel={SEMVERLEVEL}

要求パラメーター

名前 / タイプ 必須 メモ
ID URL string はい バージョンをフェッチするパッケージ ID
プレリリース URL boolean いいえ プレリリース パッケージを含めるかどうかを決定する true または false
semVerLevel URL string いいえ SemVer 2.0.0 バージョン文字列

prerelease が指定されていない場合、プレリリース パッケージは除外されます。

semVerLevel クエリ パラメーターは、SemVer 2.0.0 パッケージにオプトインするために使用されます。 このクエリ パラメーターを除外すると、SemVer 1.0.0 バージョンだけが返されます。 semVerLevel=2.0.0 を指定すると、SemVer 1.0.0 と SemVer 2.0.0 の両方のバージョンが返されます。 詳しくは、nuget.org のための SemVer 2.0.0 サポートを参照してください。

回答

応答は、指定されたパッケージ ID のすべてのパッケージ バージョンを含む JSON ドキュメントであり、指定されたクエリ パラメーターによってフィルター処理されます。

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

名前 タイプ 必須 メモ
data 文字列の配列 はい 要求と一致するパッケージのバージョン

クエリ文字列に semVerLevel=2.0.0 が指定された場合、data 配列内のパッケージ バージョンには SemVer 2.0.0 ビルド メタデータ (たとえば 1.0.0+metadata) が含まれることがあります。

要求のサンプル

GET https://api-v2v3search-0.nuget.org/autocomplete?id=nuget.protocol&prerelease=true

サンプル応答

{
  "data": [
    "4.3.0-preview3-4168",
    "4.3.0-preview4",
    "4.3.0-rtm-4324",
    "4.3.0",
    "4.4.0-preview3-4475",
    "4.4.0"
  ]
}