NuGet-APINuGet API

Die NuGet-API ist eine Reihe von HTTP-Endpunkten, die dazu genutzt werden kann, Pakete herunterzuladen, Metadaten abzurufen, neue Pakete zu veröffentlichen und die meisten anderen Vorgänge durchzuführen, die in den offiziellen NuGet-Clients verfügbar sind.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.

Diese API wird vom NuGet-Client in Visual Studio, nuget.exe und der .NET-CLI verwendet, um NuGet-Vorgänge auszuführen, z.B. dotnet restore, Suche in der Visual Studio-UI und 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.

Beachten Sie, dass "nuget.org" in einigen Fällen zusätzliche Anforderungen besitzt, die nicht von anderen Paketquellen erzwungen werden.Note in some cases, nuget.org has additional requirements that are not enforced by other package sources. Diese Unterschiede sind in den nuget.org-Protokollen dokumentiert.These differences are documented by the nuget.org Protocols.

Für die einfache Enumeration und zum Herunterladen der verfügbaren nuget.exe-Versionen wird der tools.json-Endpunkt verwendet.For a simple enumeration and download of available nuget.exe versions, see the tools.json endpoint.

DienstindexService index

Der Einstiegspunkt für die API ist ein JSON-Dokument an einem bekannten Speicherort.The entry point for the API is a JSON document in a well known location. Dieses Dokument heißt Dienstindex.This document is called the service index. Der Speicherort des Dienstindex für nuget.org lautet https://api.nuget.org/v3/index.json.The location of the service index for nuget.org is https://api.nuget.org/v3/index.json.

Dieses JSON-Dokument enthält eine Liste an Ressourcen, die verschiedene Funktionalitäten bereitstellen und verschiedene Anwendungsfälle erfüllen.This JSON document contains a list of resources which provide different functionality and fulfill different use cases.

Clients, die die API unterstützen, sollten eine oder mehrere dieser Dienstindex-URLs akzeptieren. Diese URLs werden benutzt, um sich mit den verschiedenen Paketquellen zu verbinden.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.

Weitere Informationen zum Dienstindex finden Sie in der zugehörigen API-Referenz.For more information about the service index, see its API reference.

VersionskontrolleVersioning

Die API ist Version 3 des NuGet HTTP-Protokolls.The API is version 3 of NuGet's HTTP protocol. Dieses Protokoll wird manchmal als "API V3" bezeichnet.This protocol is sometimes referred to as "the V3 API". Diese Referenzdokumentation nennt diese Version des Protokolls einfach "die API".These reference documents will refer to this version of the protocol simply as "the API."

Die Schemaversion des Dienstindex wird von der version-Eigenschaft im Dienstindex angegeben.The service index schema version is indicated by the version property in the service index. Die API erfordert, dass die version-Zeichenfolge die Hautpversionsnummer 3 hat.The API mandates that the version string has a major version number of 3. Wenn API-kompatible Änderungen am Schema des Dienstindex durchgeführt werden, wird die Nebenversion der version-Zeichenfolge erhöht.As non-breaking changes are made to the service index schema, the version string's minor version will be increased.

Ältere Clients (z. B. nuget.exe 2.x) unterstützen die V3-API nicht und unterstützen nur die ältere V2-API, die hier nicht dokumentiert ist.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.

Die NuGet-V3-API wird so genannt, weil sie der Nachfolger der V2-API ist. Die V2-API war ein OData-basiertes Protokoll, das durch die 2.x-Version des offiziellen NuGet-Clients implementiert wurde.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. Die V3-API wurde zuerst durch die Version 3.0 des offiziellen NuGet-Clients unterstützt und ist weiterhin die neueste MAJOR-Protokollversion, die durch den NuGet-Client unterstützt wird.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.

Geschütztes Protokoll an die API wurde geändert, da es veröffentlicht wurde.Non-breaking protocol changes have been made to the API since it was first released.

Ressourcen und schemaResources and schema

Die dienstindex beschreibt eine Reihe von Ressourcen.The service index describes a variety of resources. Der aktuelle Satz von unterstützten Ressourcen lauten wie folgt aus:The current set of supported resources are as follows:

RessourcennameResource name ErforderlichRequired BeschreibungDescription
KatalogCatalog Neinno Vollständigen Datensatz aller Ereignisse für Paket.Full record of all package events.
PackageBaseAddressPackageBaseAddress jayes Paketinhalt (NUPKG) zu erhalten.Get package content (.nupkg).
PackageDetailsUriTemplatePackageDetailsUriTemplate Neinno Erstellen Sie eine URL für den Zugriff auf eine Webseite des Paket-Details.Construct a URL to access a package details web page.
PackagePublishPackagePublish jayes Mithilfe von Push übertragen und löschen (oder aus der Liste entfernen) Pakete.Push and delete (or unlist) packages.
RegistrationsBaseUrlRegistrationsBaseUrl jayes Abrufen von Metadaten von Paketen.Get package metadata.
ReportAbuseUriTemplateReportAbuseUriTemplate Neinno Erstellen Sie eine URL für den Zugriff auf eine Webseite des Bericht-Missbrauch.Construct a URL to access a report abuse web page.
RepositorySignaturesRepositorySignatures Neinno Abrufen von Zertifikaten, die zum Signieren von Repository verwendet.Get certificates used for repository signing.
SearchAutocompleteServiceSearchAutocompleteService Neinno Entdecken Sie die Paket-IDs und Versionen von Teilzeichenfolge.Discover package IDs and versions by substring.
SearchQueryServiceSearchQueryService jayes Filtern und Pakete nach Schlüsselwort suchen.Filter and search for packages by keyword.
SymbolPackagePublishSymbolPackagePublish Neinno Push-Symbolpaketen an.Push symbol packages.

Im Allgemeinen werden alle nicht binären Daten zurückgegeben, die von einer API-Ressource mit JSON serialisiert.In general, all non-binary data returned by a API resource are serialized using JSON. Das Antwortschema von jeder Ressource im dienstindex zurückgegeben wird einzeln für diese Ressource definiert.The response schema returned by each resource in the service index is defined individually for that resource. Weitere Informationen zu jeder Ressource finden Sie unter den oben aufgeführten Themen.For more information about each resource, see the topics listed above.

Der Weiterentwicklung des Protokolls, möglicherweise in Zukunft neue Eigenschaften zu JSON-Antworten hinzugefügt werden.In the future, as the protocol evolves, new properties may be added to JSON responses. Der Client zukunftssicher ist sollte die Implementierung nicht ausgegangen, dass das Antwortschema endgültig ist und kann nicht die zusätzliche Daten enthalten.For the client to be future-proof, the implementation should not assume that the response schema is final and cannot include extra data. Alle Eigenschaften, die die Implementierung nicht interpretieren kann ignoriert werden sollen.All properties that the implementation does not understand should be ignored.

Hinweis

Wenn eine Datenquelle den SearchAutocompleteService nicht implementiert, sollte das Auto-Vervollständigungs-Verfahren kontrolliert deaktiviert werden.When a source does not implement SearchAutocompleteService any autocomplete behavior should be disabled gracefully. Wenn ReportAbuseUriTemplate nicht implementiert wird, fällt der offizielle NuGet-Client auf die "Missbrauch melden"-URL von nuget.org zurück (zu verfolgen in 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). Andere Clients können sich dazu entscheiden, einfach keine solche URL anzuzeigen.Other clients may opt to simply not show a report abuse URL to the user.

Nicht dokumentierte Ressourcen auf nuget.orgUndocumented resources on nuget.org

Dienstindex auf nuget.org V3 verfügt über einige Ressourcen, die oben nicht dokumentiert sind.The V3 service index on nuget.org has some resources that are not documented above. Es gibt einige Gründe für die Dokumentierung nicht auf einer Ressourcensatzes.There are a few reasons for not documenting a resource.

Wir dokumentieren nicht zuerst als Implementierungsdetail beibehalten von nuget.org verwendete Ressourcen. Die SearchGalleryQueryService in diese Kategorie fällt.First, we don't document resources used as an implementation detail of nuget.org. The SearchGalleryQueryService falls into this category. NuGetGallery verwendet diese Ressource, delegieren einige V2 (OData) Abfragen in unserer Search-Index mit der Datenbank.NuGetGallery uses this resource to delegate some V2 (OData) queries to our search index instead of using the database. Diese Ressource wurde aus Gründen der Skalierbarkeit eingeführt und ist nicht für die externe Verwendung vorgesehen.This resource was introduced for scalability reasons and is not intended for external use.

Zweitens, nicht wir Ressourcen dokumentieren, die in der RTM-Version von der offiziellen Client nie ausgeliefert wurden.Second, we don't document resources that never shipped in an RTM version of the official client. PackageDisplayMetadataUriTemplate und PackageVersionDisplayMetadataUriTemplate fallen in diese Kategorie.PackageDisplayMetadataUriTemplate and PackageVersionDisplayMetadataUriTemplate fall into this category.

Drittens nicht wir dokumentieren Sie Ressourcen, die eng gekoppelt mit dem V2-Protokoll, die wiederum ist absichtlich nicht dokumentiert.Thirdly, we don't document resources that are tightly coupled with the V2 protocol, which itself is intentionally undocumented. Die LegacyGallery Ressource in diese Kategorie fällt.The LegacyGallery resource falls into this category. Diese Ressource ermöglicht eine V3-dienstindex, um auf eine entsprechende V2-Quell-URL zu verweisen.This resource allows a V3 service index to point to a corresponding V2 source URL. Diese Ressource unterstützt die nuget.exe list.This resource supports the nuget.exe list.

Wenn eine Ressource hier nicht dokumentiert ist es stark wird empfohlen, dass Sie nicht über eine Abhängigkeit auf diesen führen.If a resource is not documented here, we strongly recommend that you do not take a dependency on them. Wir können entfernen oder ändern das Verhalten der folgenden nicht dokumentierten Ressourcen, die Ihre Implementierung auf unerwartete Weise unterbrechen kann.We may remove or change the behavior of these undocumented resources which could break your implementation in unexpected ways.

TimestampsTimestamps

Alle Zeitstempel, die von der API zurückgegeben werden, sind in UTC oder werden in der ISO 8601-Repräsentation angegeben.All timestamps returned by the API are UTC or are otherwise specified using ISO 8601 representation.

HTTP-MethodenHTTP methods

VerbVerb MitUse
GETGET Führt eine Nur-Lesen-Operation aus, meistens ein Abruf von Daten.Performs a read-only operation, typically retrieving data.
HEADHEAD Ruft die Antwortheader für die zusammenhängende GET-Anfrage ab.Fetches the response headers for the corresponding GET request.
PUTPUT Erstellt eine Ressource, die nicht vorhanden ist, oder aktualisiert sie, wenn sie bereits existiert.Creates a resource that doesn't exist or, if it does exist, updates it. Einige Ressourcen unterstützen Aktualisierungen vielleicht nicht.Some resources may not support update.
DELETEDELETE Löscht eine Ressource oder entfernt sie aus der Liste.Deletes or unlists a resource.

HTTP-StatuscodesHTTP status codes

CodeCode BeschreibungDescription
200200 Erfolg, es gibt einen Antworttext.Success, and there is a response body.
201201 Erfolg, die Ressource wurde erstellt.Success, and the resource was created.
202202 Erfolg, die Anfrage wurde akzeptiert, aber einige Arbeiten sind vielleicht noch unvollständig und werden asynchron durchgeführt.Success, the request has been accepted but some work may still be incomplete and completed asynchronously.
204204 Erfolg, es gibt aber keinen Antworttext.Success, but there is no response body.
301301 Eine permanente Umleitung.A permanent redirect.
302302 Eine temporäre Umleitung.A temporary redirect.
400400 Die Parameter in der URL oder im Anfragetext sind ungültig.The parameters in the URL or in the request body aren't valid.
401401 Die angegebenen Anmeldeinformationen sind ungültig.The provided credentials are invalid.
403403 Die Aktion ist mit den angegebenen Anmeldeinformationen nicht zulässig.The action is not allowed given the provided credentials.
404404 Die angeforderte Ressource ist nicht vorhanden.The requested resource doesn't exist.
409409 Die Anforderung steht in Konflikt mit einer vorhandenen Ressource.The request conflicts with an existing resource.
500500 Der Dienst hat einen unerwarteten Fehler festgestellt.The service has encountered an unexpected error.
503503 Der Dienst ist vorübergehend nicht verfügbar.The service is temporarily unavailable.

Jede GET-Anforderung an einen API-Endpunkt kann eine HTTP-Umleitung (301 oder 302) zurückgeben.Any GET request made to a API endpoint may return an HTTP redirect (301 or 302). Clients sollten diesen Umleitungen anstandslos folgen, indem sie den Location-Header berücksichtigen und eine entsprechende GET-Anforderung ausstellen.Clients should gracefully handle such redirects by observing the Location header and issuing a subsequent GET. Die Dokumentation der einzelnen Endpunkte gibt genau nicht an, wo Umleitungen benutzt werden können.Documentation concerning specific endpoints will not explicitly call out where redirects may be used.

Im Fall eines Statuscodes in der Region 500 kann der Client einen angemessenen Wiederholungsmechanismus implementieren.In the case of a 500-level status code, the client can implement a reasonable retry mechanism. Der offizielle NuGet-Client führt drei Wiederholungen durch, wenn er einen Statuscode in der Region 500 oder einen TCP-/DNS-Fehler antrifft.The official NuGet client retries three times when encountering any 500-level status code or TCP/DNS error.

HTTP-AnforderungsheaderHTTP request headers

nameName BeschreibungDescription
X-NuGet-ApiKeyX-NuGet-ApiKey Erforderlich für Push und Löschen, siehe PackagePublish -RessourceRequired for push and delete, see PackagePublish resource
X-NuGet-Client-VersionX-NuGet-Client-Version Veraltet und durch X-NuGet-Protocol-Version ersetztDeprecated and replaced by X-NuGet-Protocol-Version
X-NuGet-Protocol-VersionX-NuGet-Protocol-Version Auf nuget.org nur in bestimmten Fällen erforderlich, siehe Protokolle auf nuget.orgRequired in certain cases only on nuget.org, see nuget.org protocols
X-NuGet-Session-IdX-NuGet-Session-Id Optional.Optional. NuGet-Clients mit Version 4.7 oder höher identifizieren HTTP-Anfragen, die Teil der gleichen Client-Sitzung sind.NuGet clients v4.7+ identify HTTP requests that are part of the same NuGet client session.

Die X-NuGet-Session-Id hat einen einzigen Wert für alle Vorgänge im Zusammenhang mit einer einzigen Wiederherstellung an PackageReference.The X-NuGet-Session-Id has a single value for all operations related to a single restore in PackageReference. Für andere Szenarios wie AutoVervollständigen und packages.config Wiederherstellung möglicherweise gibt es mehrere andere Sitzung IDs aufgrund wie der Code berücksichtigt wurden.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.

AuthentifizierungAuthentication

Die Authentifizierung wird der Implementation der Paketquelle überlassen, die definiert werden soll.Authentication is left up to the package source implementation to define. Bei nuget.org erfordert nur die PackagePublish-Ressource Authentifizierung durch einen speziellen API-Schlüsselheader.For nuget.org, only the PackagePublish resource requires authentication via a special API key header. Details sind in der PackagePublish-Ressource definiert.See PackagePublish resource for details.