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 .