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 応答に新しいプロパティが追加される可能性があります。 クライアントが将来の技術に対応できるようにするために、実装では応答スキーマが最終的なものであり、追加のデータを含めることができないという想定はしません。 実装で認識されないすべてのプロパティは無視する必要があります。
注意
ソースが SearchAutocompleteService
を実装していない場合は、オートコンプリート動作を適切に無効にする必要があります。 ReportAbuseUriTemplate
が実装されていない場合、公式の NuGet クライアントは nuget.org の不正使用レポートの URL (NuGet/Home#4924 によって追跡) にフォールバックします。 他のクライアントでは、単に不正使用レポートの URL をユーザーに表示しないことを選択できます。
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 表現を使用して指定される場合もあります。
食器 | 用途 |
---|---|
GET | 読み取り専用操作 (通常はデータの取得) を実行します。 |
HEAD | 対応する GET 要求の応答ヘッダーをフェッチします。 |
PUT | 存在しないリソースを作成します。リソースが存在する場合は更新します。 一部のリソースでは更新がサポートされない場合があります。 |
DELETE | リソースを削除または一覧から削除します。 |
コード | 説明 |
---|---|
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 回再試行します。
名前 | 説明 |
---|---|
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
リソース 」を参照してください。