NuGet サーバー API

  • [アーティクル]

NuGet Server API は、パッケージのダウンロード、メタデータのフェッチ、新しいパッケージの発行、公式の NuGet クライアントで使用できるその他のほとんどの操作の実行に使用できる一連の HTTP エンドポイントです。

この API は、Visual Studio の NuGet クライアント、nuget.exe、および .NET CLI によって使用され、dotnet restore、Studio UI での検索、nuget.exe push などの NuGet 操作を実行します。

場合によっては、nuget.org には、他のパッケージ ソースでは適用されない追加要件があることに注意してください。 これらの違いについては、nuget.org プロトコルで文書化されています。

使用可能な nuget.exe バージョンのシンプルな列挙とダウンロードについては、tools.json エンドポイントを参照してください。

NuGet パッケージ リポジトリを実装する場合は、追加要件と推奨事項に関する実装ガイドも参照してください。

サービス インデックス

API のエントリ ポイントは、既知の場所にある JSON ドキュメントです。 このドキュメントは、サービス インデックスと呼ばれます。 nuget.org のサービス インデックスの場所は https://api.nuget.org/v3/index.json です。

この JSON ドキュメントには、さまざまな機能を提供し、さまざまなユース ケースを満たすリソースの一覧が含まれています。

API をサポートするクライアントは、それぞれのパッケージ ソースに接続する手段として、これらのサービス インデックス URL の 1 つ以上を受け入れる必要があります。

サービス インデックスの詳細については、その API リファレンス に関する記事をご覧ください。

バージョン管理

API は、NuGet の HTTP プロトコルのバージョン 3 です。 このプロトコルは、"V3 API" と呼ばれることもあります。 これらのリファレンス ドキュメントでは、このバージョンのプロトコルを単に "API" と呼びます。

サービス インデックス スキーマのバージョンは、サービス インデックスの version プロパティによって示されます。 API は、バージョン文字列のメジャー バージョン番号が 3 であることを指定します。 非破壊的変更がサービス インデックス スキーマに加えられると、バージョン文字列のマイナー バージョンが増加します。

古いクライアント (nuget.exe 2.x など) は V3 API をサポートせず、ここに文書化されていない古い V2 API のみをサポートします。

NuGet V3 API は、公式の NuGet クライアントの 2.x バージョンで実装された OData ベースのプロトコルである V2 API の後継であることから、そのように名前が付けられています。 V3 API は、公式の NuGet クライアントの 3.0 バージョンで最初にサポートされ、現在も NuGet クライアント (4.0 以降) でサポートされている最新のメジャー プロトコル バージョンです。

最初にリリースされて以来、API にはプロトコルの非破壊的変更が加えられています。

リソースとスキーマ

サービス インデックスには、さまざまなリソースが記述されています。 現在サポートされているリソースのセットは次のとおりです。

リソース名 必須 説明
Catalog いいえ すべてのパッケージ イベントの完全なレコード。
PackageBaseAddress はい パッケージ コンテンツ (.nupkg) を取得します。
PackageDetailsUriTemplate いいえ パッケージの詳細の Web ページにアクセスするための URL を構築します。
PackagePublish はい パッケージをプッシュおよび削除 (または一覧から削除) します。
RegistrationsBaseUrl はい パッケージ メタデータを取得します。
ReportAbuseUriTemplate いいえ 不正使用レポートの Web ページにアクセスするための URL を構築します。
RepositorySignatures いいえ リポジトリの署名に使用する証明書を取得します。
SearchAutocompleteService いいえ パッケージ ID とバージョンを部分文字列で検出します。
SearchQueryService はい キーワードでパッケージをフィルター処理して検索します。
SymbolPackagePublish いいえ シンボル パッケージをプッシュします。
VulnerabilityInfo いいえ 既知の脆弱性を持つパッケージ。

一般に、API リソースが返すすべての非バイナリデータは、JSON を使用してシリアル化されます。 サービス インデックス内の各リソースが返す応答スキーマは、そのリソースに対して個別に定義されます。 各リソースの詳細については、上記のトピックを参照してください。

今後、プロトコルの進化に伴い、JSON 応答に新しいプロパティが追加される可能性があります。 クライアントが将来の技術に対応できるようにするために、実装では応答スキーマが最終的なものであり、追加のデータを含めることができないという想定はしません。 実装で認識されないすべてのプロパティは無視する必要があります。

Note

ソースが SearchAutocompleteService を実装していない場合は、オートコンプリート動作を適切に無効にする必要があります。 ReportAbuseUriTemplate が実装されていない場合、公式の NuGet クライアントは nuget.org の不正使用レポートの URL (NuGet/Home#4924 によって追跡) にフォールバックします。 他のクライアントでは、単に不正使用レポートの URL をユーザーに表示しないことを選択できます。

nuget.org の文書化されていないリソース

nuget.org の V3 サービス インデックスには、上記で文書化されていないリソースがいくつかあります。 リソースを文書化しない理由がいくつかあります。

第 1 に、nuget.org の実装の詳細として使用されるリソースは文書化されません。SearchGalleryQueryService がこれに該当します。 NuGetGallery では、一部の V2 (OData) クエリを検索インデックスに委任する場合に、データベースではなく、このリソースが使用されます。 このリソースはスケーラビリティの理由から導入されており、外部で使用するためのものではありません。

第 2 に、RTM バージョンの公式クライアントに出荷されなかったリソースは文書化されません。 PackageDisplayMetadataUriTemplate と PackageVersionDisplayMetadataUriTemplate がこれに該当します。

第 3 に、V2 プロトコルと密接に結合されているリソースは文書化されません (V2 プロトコル自体が意図的に文書化されていない)。 LegacyGallery リソースがこれに該当します。 このリソースを使用すると、V3 サービス インデックスが対応する V2 ソース URL をポイントできるようになります。 このリソースでは nuget.exe list がサポートされています。

ここに文書化されていないリソースには依存しないことを強くお勧めします。 文書化されていないリソースの動作は削除または変更される場合があり、それによって予期しない形で実装が破壊される可能性があります。

タイムスタンプ

API が返すタイムスタンプにはすべて UTC が使用されていますが、ISO 8601 表現を使用して指定される場合もあります。

HTTP メソッド

食器 用途
GET 読み取り専用操作 (通常はデータの取得) を実行します。
HEAD 対応する GET 要求の応答ヘッダーをフェッチします。
PUT 存在しないリソースを作成します。リソースが存在する場合は更新します。 一部のリソースでは更新がサポートされない場合があります。
DELETE リソースを削除または一覧から削除します。

HTTP 状態コード

コード 説明
200 正常に終了し、応答本文が返されています。
201 正常に終了し、リソースが作成されました。
202 正常に終了し、要求は受け入れられましたが、一部の作業はまだ不完全で、非同期で完了する可能性があります。
204 正常に終了しましたが、応答本文は返されていません。
301 永続的なリダイレクトです。
302 一時的なリダイレクトです。
400 URL または要求本文のパラメーターが無効です。
401 指定した認証情報が無効です。
403 指定した認証情報では、このアクションは許可されません。
404 要求されたリソースは存在しません。
409 この要求は既存のリソースと競合しています。
500 サービスで予期しないエラーが発生しました。
503 サービスは一時的に利用できません。

API エンドポイントに対して行われた GET 要求は、HTTP リダイレクト (301 または 302) を返す場合があります。 クライアントは、Location ヘッダーを監視し、その後 GET を発行することにより、このようなリダイレクトを適切に処理する必要があります。 特定のエンドポイントに関するドキュメントでは、リダイレクトが使用される場所が明示的に示されていません。

500 レベルの状態コードの場合、クライアントは適切な再試行メカニズムを実装できます。 公式の NuGet クライアントは、500 レベルの状態コードまたは TCP/DNS エラーが発生したときに 3 回再試行します。

HTTP 要求ヘッダー

名前 説明
X-NuGet-ApiKey プッシュと削除に必要です (「PackagePublish リソース」を参照)
X-NuGet-Client-Version 非推奨となり X-NuGet-Protocol-Version に置き換えられました
X-NuGet-Protocol-Version nuget.org の特定のケースでのみ必要です (「nuget.org プロトコル」を参照)
X-NuGet-Session-Id 省略可。 NuGet クライアント v4.7 以降は、同じ NuGet クライアント セッションの一部である HTTP 要求を識別します。

X-NuGet-Session-Id には、PackageReference の単一の復元に関連するすべての操作に対して単一の値が使用されます。 オートコンプリートや packages.config 復元などの他のシナリオでは、コードのファクタリング方法が原因で、いくつかの異なるセッション ID が存在する場合があります。

認証

認証は、定義するパッケージ ソースの実装によって決まります。 nuget.org の場合、特別な API キー ヘッダーによる認証が必要なのは PackagePublish リソースだけです。 詳細については、「PackagePublish リソース 」を参照してください。