NuGet rozhraní APINuGet API

Rozhraní API NuGet je sada koncových bodů protokolu HTTP, které lze použít pro stáhnout balíčky, načtení metadat, publikování nové balíčky a provádět většinu dalších operací k dispozici v oficiální klienty NuGet.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.

Toto rozhraní API slouží klientem NuGet v sadě Visual Studio, nuget.exe a rozhraní příkazového řádku .NET k provádění operací NuGet, jako dotnet restore , vyhledávání v uživatelském rozhraní Visual Studio a 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.

Poznámka: v některých případech nuget.org má další požadavky, které nejsou vynucené jinými zdroji balíčku.Note in some cases, nuget.org has additional requirements that are not enforced by other package sources. Tyto rozdíly jsou popsány pomocí nuget.org protokoly.These differences are documented by the nuget.org Protocols.

Index službyService index

Vstupní bod pro rozhraní API je dokument JSON v dobře známé umístění.The entry point for the API is a JSON document in a well known location. Tento dokument je volána indexu služby.This document is called the service index. Umístění indexu služby pro nuget.org je https://api.nuget.org/v3/index.json.The location of the service index for nuget.org is https://api.nuget.org/v3/index.json.

Tento dokument JSON obsahuje seznam prostředky který poskytují různé funkce a splnění použití v odlišných situacích.This JSON document contains a list of resources which provide different functionality and fulfill different use cases.

Klienti, které podporují rozhraní API by měl přijmout jednu nebo více tyto adresy URL služby indexu jako způsobu připojení ke zdrojům příslušných balíčku.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.

Další informace o indexu služby najdete v tématu jeho referenční dokumentace rozhraní API.For more information about the service index, see its API reference.

Správa verzíVersioning

Rozhraní API je verze 3 NuGet protokolu HTTP.The API is version 3 of NuGet's HTTP protocol. Tento protokol se někdy označuje jako "V3 API."This protocol is sometimes referred to as "the V3 API." Tyto dokumenty odkaz bude odkazovat na tuto verzi protokolu jednoduše jako "rozhraní API."These reference documents will refer to this version of the protocol simply as "the API."

Verze schématu indexu služby je indikován version vlastnost v indexu služby.The service index schema version is indicated by the version property in the service index. Rozhraní API vyžaduje, aby řetězec verze má hlavní verzi počet 3.The API mandates that the version string has a major version number of 3. Při provedení změn pevné na schéma indexu služby, zvýší se podverze řetězec verze.As non-breaking changes are made to the service index schema, the version string's minor version will be increased.

Starší klienty (například nuget.exe 2.x) nepodporují rozhraní API V3 a podporují pouze starší API V2, který není zde popsán.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.

Rozhraní API V3 NuGet je jako takový název, protože je nástupcem V2 rozhraní API, která byla protokol OData na základě implementované verze 2.x oficiální klienta NuGet.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. Rozhraní API V3 byl nejprve nepodporuje verzi 3.0 oficiální klienta NuGet a je stále nejnovější hlavní protokol verze podporována klientem nástroje NuGet 4.0 a na.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.

Byly provedeny non nejnovější protokol změn do rozhraní API od prvního vydání.Non-breaking protocol changes have been made to the API since it was first release.

Prostředky a schématuResources and schema

Indexu služby popisuje různé druhy prostředků.The service index describes a variety of resources. Aktuální sadu prostředků podporované jsou následující:The current set of supported resources are as follows:

Název prostředkuResource name PožadovánoRequired PopisDescription
PackagePublish Anoyes Push a odstraňte (nebo unlist) balíčky.Push and delete (or unlist) packages.
SearchQueryService Anoyes Filtr a vyhledejte balíčků – klíčové slovo.Filter and search for packages by keyword.
RegistrationsBaseUrl Anoyes Získáte metadata balíčků.Get package metadata.
PackageBaseAddress Anoyes Získáte obsah balíčku (.nupkg).Get package content (.nupkg).
SearchAutocompleteService Neno Zjišťování ID balíčku a verze dílčí řetězec.Discover package IDs and versions by substring.
ReportAbuseUriTemplate Neno Vytvořte adresu URL pro přístup k webové stránky "oznámení zneužití".Construct a URL to access a "report abuse" web page.
Catalog Neno Úplný záznam všechny události balíčku.Full record of all package events.

Obecně platí všechny NEBINÁRNÍ data vrácená prostředkem rozhraní API se serializují pomocí JSON.In general, all non-binary data returned by a API resource are serialized using JSON. Schéma odpovědi vrácené každého prostředku v indexu služby je jednotlivě definované pro tento prostředek.The response schema returned by each resource in the service index is defined individually for that resource. Další informace o jednotlivých prostředcích najdete v tématech uvedených výše.For more information about each resource, see the topics listed above.

Poznámka

Pokud zdroj neimplementuje SearchAutocompleteService žádné chování automatického dokončování by mělo být zakázáno řádně.When a source does not implement SearchAutocompleteService any autocomplete behavior should be disabled gracefully. Když ReportAbuseUriTemplate není implementována oficiální vrátí klienta NuGet k nuget.org sestavy zneužití URL (sledovaných pomocí NuGet Domů #4924).When ReportAbuseUriTemplate is not implemented, the official NuGet client falls back to nuget.org's report abuse URL (tracked by NuGet/Home#4924). Ostatní klienti mohou zvolit, aby jednoduše adresu URL sestavy zneužití nezobrazovat uživateli.Other clients may opt to simply not show a report abuse URL to the user.

Časová razítkaTimestamps

Všechny časová razítka vrácený rozhraní API jsou UTC nebo zadávají jinak pomocí ISO 8601 reprezentace.All timestamps returned by the API are UTC or are otherwise specified using ISO 8601 representation.

Metody HTTPHTTP methods

VerbVerb PoužitíUse
GETGET Provede operaci jen pro čtení, obvykle načítání dat.Performs a read-only operation, typically retrieving data.
HEADHEAD Načte hlavičky odpovědi pro příslušné GET požadavku.Fetches the response headers for the corresponding GET request.
PUTPUT Vytvoří prostředek, který neexistuje, nebo pokud neexistuje, aktualizuje.Creates a resource that doesn't exist or, if it does exist, updates it. Některé prostředky, nemusí podporovat aktualizace.Some resources may not support update.
DELETEDELETE Odstraní nebo unlists prostředku.Deletes or unlists a resource.

Stavové kódy HTTPHTTP status codes

KódCode PopisDescription
200200 Úspěch, a že je text odpovědi.Success, and there is a response body.
201201 Úspěch a prostředek byl vytvořen.Success, and the resource was created.
202202 Úspěch, požadavek byl přijat, ale některé pracovní stále může být neúplné a dokončených asynchronně.Success, the request has been accepted but some work may still be incomplete and completed asynchronously.
204204 Úspěch, ale neexistuje žádný text odpovědi.Success, but there is no response body.
301301 Trvalé přesměrování.A permanent redirect.
302302 Dočasné přesměrování.A temporary redirect.
400400 Parametry v adrese URL nebo v textu žádosti nejsou platné.The parameters in the URL or in the request body aren't valid.
401401 Zadané přihlašovací údaje jsou neplatné.The provided credentials are invalid.
403403 Akce není povolena, danou zadané přihlašovací údaje.The action is not allowed given the provided credentials.
404404 Požadovaný prostředek neexistuje.The requested resource doesn't exist.
409409 Pro žádosti v konfliktu s existující prostředek.The request conflicts with an existing resource.
500500 Služby došlo k neočekávané chybě.The service has encountered an unexpected error.
503503 Služba je dočasně nedostupná.The service is temporarily unavailable.

Všechny GET požadavek na koncový bod rozhraní API může vrátit přesměrování HTTP (301 nebo 302).Any GET request made to a API endpoint may return an HTTP redirect (301 or 302). Klienti měli pohodlné zpracování takové přesměrování pomocí sledování Location záhlaví a vydávání následné GET.Clients should gracefully handle such redirects by observing the Location header and issueing a subsequent GET. Dokumentace týkající se specifické koncové body nebude vyvolávající explicitně kde mohou být použity přesměrování.Documentation concerning specific endpoints will not explicitly call out where redirects may be used.

V případě úrovni 500 stavový kód klienta můžete implementovat mechanismus přiměřené opakování.In the case of a 500-level status code, the client can implement a reasonable retry mechanism. Oficiální NuGet klienta opakované pokusy třikrát při zjištění žádné úrovni 500 stavový kód nebo chyba TCP a DNS.The official NuGet client retries three times when encountering any 500-level status code or TCP/DNS error.

Hlavičky požadavku HTTPHTTP request headers

NázevName PopisDescription
X-NuGet-ApiKeyX-NuGet-ApiKey Požadované pro nabízené a odstranění, najdete v části PackagePublish prostředkůRequired for push and delete, see PackagePublish resource
X-NuGet-Client-VersionX-NuGet-Client-Version Zastaralé a nahraditX-NuGet-Protocol-VersionDeprecated and replaced by X-NuGet-Protocol-Version
X-NuGet-Protocol-VersionX-NuGet-Protocol-Version V některých případech pouze v nuget.org potřeba, najdete v části nuget.org protokolyRequired in certain cases only on nuget.org, see nuget.org protocols

OvěřováníAuthentication

Ověřování je ponecháno implementace zdroje balíčku definovat.Authentication is left up to the package source implementation to define. Pro nuget.org pouze PackagePublish prostředek vyžaduje ověření prostřednictvím speciální záhlaví klíče rozhraní API.For nuget.org, only the PackagePublish resource requires authentication via a special API key header. V tématu PackagePublish prostředků podrobnosti.See PackagePublish resource for details.