次の方法で共有

NuGet Server API

  • [アーティクル]

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

この API は、Visual Studio の NuGet クライアント、nuget.exe、および .NET CLI によって、dotnet restore、Visual 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 が最初にリリースされてから、破壊的でないプロトコル変更が API に対して行われました。

リソースとスキーマ

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

リソース名 必須 形容
カタログ いいえ すべてのパッケージ イベントの完全なレコード。
PackageBaseAddress の はい パッケージ コンテンツ (.nupkg) を取得します。
PackageDetailsUriTemplate の いいえ パッケージの詳細 Web ページにアクセスするための URL を作成します。
PackagePublish はい パッケージをプッシュおよび削除 (またはリストから削除) します。
ReadmeUriTemplate いいえ パッケージの README にアクセスするための URL を作成します。
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 の文書化されていないリソース

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

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

次に、RTM バージョンの公式クライアントに出荷されなかったリソースは文書化しません。 PackageDisplayMetadataUriTemplate と PackageVersionDisplayMetadataUriTemplate は、このカテゴリに分類されます。

3 つ目は、V2 プロトコルと密接に結び付いているリソースを文書化しません。これは、それ自体が意図的に文書化されていません。 LegacyGallery リソースはこのカテゴリに分類されます。 このリソースを使用すると、V3 サービス インデックスが対応する V2 ソース URL を指すことができます。 このリソースは、nuget.exe listをサポートしています。

リソースがここに記載されていない場合は、依存しないことを強 強く推奨。 これらの文書化されていないリソースの動作を削除または変更する場合があり、予期しない方法で実装が中断される可能性があります。

タイムスタンプ

API によって返されるすべてのタイムスタンプは UTC であるか、ISO 8601 表現 使用して指定されます。

HTTP メソッド

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

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での単一の復元に関連するすべての操作に対して 1 つの値があります。 オートコンプリートや packages.config 復元などのその他のシナリオでは、コードの要素化方法により、いくつかの異なるセッション ID が存在する可能性があります。

認証

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