Serverové rozhraní API pro NuGet

Rozhraní API serveru NuGet je sada koncových bodů HTTP, které lze použít ke stahování balíčků, načítání metadat, publikování nových balíčků a provádění většiny dalších operací dostupných v oficiálních klientech NuGet.

Toto rozhraní API používá klient NuGet v sadě Visual Studio, nuget.exe a rozhraní příkazového řádku .NET k provádění operací NuGet, jako dotnet restoreje vyhledávání v uživatelském rozhraní sady Visual Studio a nuget.exe push.

V některých případech nuget.org má další požadavky, které jiné zdroje balíčků nevynucují. Tyto rozdíly jsou zdokumentované protokoly nuget.org.

Jednoduchý výčet a stažení dostupných verzí nuget.exe najdete v koncovém bodu tools.json .

Pokud implementujete úložiště balíčků NuGet, projděte si také průvodce implementací pro další požadavky a doporučení.

Index služby

Vstupním bodem pro rozhraní API je dokument JSON ve známém umístění. Tento dokument se nazývá index služby. Umístění indexu služby pro nuget.org je https://api.nuget.org/v3/index.json.

Tento dokument JSON obsahuje seznam prostředků , které poskytují různé funkce a splňují různé případy použití.

Klienti, kteří podporují rozhraní API, by měli jako prostředek připojení k příslušným zdrojům balíčků přijmout jednu nebo více z těchto adres URL indexu služby.

Další informace o indexu služby najdete v referenčních informacích k rozhraní API.

Vytváření verzí

Rozhraní API je verze 3 protokolu HTTP NuGet. Tento protokol se někdy označuje jako "rozhraní API V3". Tyto referenční dokumenty budou odkazovat na tuto verzi protokolu jednoduše jako "rozhraní API".

Verze schématu indexu služby je označena version vlastností v indexu služby. Rozhraní API vyžaduje, aby řetězec verze má číslo 3hlavní verze . Vzhledem k tomu, že ve schématu indexu služby se neprovedou změny způsobující chybu, zvýší se podverze řetězce verze.

Starší klienti (například nuget.exe 2.x) nepodporují rozhraní API V3 a podporují pouze starší rozhraní API V2, které zde není zdokumentované.

Rozhraní API NuGet v3 je pojmenované jako takové, protože se jedná o následníka rozhraní API v2, což byl protokol založený na OData implementovaný verzí 2.x oficiálního klienta NuGet. Rozhraní API v3 bylo poprvé podporováno verzí 3.0 oficiálního klienta NuGet a je stále nejnovější hlavní verzí protokolu podporovanou klientem NuGet, 4.0 a zapnutým.

Změny protokolu, které nejsou zásadní, byly provedeny v rozhraní API od prvního vydání.

Prostředky a schéma

Index služby popisuje celou řadu prostředků. Aktuální sada podporovaných prostředků je následující:

Název prostředku	Požadováno	Popis
Katalog	ne	Úplný záznam všech událostí balíčku.
PackageBaseAddress	ano	Získání obsahu balíčku (.nupkg)
PackageDetailsUriTemplate	ne	Vytvořte adresu URL pro přístup k webové stránce podrobností balíčku.
PackagePublish	ano	Nasdílení a odstranění (nebo zrušení seznamu) balíčků
RegistrationsBaseUrl	ano	Získejte metadata balíčku.
ReportAbuseUriTemplate	ne	Vytvořte adresu URL pro přístup k webové stránce zneužití sestavy.
RepositorySignatures	ne	Získejte certifikáty používané k podepisování úložiště.
SearchAutocompleteService	ne	Zjišťování ID a verzí balíčků pomocí podřetězece
SearchQueryService	ano	Filtrování a vyhledávání balíčků podle klíčových slov
SymbolPackagePublish	ne	Nasdílení balíčků symbolů
Informace o ohrožení zabezpečení	ne	Balíčky se známými ohroženími zabezpečení

Obecně platí, že všechna nebinární data vrácená prostředkem rozhraní API se serializují pomocí json. Schéma odpovědí vrácené jednotlivými prostředky v indexu služby je definováno jednotlivě pro daný prostředek. Další informace o jednotlivých prostředcích najdete v tématech uvedených výše.

V budoucnu se s vývojem protokolu můžou do odpovědí JSON přidat nové vlastnosti. Aby klient byl v budoucnu důkazem, implementace by neměla předpokládat, že schéma odpovědi je konečné a nemůže obsahovat další data. Všechny vlastnosti, kterým implementace nerozumí, by se měly ignorovat.

Poznámka:

Pokud zdroj neimplementuje SearchAutocompleteService žádné chování automatického dokončování, mělo by být řádně zakázáno. Pokud ReportAbuseUriTemplate není implementovaný, oficiální klient NuGet se vrátí zpět na adresu URL zneužití sestavy nuget.org (sledovaný NuGet /Home#4924). Jiní klienti se můžou rozhodnout, že se uživateli jednoduše nezobrazí adresa URL pro zneužití sestavy.

Nezdokumentované prostředky na nuget.org

Index služby V3 na nuget.org obsahuje některé prostředky, které nejsou popsané výše. Existuje několik důvodů, proč prostředek nezdokumentovat.

Nejprve nezadokumentujeme prostředky používané jako podrobnosti implementace nuget.org. Tato SearchGalleryQueryService kategorie spadá do této kategorie. NuGetGallery používá tento prostředek k delegování některých dotazů V2 (OData) na náš vyhledávací index místo použití databáze. Tento prostředek byl zaveden z důvodů škálovatelnosti a není určen pro externí použití.

Za druhé, nezadokumentujeme prostředky, které se nikdy nedoručily ve verzi RTM oficiálního klienta. PackageDisplayMetadataUriTemplate a PackageVersionDisplayMetadataUriTemplate spadají do této kategorie.

Za třetí, nezadokumentujeme prostředky, které jsou úzce propojené s protokolem V2, který sám je záměrně nezdokumentován. Zdroj LegacyGallery spadá do této kategorie. Tento prostředek umožňuje indexu služby V3 odkazovat na odpovídající zdrojovou adresu URL V2. Tento prostředek podporuje nuget.exe list.

Pokud zde není zdokumentován prostředek, důrazně doporučujeme, abyste na nich nezávisli. Můžeme odebrat nebo změnit chování těchto nezdokumentovaných prostředků, které by mohly narušit vaši implementaci neočekávanými způsoby.

Časová razítka

Všechna časová razítka vrácená rozhraním API jsou UTC nebo jsou jinak určena pomocí reprezentace ISO 8601 .

Metody HTTP

Verb (Příkaz)	Používání
GET	Provádí operaci jen pro čtení, která obvykle načítá data.
HEAD	Načte hlavičky odpovědi pro odpovídající GET požadavek.
PUT	Vytvoří prostředek, který neexistuje nebo pokud existuje, aktualizuje ho. Některé prostředky nemusí podporovat aktualizaci.
DELETE	Odstraní nebo zruší seznam prostředků.

Stavové kódy HTTP

Kód	Popis
200	Úspěch a existuje tělo odpovědi.
201	Úspěch a prostředek byl vytvořen.
202	Žádost byla přijata úspěšně, ale některé práce můžou být stále neúplné a dokončené asynchronně.
204	Úspěch, ale neexistuje žádný text odpovědi.
301	Trvalé přesměrování.
302	Dočasné přesměrování.
400	Parametry v adrese URL nebo v textu požadavku nejsou platné.
401	Zadané přihlašovací údaje jsou neplatné.
403	Akce není povolena pro zadané přihlašovací údaje.
404	Požadovaný prostředek neexistuje.
409	Požadavek je v konfliktu s existujícím prostředkem.
500	Služba zjistila neočekávanou chybu.
503	Služba je dočasně nedostupná.

Jakýkoli GET požadavek na koncový bod rozhraní API může vrátit přesměrování HTTP (301 nebo 302). Klienti by měli řádně zpracovávat takové přesměrování sledováním Location hlavičky a vydáním následného GET. Dokumentace týkající se konkrétních koncových bodů explicitně nevyvolá, kde se můžou používat přesměrování.

V případě stavového kódu na úrovni 500 může klient implementovat rozumný mechanismus opakování. Oficiální klient NuGet třikrát opakuje pokusy při výskytu jakéhokoli stavového kódu na úrovni 500 nebo chyby TCP/DNS.

Hlavičky požadavků HTTP

Název	Popis
X-NuGet-ApiKey	Požadováno pro nabízení a odstranění, viz PackagePublish prostředek
X-NuGet-Client-Version	Zastaralé a nahrazenéX-NuGet-Protocol-Version
Verze X-NuGet-Protocol	Vyžadováno pouze v některých případech pouze u nuget.org, viz protokoly nuget.org
X-NuGet-Session-ID	Volitelné. Klienti NuGet verze 4.7+ identifikují požadavky HTTP, které jsou součástí stejné relace klienta NuGet.

Má X-NuGet-Session-Id jednu hodnotu pro všechny operace související s jedním obnovením v PackageReference. V jiných scénářích, jako je automatické dokončování a packages.config obnovení, může existovat několik různých ID relace kvůli tomu, jak je kód faktorován.

Ověřování

Ověřování je ponecháno až na implementaci zdroje balíčku, která se definuje. Pro nuget.org vyžaduje ověřování pouze PackagePublish prostředek prostřednictvím speciální hlavičky klíče rozhraní API. Podrobnosti najdete PackagePublish v zdroji .