NuGet-Server-API

  • Artikel

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.exe und der .NET CLI verwendet, um NuGet-Vorgänge auszuführen, z dotnet restore. B. die Suche in der Visual Studio-Benutzeroberfläche und nuget.exe push.

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 Protokolle dokumentiert.

Eine einfache Aufzählung und einen Download der verfügbaren Nuget.exe-Versionen finden Sie im tools.json-Endpunkt .

Wenn Sie ein NuGet-Paket-Repository implementieren, lesen Sie auch das Implementierungshandbuch 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 Dienstindex bezeichnet. Der Dienstindexspeicherort für nuget.org ist https://api.nuget.org/v3/index.json.

Dieses JSON-Dokument enthält eine Liste von 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 finden Sie in der Referenz zur API zur Indexerstellung.

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 version Eigenschaft im Dienstindex angegeben. Die API verlangt, dass die Versionszeichenfolge die Hauptversionsnummer 3 aufweist. Da am Dienstindexschema keine Breaking Changes 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.

Ressourcenprotokollschema

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).
RegistrationsBaseUrl ja Paketmetadaten abrufen.
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 nach Paketen nach Schlüsselwort (keyword).
SymbolPackagePublish Nein Push-Symbolpakete.
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.

Hinweis

Wenn eine Quelle kein AutoVervollständigen-Verhalten implementiertSearchAutocompleteService, sollte ordnungsgemäß deaktiviert werden. Wenn ReportAbuseUriTemplate sie nicht implementiert ist, greift der offizielle NuGet-Client auf die Missbrauchs-URL 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. Der SearchGalleryQueryService Fall 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 in diese Kategorie fallen.

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, empfehlen wir dringend, 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 Einsetzen
GET Führt einen schreibgeschützten Vorgang aus, der in der Regel Daten abruft.
HEAD Ruft die Antwortheader für die entsprechende GET-Anforderung ab.
PUT Erstellt eine Ressource, die nicht vorhanden ist oder, falls vorhanden, aktualisiert sie. Einige Ressourcen unterstützen möglicherweise kein Update.
DELETE Löscht oder hebt die Liste einer Ressource auf.

HTTP-Statuscodes (Azure Cognitive Search)

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 Permanente Umleitung.
302 Temporäre Umleitung.
400 Die Parameter in der URL oder im Anforderungstext sind ungültig.
401 Die bereitgestellten Anmeldeinformationen sind falsch.
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 Der Server hat einen unerwarteten Fehler erkannt.
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äß verarbeiten, indem Sie den Location Header beobachten und eine nachfolgende GETAusgabe ausgeben. 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, siehe PackagePublish Ressource
X-NuGet-Client-Version Veraltet und ersetzt durch X-NuGet-Protocol-Version
X-NuGet-Protokollversion Erforderlich in bestimmten Fällen nur für nuget.org, siehe nuget.org Protokolle
X-NuGet-Session-ID Optional. NuGet-Clients v4.7+ identifizieren HTTP-Anforderungen, die Teil derselben NuGet-Clientsitzung sind.

Der X-NuGet-Session-Id Wert weist einen einzelnen Wert für alle Vorgänge auf, die sich auf eine einzelne Wiederherstellung beziehen PackageReference. Für andere Szenarien wie AutoVervollständigen und packages.config Wiederherstellen gibt es möglicherweise mehrere verschiedene Sitzungs-IDs, 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. Details finden Sie PackagePublish in der Ressource .