NuGet APINuGet API

NuGet API は、パッケージのダウンロード、メタデータのフェッチ、新しいパッケージの発行、および公式の NuGet クライアントで利用可能なその他のほとんどの操作を実行するために使用できる一連の HTTP エンドポイントです。The NuGet API is a set of HTTP endpoints that can be used to download packages, fetch metadata, publish new packages, and perform most other operations available in the official NuGet clients.

この API は、visual studio、nuget.exe、および .net CLI の nuget クライアントによってdotnet restore、などの nuget 操作 (visual studio UI での検索、およびnuget.exe pushの検索) を実行するために使用されます。This API is used by the NuGet client in Visual Studio, nuget.exe, and the .NET CLI to perform NuGet operations such as dotnet restore, search in the Visual Studio UI, and nuget.exe push.

注 nuget.org には、他のパッケージソースによって適用されない追加の要件がある場合があります。Note in some cases, nuget.org has additional requirements that are not enforced by other package sources. これらの違いについては、 Nuget.org プロトコルによって説明されています。These differences are documented by the nuget.org Protocols.

使用可能な nuget.exe バージョンの簡単な列挙とダウンロードについては、「ツールの jsonエンドポイント」を参照してください。For a simple enumeration and download of available nuget.exe versions, see the tools.json endpoint.

サービス インデックスService index

API のエントリポイントは、既知の場所にある JSON ドキュメントです。The entry point for the API is a JSON document in a well known location. このドキュメントは、サービスインデックスと呼ばれています。This document is called the service index. Nuget.org のサービスインデックスの場所はhttps://api.nuget.org/v3/index.jsonです。The location of the service index for nuget.org is https://api.nuget.org/v3/index.json.

この JSON ドキュメントには、さまざまな機能を提供し、さまざまなユースケースを満たすリソースの一覧が含まれています。This JSON document contains a list of resources which provide different functionality and fulfill different use cases.

API をサポートするクライアントは、それぞれのパッケージソースに接続する手段として、これらのサービスインデックスの URL の1つ以上を受け入れる必要があります。Clients that support the API should accept one or more of these service index URL as the means of connecting to the respective package sources.

サービスインデックスの詳細については、 API リファレンスを参照してください。For more information about the service index, see its API reference.

バージョン管理Versioning

API は、NuGet の HTTP プロトコルのバージョン3です。The API is version 3 of NuGet's HTTP protocol. このプロトコルは、"V3 API" と呼ばれることもあります。This protocol is sometimes referred to as "the V3 API". これらのリファレンスドキュメントでは、このバージョンのプロトコルを単に "API" と呼びます。These reference documents will refer to this version of the protocol simply as "the API."

サービスインデックスのスキーマバージョンは、サービスインデックスversionのプロパティによって示されます。The service index schema version is indicated by the version property in the service index. API は、バージョン文字列のメジャーバージョン番号がであること3を指定します。The API mandates that the version string has a major version number of 3. サービスインデックススキーマに重大でない変更が加えられると、バージョン文字列のマイナーバージョンが増加します。As non-breaking changes are made to the service index schema, the version string's minor version will be increased.

古いクライアント (nuget.exe 2.x など) は V3 API をサポートしていないため、ここでは説明されていない古い V2 API のみをサポートしています。Older clients (such as nuget.exe 2.x) do not support the V3 API and only support the older V2 API, which is not documented here.

NuGet V3 API は、V2 API の後継であるため、このような名前が付けられています。これは、公式の NuGet クライアントの2.x バージョンによって実装された OData ベースのプロトコルでした。The NuGet V3 API is named as such because it's the successor of the V2 API, which was the OData-based protocol implemented by the 2.x version of the official NuGet client. V3 API は、公式の NuGet クライアントの3.0 バージョンで最初にサポートされていましたが、NuGet クライアント、4.0、およびでサポートされている最新のメジャープロトコルバージョンです。The V3 API was first supported by the 3.0 version of the official NuGet client and is still the latest major protocol version supported by the NuGet client, 4.0 and on.

API は最初にリリースされた後、API に対して互換性のないプロトコルの変更が行われました。Non-breaking protocol changes have been made to the API since it was first released.

リソースとスキーマResources and schema

サービスインデックスには、さまざまなリソースが記述されています。The service index describes a variety of resources. 現在サポートされているリソースのセットは次のとおりです。The current set of supported resources are as follows:

リソース名Resource name 必須Required 説明Description
CatalogCatalog no すべてのパッケージイベントの完全な記録。Full record of all package events.
PackageBaseAddressPackageBaseAddress yes パッケージコンテンツ (. nupkg) を取得します。Get package content (.nupkg).
PackageDetailsUriTemplatePackageDetailsUriTemplate no パッケージの詳細 web ページにアクセスするための URL を作成します。Construct a URL to access a package details web page.
PackagePublishPackagePublish yes パッケージのプッシュおよび削除 (または一覧から削除) を行います。Push and delete (or unlist) packages.
RegistrationsBaseUrlRegistrationsBaseUrl yes パッケージメタデータを取得します。Get package metadata.
ReportAbuseUriTemplateReportAbuseUriTemplate no 不正使用の web ページにアクセスするための URL を作成します。Construct a URL to access a report abuse web page.
RepositorySignaturesRepositorySignatures no リポジトリの署名に使用される証明書を取得します。Get certificates used for repository signing.
SearchAutocompleteServiceSearchAutocompleteService no パッケージ Id とバージョンを部分文字列で検出します。Discover package IDs and versions by substring.
SearchQueryServiceSearchQueryService yes キーワードを使用してパッケージをフィルター処理し、検索します。Filter and search for packages by keyword.
シンボル PackagepublishSymbolPackagePublish no シンボルパッケージをプッシュします。Push symbol packages.

一般に、API リソースによって返されるすべての非バイナリデータは、JSON を使用してシリアル化されます。In general, all non-binary data returned by a API resource are serialized using JSON. サービスインデックスの各リソースによって返される応答スキーマは、そのリソースに対して個別に定義されます。The response schema returned by each resource in the service index is defined individually for that resource. 各リソースの詳細については、上記のトピックを参照してください。For more information about each resource, see the topics listed above.

今後、プロトコルが進化するにつれて、新しいプロパティが JSON 応答に追加される可能性があります。In the future, as the protocol evolves, new properties may be added to JSON responses. クライアントを将来の証明として使用する場合、実装では、応答スキーマが最終的なものであり、追加のデータを含めることができないと想定しないでください。For the client to be future-proof, the implementation should not assume that the response schema is final and cannot include extra data. 実装で認識されないすべてのプロパティを無視する必要があります。All properties that the implementation does not understand should be ignored.

注意

変換元が実装SearchAutocompleteServiceしていない場合は、オートコンプリート動作を正常に無効にする必要があります。When a source does not implement SearchAutocompleteService any autocomplete behavior should be disabled gracefully. ReportAbuseUriTemplate実装されていない場合、公式の nuget クライアントは nuget にフォールバックします ( nuget/Home # 4924によって追跡されます)。When ReportAbuseUriTemplate is not implemented, the official NuGet client falls back to nuget.org's report abuse URL (tracked by NuGet/Home#4924). 他のクライアントは、ユーザーにレポートの不正利用の URL を表示しないように選択できます。Other clients may opt to simply not show a report abuse URL to the user.

Nuget.org のドキュメントに記載されるリソースUndocumented resources on nuget.org

Nuget.org の V3 サービスインデックスには、上に記載されていないいくつかのリソースがあります。The V3 service index on nuget.org has some resources that are not documented above. リソースをドキュメント化しない理由はいくつかあります。There are a few reasons for not documenting a resource.

まず、nuget.org の実装の詳細として使用されるリソースについては説明しません。はSearchGalleryQueryService 、このカテゴリに分類されます。First, we don't document resources used as an implementation detail of nuget.org. The SearchGalleryQueryService falls into this category. NuGetGalleryは、このリソースを使用して、データベースを使用するのではなく、一部の V2 (OData) クエリを検索インデックスに委任します。NuGetGallery uses this resource to delegate some V2 (OData) queries to our search index instead of using the database. このリソースは、スケーラビリティ上の理由から導入されたものであり、外部で使用するためのものではありません。This resource was introduced for scalability reasons and is not intended for external use.

2つ目の方法として、公式クライアントの RTM バージョンには同梱されていないリソースについては説明しません。Second, we don't document resources that never shipped in an RTM version of the official client. PackageDisplayMetadataUriTemplatePackageVersionDisplayMetadataUriTemplateはこのカテゴリに分類されます。PackageDisplayMetadataUriTemplate and PackageVersionDisplayMetadataUriTemplate fall into this category.

Thirdly、V2 プロトコルと密接に関連付けられているリソースについては説明しません。このリソース自体は意図的に文書化されていません。Thirdly, we don't document resources that are tightly coupled with the V2 protocol, which itself is intentionally undocumented. リソースLegacyGalleryはこのカテゴリに分類されます。The LegacyGallery resource falls into this category. このリソースにより、V3 サービスインデックスは、対応する V2 ソース URL を指すことができます。This resource allows a V3 service index to point to a corresponding V2 source URL. このリソースは、 nuget.exe listをサポートしています。This resource supports the nuget.exe list.

リソースがここに記載されていない場合は、依存関係を取得しないことを強くお勧めします。If a resource is not documented here, we strongly recommend that you do not take a dependency on them. このようなドキュメントに記載されていないリソースの動作を削除したり、変更したりすると、予期しない方法で実装が中断される可能性があります。We may remove or change the behavior of these undocumented resources which could break your implementation in unexpected ways.

タイムスタンプTimestamps

API によって返されるすべてのタイムスタンプは UTC であるか、 ISO 8601表現を使用して指定されます。All timestamps returned by the API are UTC or are otherwise specified using ISO 8601 representation.

HTTP メソッドHTTP methods

VerbVerb 使用Use
GETGET 読み取り専用の操作を実行します。通常はデータを取得します。Performs a read-only operation, typically retrieving data.
HEAD、HEAD 対応するGET要求の応答ヘッダーをフェッチします。Fetches the response headers for the corresponding GET request.
PUTPUT 存在しないリソースを作成します。存在する場合は、リソースを更新します。Creates a resource that doesn't exist or, if it does exist, updates it. 一部のリソースでは、更新プログラムがサポートされない場合があります。Some resources may not support update.
DelDELETE リソースを削除または一覧から削除します。Deletes or unlists a resource.

HTTP 状態コードHTTP status codes

コードCode 説明Description
200200 成功し、応答の本文があります。Success, and there is a response body.
201201 成功し、リソースが作成されました。Success, and the resource was created.
202202 成功、要求は受け入れられましたが、一部の作業はまだ完了しておらず、非同期的に完了している可能性があります。Success, the request has been accepted but some work may still be incomplete and completed asynchronously.
204204 成功しましたが、応答本文がありません。Success, but there is no response body.
301301 永続的なリダイレクト。A permanent redirect.
302302 一時的なリダイレクト。A temporary redirect.
400400 URL または要求本文内のパラメーターが無効です。The parameters in the URL or in the request body aren't valid.
401401 指定された資格情報が無効です。The provided credentials are invalid.
403403 指定された資格情報を指定した場合、アクションは許可されません。The action is not allowed given the provided credentials.
404404 要求されたリソースは存在しません。The requested resource doesn't exist.
409409 要求が既存のリソースと競合しています。The request conflicts with an existing resource.
500500 サービスで予期しないエラーが発生しました。The service has encountered an unexpected error.
503503 サービスは一時的に使用できません。The service is temporarily unavailable.

API エンドポイントに対して行われた要求は、HTTPリダイレクト(301または302)を返す場合があります。GETAny GET request made to a API endpoint may return an HTTP redirect (301 or 302). クライアントは、 Locationヘッダーを観察し、後続GETのを発行することで、このようなリダイレクトを適切に処理する必要があります。Clients should gracefully handle such redirects by observing the Location header and issuing a subsequent GET. 特定のエンドポイントに関するドキュメントでは、リダイレクトが使用される場所を明示的に呼び出すことはありません。Documentation concerning specific endpoints will not explicitly call out where redirects may be used.

500レベルのステータスコードの場合、クライアントは適切な再試行メカニズムを実装できます。In the case of a 500-level status code, the client can implement a reasonable retry mechanism. 正式な NuGet クライアントは、500レベルの状態コードまたは TCP/DNS エラーが発生すると、3回再試行します。The official NuGet client retries three times when encountering any 500-level status code or TCP/DNS error.

HTTP 要求ヘッダーHTTP request headers

名前Name 説明Description
X-NuGet-ApiKeyX-NuGet-ApiKey プッシュと削除には必須です。「リソース」を参照してください。 PackagePublishRequired for push and delete, see PackagePublish resource
X-NuGet-Client-VersionX-NuGet-Client-Version 非推奨と置き換えX-NuGet-Protocol-VersionDeprecated and replaced by X-NuGet-Protocol-Version
X-NuGet-Protocol-VersionX-NuGet-Protocol-Version Nuget.org のみで必要な場合は、「 nuget.org プロトコル」を参照してください。Required in certain cases only on nuget.org, see nuget.org protocols
X-NuGet-Session-IdX-NuGet-Session-Id 省略可能Optional. NuGet クライアント v1.0 + 同じ NuGet クライアントセッションの一部である HTTP 要求を識別します。NuGet clients v4.7+ identify HTTP requests that are part of the same NuGet client session.

X-NuGet-Session-IdPackageReferenceは、の1回の復元に関連するすべての操作に対して1つの値が使用されます。The X-NuGet-Session-Id has a single value for all operations related to a single restore in PackageReference. オートコンプリートやpackages.config復元などの他のシナリオでは、コードがどのように考慮されるかによって、複数の異なるセッション ID が存在する可能性があります。For other scenarios such as autocomplete and packages.config restore there may be several different session ID's due to how the code is factored.

認証Authentication

認証は、を定義するために、パッケージソースの実装に残されます。Authentication is left up to the package source implementation to define. Nuget.org では、 PackagePublishリソースのみが特別な API キーヘッダーによる認証を必要とします。For nuget.org, only the PackagePublish resource requires authentication via a special API key header. 詳細については、「 PackagePublishリソース」を参照してください。See PackagePublish resource for details.