NuGet Server-API
Die NuGet Server-API ist eine Reihe von HTTP-Endpunkten, die verwendet werden können, um Pakete herunterzuladen, Metadaten abzurufen, neue Pakete zu veröffentlichen und die meisten anderen Vorgänge auszuführen, die in den offiziellen NuGet-Clients verfügbar sind.
Diese API wird vom NuGet-Client in Visual Studio, nuget.exeund der .NET CLI zum Ausführen von NuGet-Vorgängen wie dotnet restore, Suchen in der Visual Studio-Benutzeroberfläche und nuget.exe pushverwendet.
Beachten Sie in einigen Fällen, dass nuget.org zusätzliche Anforderungen hat, die nicht von anderen Paketquellen erzwungen werden. Diese Unterschiede werden durch die nuget.org Protokolledokumentiert.
Eine einfache Aufzählung und das Herunterladen verfügbarer nuget.exe Versionen finden Sie im tools.json Endpunkt.
Wenn Sie ein NuGet-Paket-Repository implementieren, lesen Sie auch den Implementierungsleitfaden für zusätzliche Anforderungen und Empfehlungen.
Dienstindex
Der Einstiegspunkt für die API ist ein JSON-Dokument an einem bekannten Speicherort. Dieses Dokument wird als Dienstindexbezeichnet. Der Speicherort des Dienstindex für nuget.org ist https://api.nuget.org/v3/index.json.
Dieses JSON-Dokument enthält eine Liste der Ressourcen, die unterschiedliche Funktionen bereitstellen und unterschiedliche Anwendungsfälle erfüllen.
Clients, die die API unterstützen, sollten eine oder mehrere dieser Dienstindex-URL als Verbindung mit den jeweiligen Paketquellen akzeptieren.
Weitere Informationen zum Dienstindex finden Sie der API-Referenz.
Versionsverwaltung
Die API ist Version 3 des HTTP-Protokolls von NuGet. Dieses Protokoll wird manchmal als "die V3-API" bezeichnet. Diese Referenzdokumente beziehen sich einfach auf diese Version des Protokolls als "die API".
Die Dienstindexschemaversion wird durch die eigenschaft version im Dienstindex angegeben. Die API schreibt vor, dass die Versionszeichenfolge eine Hauptversionsnummer von 3hat. Wenn änderungen am Dienstindexschema vorgenommen werden, wird die Nebenversion der Versionszeichenfolge erhöht.
Ä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.
Die NuGet V3-API wird als solche bezeichnet, da sie der Nachfolger der V2-API ist, das das OData-basierte Protokoll war, das von der 2.x-Version des offiziellen NuGet-Clients implementiert wurde. Die V3-API wurde zuerst von der 3.0-Version des offiziellen NuGet-Clients unterstützt und ist weiterhin die neueste Hauptprotokollversion, die vom NuGet-Client, 4.0 und weiter unterstützt wird.
Seit der ersten Veröffentlichung wurden ungebrochene Protokolländerungen an der API vorgenommen.
Ressourcen und Schema
Der Dienstindex beschreibt eine Vielzahl von Ressourcen. Die aktuellen unterstützten Ressourcen sind wie folgt:
| Ressourcenname | Erforderlich | Beschreibung |
|---|---|---|
| Katalog- | Nein | Vollständige Aufzeichnung aller Paketereignisse. |
| PackageBaseAddress- | ja | Abrufen von Paketinhalten (.nupkg). |
| PackageDetailsUriTemplate- | Nein | Erstellen Sie eine URL für den Zugriff auf eine Paketdetails-Webseite. |
| PackagePublish- | ja | Push- und Löschpakete (oder Aufheben der Liste). |
| ReadmeUriTemplate- | Nein | Erstellen Sie eine URL für den Zugriff auf die README-Datei eines Pakets. |
| RegistrationsBaseUrl | ja | Abrufen von Paketmetadaten. |
| ReportAbuseUriTemplate- | Nein | Erstellen Sie eine URL für den Zugriff auf eine Berichtsmissbrauchswebseite. |
| RepositorySignatures | Nein | Abrufen von Zertifikaten, die für die Repositorysignierung verwendet werden. |
| SearchAutocompleteService- | Nein | Entdecken Sie Paket-IDs und -Versionen nach Teilzeichenfolge. |
| SearchQueryService- | ja | Filtern und suchen Sie nach Paketen nach Schlüsselwort. |
| SymbolPackagePublish- | Nein | Pushsymbolpakete. |
| VulnerabilityInfo- | Nein | Pakete mit bekannten Sicherheitsrisiken. |
Im Allgemeinen werden alle nicht binären Daten, die von einer API-Ressource zurückgegeben werden, mithilfe von JSON serialisiert. Das antwortschema, das von jeder Ressource im Dienstindex zurückgegeben wird, wird für diese Ressource einzeln definiert. Weitere Informationen zu den einzelnen Ressourcen finden Sie in den oben aufgeführten Themen.
Wenn sich das Protokoll weiterentwickelt, können zukünftig neue Eigenschaften zu JSON-Antworten hinzugefügt werden. Damit der Client zukunftssicher ist, sollte die Implementierung nicht davon ausgehen, dass das Antwortschema abgeschlossen ist und keine zusätzlichen Daten enthalten kann. Alle Eigenschaften, die die Implementierung nicht versteht, sollten ignoriert werden.
Anmerkung
Wenn eine Quelle SearchAutocompleteService kein AutoVervollständigen-Verhalten implementiert, sollte dies ordnungsgemäß deaktiviert werden. Wenn ReportAbuseUriTemplate nicht implementiert ist, greift der offizielle NuGet-Client auf die Url des Missbrauchsberichts von nuget.org zurück (nachverfolgt von NuGet/Home#4924). Andere Clients können sich dafür entscheiden, dem Benutzer einfach keine Berichtsmissbrauchs-URL anzuzeigen.
Nicht dokumentierte Ressourcen für nuget.org
Der V3-Dienstindex für nuget.org enthält einige Ressourcen, die oben nicht dokumentiert sind. Es gibt einige Gründe, eine Ressource nicht zu dokumentieren.
Zunächst dokumentieren wir keine Ressourcen, die als Implementierungsdetails von nuget.org verwendet werden. Die SearchGalleryQueryService fällt in diese Kategorie.
NuGetGallery verwendet diese Ressource, um einige V2 (OData)-Abfragen an unseren Suchindex zu delegieren, anstatt die Datenbank zu verwenden. Diese Ressource wurde aus Skalierbarkeitsgründen eingeführt und ist nicht für die externe Verwendung vorgesehen.
Zweitens dokumentieren wir keine Ressourcen, die nie in einer RTM-Version des offiziellen Kunden ausgeliefert wurden.
PackageDisplayMetadataUriTemplate und PackageVersionDisplayMetadataUriTemplate fallen in diese Kategorie.
Drittens dokumentieren wir keine Ressourcen, die eng mit dem V2-Protokoll verbunden sind, das absichtlich nicht dokumentiert ist. Die LegacyGallery Ressource fällt in diese Kategorie. Diese Ressource ermöglicht es einem V3-Dienstindex, auf eine entsprechende V2-Quell-URL zu verweisen. Diese Ressource unterstützt die nuget.exe list.
Wenn eine Ressource hier nicht dokumentiert ist, wir dringend empfehlen, dass Sie keine Abhängigkeit davon nehmen. Wir können das Verhalten dieser nicht dokumentierten Ressourcen entfernen oder ändern, die Ihre Implementierung auf unerwartete Weise unterbrechen könnten.
Zeitstempel
Alle von der API zurückgegebenen Zeitstempel sind UTC oder werden anderweitig mit ISO 8601 Darstellung angegeben.
HTTP-Methoden
| Verb | Gebrauchen |
|---|---|
| ERHALTEN | Führt einen schreibgeschützten Vorgang aus, der in der Regel Daten abruft. |
| KOPF | Ruft die Antwortheader für die entsprechende GET Anforderung ab. |
| STELLEN | Erstellt eine Ressource, die nicht vorhanden ist oder, falls vorhanden, aktualisiert sie. Einige Ressourcen unterstützen möglicherweise kein Update. |
| LÖSCHEN | Löscht oder hebt die Liste einer Ressource auf. |
HTTP-Statuscodes
| Code | Beschreibung |
|---|---|
| 200 | Erfolg, und es gibt einen Antworttext. |
| 201 | Erfolg und Die Ressource wurde erstellt. |
| 202 | Erfolg, die Anforderung wurde akzeptiert, aber einige Arbeiten sind möglicherweise noch unvollständig und asynchron abgeschlossen. |
| 204 | Erfolg, aber es gibt keinen Antworttext. |
| 301 | Eine dauerhafte Umleitung. |
| 302 | Eine temporäre Umleitung. |
| 400 | Die Parameter in der URL oder im Anforderungstext sind ungültig. |
| 401 | Die bereitgestellten Anmeldeinformationen sind ungültig. |
| 403 | Die Aktion ist aufgrund der bereitgestellten Anmeldeinformationen nicht zulässig. |
| 404 | Die angeforderte Ressource ist nicht vorhanden. |
| 409 | Die Anforderung ist mit einer vorhandenen Ressource in Konflikt. |
| 500 | Beim Dienst ist ein unerwarteter Fehler aufgetreten. |
| 503 | Der Dienst ist vorübergehend nicht verfügbar. |
Jede GET Anforderung an einen API-Endpunkt kann eine HTTP-Umleitung (301 oder 302) zurückgeben. Clients sollten solche Umleitungen ordnungsgemäß behandeln, indem Sie den Location Header beobachten und eine nachfolgende GETausgeben. Dokumentation zu bestimmten Endpunkten wird nicht explizit aufgerufen, wo Umleitungen verwendet werden können.
Bei einem Statuscode der 500-Ebene kann der Client einen angemessenen Wiederholungsmechanismus implementieren. Der offizielle NuGet-Client wiederholt dreimal, wenn ein Statuscode auf 500 Ebenen oder ein TCP/DNS-Fehler auftritt.
HTTP-Anforderungsheader
| Name | Beschreibung |
|---|---|
| X-NuGet-ApiKey | Erforderlich für Push- und Löschvorgang finden Sie unter PackagePublish Ressourcen- |
| X-NuGet-Client-Version |
veraltete und ersetzt durch X-NuGet-Protocol-Version |
| X-NuGet-Protocol-Version | In bestimmten Fällen nur für nuget.org erforderlich, lesen Sie nuget.org Protokolle |
| X-NuGet-Session-Id | Optional. NuGet-Clients v4.7+ identifizieren HTTP-Anforderungen, die Teil derselben NuGet-Clientsitzung sind. |
Die X-NuGet-Session-Id weist einen einzelnen Wert für alle Vorgänge im Zusammenhang mit einer einzelnen Wiederherstellung in PackageReferenceauf. Für andere Szenarien wie AutoVervollständigen und packages.config Wiederherstellen kann es mehrere verschiedene Sitzungs-IDs geben, da der Code faktoriert wird.
Authentifizierung
Die Authentifizierung bleibt bis zur Paketquellimplementierung, die definiert werden soll. Für nuget.org erfordert nur die PackagePublish Ressource eine Authentifizierung über einen speziellen API-Schlüsselheader. Weitere Informationen finden Sie unter PackagePublish Ressourcen-.