NuGet Server API
A NuGet Server API HTTP-végpontok készlete, amelyek felhasználhatók csomagok letöltésére, metaadatok lekérésére, új csomagok közzétételére és a hivatalos NuGet-ügyfelekben elérhető legtöbb egyéb művelet végrehajtására.
Ezt az API-t használja a NuGet-ügyfél a Visual Studióban, a nuget.exeés a .NET CLI-vel NuGet-műveletek, például dotnet restore, keresés a Visual Studio felhasználói felületén és nuget.exe push.
Vegye figyelembe, hogy bizonyos esetekben a nuget.org olyan további követelményekkel rendelkezik, amelyeket más csomagforrások nem kényszerítenek ki. Ezeket a különbségeket a nuget.org protokollokdokumentálják.
Az elérhető nuget.exe verziók egyszerű felsorolásáért és letöltéséért tekintse meg a tools.json végpontot.
Ha NuGet-csomagtárházat implementál, további követelményekért és javaslatokért tekintse meg a megvalósítási útmutatót.
Szolgáltatásindex
Az API belépési pontja egy jól ismert helyen található JSON-dokumentum. Ezt a dokumentumot szolgáltatásindexnek nevezzük. A nuget.org szolgáltatásindexének helye https://api.nuget.org/v3/index.json.
Ez a JSON-dokumentum erőforrások listáját tartalmazza, amelyek különböző funkciókat biztosítanak, és különböző használati eseteket tesznek lehetővé.
Az API-t támogató ügyfeleknek el kell fogadniuk egy vagy több szolgáltatásindex URL-címét a megfelelő csomagforrásokhoz való csatlakozás eszközeként.
A szolgáltatásindexről további információt API-referencia.
Verziószámozás
Az API a NuGet HTTP-protokolljának 3. verziója. Ezt a protokollt néha "V3 API-nak" is nevezik. Ezek a referenciadokumentumok a protokoll ezen verziójára egyszerűen "API"-ként hivatkoznak.
A szolgáltatásindex sémaverzióját a szolgáltatásindex version tulajdonsága jelzi. Az API előírja, hogy a verziósztring főverziószáma 3. Mivel a szolgáltatásindex sémáján nem töredék módosítások történnek, a verziósztring alverziója növekedni fog.
A régebbi ügyfelek (például nuget.exe 2.x) nem támogatják a V3 API-t, és csak a régebbi V2 API-t támogatják, amely itt nincs dokumentálva.
A NuGet V3 API neve azért van így, mert a V2 API utódja, amely a hivatalos NuGet-ügyfél 2.x verziója által implementált OData-alapú protokoll volt. A V3 API-t először a hivatalos NuGet-ügyfél 3.0-s verziója támogatta, és továbbra is a NuGet-ügyfél által támogatott legújabb fő protokollverzió, a 4.0-s és az újabb verzió.
Az API-t nemtörő protokollmódosítások történtek az első kiadás óta.
Erőforrások és séma
A szolgáltatásindex számos erőforrást ír le. A támogatott erőforrások jelenlegi készlete a következő:
| Erőforrás neve | Szükséges | Leírás |
|---|---|---|
| katalógus | Nem | Az összes csomagesemény teljes rekordja. |
| PackageBaseAddress | igen | Csomagtartalom lekérése (.nupkg). |
| PackageDetailsUriTemplate | Nem | Hozzon létre egy URL-címet a csomag részleteit tartalmazó weblap eléréséhez. |
| PackagePublish | igen | Csomagok leküldése és törlése (vagy törlése). |
| ReadmeUriTemplate | Nem | Hozzon létre egy URL-címet a csomag README-jének eléréséhez. |
| RegistrationsBaseUrl | igen | Csomag metaadatainak lekérése. |
| ReportAbuseUriTemplate | Nem | Hozzon létre egy URL-címet a jelentéshasználati weblap eléréséhez. |
| RepositorySignatures | Nem | Az adattár-aláíráshoz használt tanúsítványok lekérése. |
| SearchAutocompleteService | Nem | A csomagazonosítók és -verziók felderítése részszűréssel. |
| SearchQueryService | igen | Csomagok szűrése és keresése kulcsszó szerint. |
| SymbolPackagePublish | Nem | Leküldéses szimbólumcsomagok. |
| VulnerabilityInfo | Nem | Ismert biztonsági résekkel rendelkező csomagok. |
Az API-erőforrások által visszaadott nem bináris adatok általában JSON használatával szerializálódnak. A szolgáltatásindex egyes erőforrásai által visszaadott válaszséma külön-külön van definiálva az adott erőforráshoz. Az egyes erőforrásokkal kapcsolatos további információkért tekintse meg a fenti témaköröket.
A jövőben a protokoll fejlődésével új tulajdonságokat lehet hozzáadni a JSON-válaszokhoz. Ahhoz, hogy az ügyfél időtálló legyen, a megvalósítás nem feltételezi, hogy a válaszséma végleges, és nem tartalmazhat további adatokat. Az implementáció által nem értelmezhető összes tulajdonságot figyelmen kívül kell hagyni.
Jegyzet
Ha egy forrás nem implementálja SearchAutocompleteService az automatikus kiegészítési viselkedést kecsesen le kell tiltani. Ha a ReportAbuseUriTemplate nincs implementálva, a hivatalos NuGet-ügyfél visszaesik a nuget.org jelentésének visszaélési URL-címére (NuGet/Home#4924). Más ügyfelek dönthetnek úgy, hogy egyszerűen nem jelenítik meg a jelentés visszaélés URL-címét a felhasználónak.
Nem dokumentált erőforrások a nuget.org
A nuget.org V3 szolgáltatásindexe olyan erőforrásokkal rendelkezik, amelyek nem dokumentáltak fent. Van néhány oka annak, hogy nem dokumentál egy erőforrást.
Először is, nem dokumentáljuk a nuget.org implementálási részleteiként használt erőforrásokat. A SearchGalleryQueryService ebbe a kategóriába tartozik.
NuGetGallery ezzel az erőforrással delegál néhány V2 (OData) lekérdezést a keresési indexbe az adatbázis használata helyett. Ez az erőforrás méretezhetőségi okokból lett bevezetve, és nem külső használatra készült.
Másodszor, nem dokumentáljuk a hivatalos ügyfél RTM-verziójában soha nem szállított erőforrásokat.
PackageDisplayMetadataUriTemplate és PackageVersionDisplayMetadataUriTemplate ebbe a kategóriába tartoznak.
Harmadszor, nem dokumentáljuk azokat az erőforrásokat, amelyek szorosan kapcsolódnak a V2 protokollhoz, amely maga szándékosan nem dokumentált. A LegacyGallery erőforrás ebbe a kategóriába tartozik. Ez az erőforrás lehetővé teszi, hogy a V3 szolgáltatásindex egy megfelelő V2-forrás URL-címre mutasson. Ez az erőforrás támogatja a nuget.exe list.
Ha egy erőforrás nincs dokumentálva, erősen javasoljuk, javasoljuk, hogy ne függjön tőlük. Eltávolíthatjuk vagy módosíthatjuk a nem dokumentált erőforrások viselkedését, ami váratlan módon megszakíthatja a megvalósítást.
Időbélyegek
Az API által visszaadott időbélyegek utc- vagy egyéb módon vannak megadva ISO 8601-ábrázolással.
HTTP-metódusok
| Ige | Használ |
|---|---|
| KAP | Írásvédett műveletet hajt végre, amely általában adatokat olvas be. |
| FEJ | Lekéri a megfelelő GET kérés válaszfejléceit. |
| HELYEZ | Olyan erőforrást hoz létre, amely nem létezik, vagy ha létezik, frissíti azt. Előfordulhat, hogy egyes erőforrások nem támogatják a frissítést. |
| TÖRÖL | Töröl vagy töröl egy erőforrást. |
HTTP-állapotkódok
| Kód | Leírás |
|---|---|
| 200 | Siker, és van egy válasz törzse. |
| 201 | Sikeres volt, és létrejött az erőforrás. |
| 202 | Sikeres, a kérést elfogadták, de előfordulhat, hogy néhány munka még mindig hiányos, és aszinkron módon fejeződött be. |
| 204 | Siker, de nincs választörzs. |
| 301 | Állandó átirányítás. |
| 302 | Ideiglenes átirányítás. |
| 400 | Az URL-címben vagy a kérelem törzsében lévő paraméterek érvénytelenek. |
| 401 | A megadott hitelesítő adatok érvénytelenek. |
| 403 | A művelet nem engedélyezett a megadott hitelesítő adatokkal. |
| 404 | A kért erőforrás nem létezik. |
| 409 | A kérés ütközik egy meglévő erőforrással. |
| 500 | A szolgáltatás váratlan hibát észlelt. |
| 503 | A szolgáltatás átmenetileg nem érhető el. |
Az API-végpontra irányuló GET kérések HTTP-átirányítást (301 vagy 302) adhatnak vissza. Az ügyfeleknek az ilyen átirányításokat a Location fejléc megfigyelésével és egy későbbi GETkiadásával kell kezelnie. Az adott végpontokra vonatkozó dokumentáció nem hívja meg explicit módon, hogy hol használhatók átirányítások.
500 szintű állapotkód esetén az ügyfél ésszerű újrapróbálkozési mechanizmust valósíthat meg. A hivatalos NuGet-ügyfél háromszor próbálkozik újra, amikor 500 szintű állapotkódot vagy TCP/DNS-hibát tapasztal.
HTTP-kérelem fejlécei
| Név | Leírás |
|---|---|
| X-NuGet-ApiKey | Leküldéshez és törléshez szükséges, lásd PackagePublish erőforrás- |
| X-NuGet-Client-Version |
Elavult és helyébe X-NuGet-Protocol-Version |
| X-NuGet-Protocol-Version | Bizonyos esetekben csak nuget.org szükséges, lásd nuget.org protokollokat |
| X-NuGet-Session-Id | Választható. A NuGet-ügyfelek v4.7+-os verziói azonos NuGet-ügyfél munkamenet részét képező HTTP-kéréseket azonosítanak. |
A X-NuGet-Session-Id egyetlen értékkel rendelkezik az PackageReferenceegyetlen visszaállításával kapcsolatos összes művelethez. Más forgatókönyvek, például az automatikus kiegészítés és a packages.config visszaállítása esetén a kód faktorálásának köszönhetően több különböző munkamenet-azonosító is előfordulhat.
Hitelesítés
A hitelesítés a definiálandó csomagforrás-implementáción múlik. Az nuget.org esetében csak a PackagePublish erőforrás igényel hitelesítést egy speciális API-kulcsfejlécen keresztül. Részletekért lásd PackagePublish erőforrás-.