Rozhraní API NugetuNuGet API

NuGet rozhraní API je sada koncových bodů HTTP, které je možné stáhnout balíčky, načíst metadata, publikovat nové balíčky a provádějí 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 používá klienta 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í služby 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.

Všimněte si, v některých případech nuget.org má další požadavky, které nejsou vynucené z jiných zdrojů balíčků.Note in some cases, nuget.org has additional requirements that are not enforced by other package sources. Tyto rozdíly jsou popsány pomocí protokoly nuget.org.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 index služby.This document is called the service index. Umístění index 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 splnit různé případy použití.This JSON document contains a list of resources which provide different functionality and fulfill different use cases.

Klienti podporující rozhraní API by měl přijmout jednu nebo více tyto adresy URL indexu služby jako způsob připojení ke zdrojům odpovídající balíček.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 index služby najdete v tématu reference k rozhraní API.For more information about the service index, see its API reference.

Správa verzíVersioning

Rozhraní API je verze 3 protokolu HTTP Nugetu.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 referenční dokumenty 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 index služby.The service index schema version is indicated by the version property in the service index. Rozhraní API Určuje, zda má řetězec verze číslo hlavní verze 3.The API mandates that the version string has a major version number of 3. Jak nevýznamných změn schématu indexu služby, zvýší se verze řetězec podverze.As non-breaking changes are made to the service index schema, the version string's minor version will be increased.

Starší klienti (jako je například nuget.exe 2.x) nepodporují rozhraní API V3 a podporují pouze starší API V2, které není zdokumentované tady.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 jmenuje jako takové, protože jedná se o nástupce rozhraní API V2, která byla protokolu založených na protokolu OData 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 je nejprve podporován ve verzi 3.0 oficiální klienta NuGet a stále verze nejnovější hlavní protokol není podporovaný od klienta NuGet 4.0 a.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.

Bez konce protokolu změnám rozhraní API od jeho prvním vydání.Non-breaking protocol changes have been made to the API since it was first release.

Prostředky a schématuResources and schema

Index 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 delete (nebo vyjmutí ze seznamu) balíčky.Push and delete (or unlist) packages.
SearchQueryService Anoyes Můžete filtrovat a hledat balíčky – klíčové slovo.Filter and search for packages by keyword.
RegistrationsBaseUrl Anoyes Získáte metadata balíčku.Get package metadata.
PackageBaseAddress Anoyes Získáte balíček obsahu (.nupkg).Get package content (.nupkg).
SearchAutocompleteService Neno Zjistíte ID balíčku a verze pomocí dílčí řetězec.Discover package IDs and versions by substring.
ReportAbuseUriTemplate Neno Vytvořte adresu URL pro přístup k webové stránky "ohlásit nevhodné chování".Construct a URL to access a "report abuse" web page.
RepositorySignatures Neno Získání certifikátů pro podpis úložiště.Get certificates used for repository signing.
Catalog Neno Celý záznam všech událostí balíčku.Full record of all package events.

Obecně platí všechny NEBINÁRNÍ data vrácená rozhraním API prostředku se serializují pomocí formátu 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 samostatně definované pro daný 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

Když zdroj neimplementuje SearchAutocompleteService všechna chování automatického dokončování by mělo být zakázáno bez výpadku.When a source does not implement SearchAutocompleteService any autocomplete behavior should be disabled gracefully. Když ReportAbuseUriTemplate neimplementována oficiální spadá klienta NuGet zpět na nuget.org ohlásit nevhodné chování adresy URL (sledované podle Domů NuGet #4924).When ReportAbuseUriTemplate is not implemented, the official NuGet client falls back to nuget.org's report abuse URL (tracked by NuGet/Home#4924). Jiní klienti mohou zvolit, aby jednoduše adresa URL pro sestavu 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ím API jsou UTC nebo jinak zvoleny pomocí ISO 8601 reprezentace.All timestamps returned by the API are UTC or are otherwise specified using ISO 8601 representation.

Metody HTTPHTTP methods

PříkazVerb PoužitíUse
ZÍSKATGET Provádí operaci jen pro čtení, obvykle načítají se data.Performs a read-only operation, typically retrieving data.
HLAVNÍHEAD Načte hlavičky odpovědi pro odpovídající GET požadavku.Fetches the response headers for the corresponding GET request.
PUTPUT Vytvoří prostředek, který neexistuje, nebo pokud existuje, aktualizuje ji.Creates a resource that doesn't exist or, if it does exist, updates it. Některé prostředky nemusí podporovat aktualizaci.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 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žadavku byla přijata ale úkony mohou být nekompletní 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á pověření jsou neplatná.The provided credentials are invalid.
403403 Akce není povolen zadaný zadaných přihlašovacích údajů.The action is not allowed given the provided credentials.
404404 Požadovaný prostředek neexistuje.The requested resource doesn't exist.
409409 V požadavku je 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.

Žádné GET požadavku 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 bez výpadku zpracovávat takové přesměrování pozorováním Location záhlaví a vydání následných GET.Clients should gracefully handle such redirects by observing the Location header and issuing a subsequent GET. Dokumentace týkající se konkrétní koncové body nebude volat 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í libovolné úrovni 500 stavový kód nebo došlo k chybě TCP/DNS.The official NuGet client retries three times when encountering any 500-level status code or TCP/DNS error.

Hlavičky žádosti HTTPHTTP request headers

NázevName PopisDescription
X-NuGet-ApiKeyX-NuGet-ApiKey Vyžadováno pro push a delete, naleznete v tématu PackagePublish prostředkůRequired for push and delete, see PackagePublish resource
X-NuGet klienta VersionX-NuGet-Client-Version Zastaralé a nahradit X-NuGet-Protocol-VersionDeprecated and replaced by X-NuGet-Protocol-Version
X-NuGet-Protocol-VersionX-NuGet-Protocol-Version Vyžaduje se v některých případech pouze na nuget.org, naleznete v tématu protokoly nuget.orgRequired in certain cases only on nuget.org, see nuget.org protocols
X-NuGet-Session-IdX-NuGet-Session-Id Volitelné.Optional. NuGet klientů v4.7 + identifikovat požadavky HTTP, které jsou součástí stejné relace klienta NuGet.NuGet clients v4.7+ identify HTTP requests that are part of the same NuGet client session. Pro PackageReference existuje operace obnovení je jedno id relace, pro jiné scénáře, jako je automatické dokončování, a packages.config obnovení může být několik různých id relace z důvodu jak dostaneme kód.For PackageReference restore operations there is a single session id, for other scenarios such as auto complete, and packages.config restore there may be several different session id's due to how the code is factored.

OvěřováníAuthentication

Ověřování zůstane až po implementaci zdroje balíčku k definování.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. Zobrazit PackagePublish prostředků podrobnosti.See PackagePublish resource for details.