Rozhraní API serveru 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.exea rozhraní příkazového řádku .NET k provádění operací NuGet, jako je dotnet restore, 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í 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 tématu referenčnírozhraní API .
Správa 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 vlastností version v indexu služby. Rozhraní API vyžaduje, aby řetězec verze má číslo hlavní verze 3. 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 různé prostředky. Aktuální sada podporovaných prostředků je následující:
| Název prostředku | Požadovaný | Popis |
|---|---|---|
| katalogu | 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ů |
| ReadmeUriTemplate | Ne | Vytvořte adresu URL pro přístup k souboru README balíčku. |
| 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ů |
| VulnerabilityInfo | 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 jakékoli chování automatického dokončování by mělo být řádně zakázáno. Pokud ReportAbuseUriTemplate není implementováno, oficiální klient NuGet se vrátí na adresu URL zneužití sestavy nuget.org (sleduje 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. SearchGalleryQueryService spadá do této kategorie.
NuGetGallery tento prostředek používá k delegování některých dotazů V2 (OData) do našeho vyhledávacího indexu namí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í zdokumentovaný 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 zadána pomocí reprezentace ISO 8601.
Metody HTTP
| Sloveso | Používat |
|---|---|
| DOSTAT | Provádí operaci jen pro čtení, která obvykle načítá data. |
| HLAVA | Načte hlavičky odpovědi pro odpovídající požadavek GET. |
| DÁT | Vytvoří prostředek, který neexistuje nebo pokud existuje, aktualizuje ho. Některé prostředky nemusí podporovat aktualizaci. |
| VYMAZAT | 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 hlavičky Location 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
| Jméno | Popis |
|---|---|
| X-NuGet-ApiKey | Požadováno pro nabízení a odstranění, viz prostředkůPackagePublish |
| X-NuGet–Client-Version |
zastaralé a nahrazené X-NuGet-Protocol-Version |
| X-NuGet–Protocol-Version | Povinné pouze v některých případech pouze na nuget.org, viz nuget.org protokoly |
| 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 má 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 být kvůli faktoru kódu několik různých ID relace.
Autentizace
Ověřování je ponecháno až na implementaci zdroje balíčku, která se definuje. Pro nuget.org vyžaduje ověřování pouze prostředek PackagePublish prostřednictvím speciální hlavičky klíče rozhraní API. Podrobnosti najdete v PackagePublish prostředku.