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.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 GET
Ausgabe 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 .