Číst v angličtině

Sdílet prostřednictvím


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.

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 .