HTTP kérések a Kotlinnal és a khttp-vel
1. Bemutatkozás
A HTTP protokoll és az arra épülő API-k központi fontosságúak a programozásban manapság.
A JVM-en számos rendelkezésre álló lehetőség áll rendelkezésre, az alacsonyabb szintű és a nagyon magas szintű könyvtárak között, a létrehozott projektektől kezdve az új gyerekekig. Legtöbbjük azonban elsősorban a Java programokat célozza meg.
Ebben a cikkben, megnézzük a khttp-t, egy idiomatikus Kotlin könyvtárat, amely HTTP alapú erőforrásokat fogyaszt és API-k.
2. Függőségek
A könyvtár használatához projektünkben először hozzá kell adnunk a függőségeinkhez:
khttp khttp 0.1.0
Mivel ez még nincs a Maven Centralon, engedélyeznünk kell a JCenter adattárat is:
central //jcenter.bintray.com
A 0.1.0 verzió az aktuális az írás idején. Természetesen ellenőrizhetjük a JCentert egy újabbal.
3. Alapvető használat
A HTTP protokoll alapjai egyszerűek, bár a finom részletek meglehetősen bonyolultak lehetnek. Ezért a khttp-nek is van egy egyszerű felülete.
Minden HTTP módszerhez találhatunk csomagszintű függvényt a khttp csomag, mint például kap, post stb.
A függvények mindegyike ugyanazokat az argumentumokat veszi fel, és visszaadja a Válasz tárgy; ezek részleteit a következő szakaszokban láthatjuk.
A cikk során a teljesen minősített űrlapot fogjuk használni, például khttp.put. Projektjeinkben természetesen importálhatjuk és esetleg átnevezhetjük ezeket a módszereket:
importálja a khttp.delete fájlt httpDelete néven
Megjegyzés: A kódpéldákban az egyértelműség kedvéért típusdeklarációkat adtunk hozzá mert IDE nélkül nehéz lehet őket követni.
4. Egyszerű kérés
Minden HTTP-kérelemnek legalább két szükséges összetevője van: egy módszer és egy URL. A khttp fájlban a módszert az általunk meghívott függvény határozza meg, amint azt az előző szakaszban láthattuk.
Az URL az egyetlen szükséges argumentum a módszerhez; így könnyen teljesíthetünk egy egyszerű kérést:
khttp.get ("// httpbin.org/get")
A következő szakaszokban az összes kérelmet sikeresen teljesítjük.
4.1. Paraméterek hozzáadása
Gyakran meg kell adnunk a lekérdezési paramétereket az alap URL-en kívül, különösen a GET kéréseknél.
A khttp módszerei elfogadják a params érv ami a Térkép kulcs-érték párok közül a lekérdezésbe Húr:
khttp.get (url = "//httpbin.org/get", params = mapOf ("key1" - "value1", "keyn" - "valuen"))
Figyelje meg, hogy a mapOf függvény a Térkép menet közben; az eredményül kapott URL a következő lesz:
//httpbin.org/get?key1=value1&keyn=valuen
5. Kérelmező testület
Egy másik gyakori művelet, amelyet gyakran el kell végeznünk, az adatküldés, általában POST vagy PUT kérés hasznos terheként.
Ehhez a könyvtár számos lehetőséget kínál, amelyeket megvizsgálunk a következő szakaszokban.
5.1. JSON hasznos terhelés küldése
Használhatjuk a json argumentum JSON objektum vagy tömb elküldéséhez. Többféle lehet:
- A JSONObject vagy JSONArray az org.json könyvtár biztosítja
- A Térkép, amely átalakul JSON objektummá
- A Gyűjtemény, Iterálható vagy tömb, amely átalakul JSON tömbvé
Könnyen átalakíthatjuk korábbi GET példánkat POST-vá, amely egy egyszerű JSON objektumot küld:
khttp.post (url = "//httpbin.org/post", json = mapOf ("key1" - "value1", "keyn" - "valuen"))
Vegye figyelembe, hogy a gyűjteményekből a JSON objektumokká történő átalakítás sekély. Például a Lista nak,-nek TérképNem konvertálódnak JSON objektumok JSON tömbjévé, sokkal inkább stringek tömbjévé.
A mély konverzióhoz egy összetettebb JSON-leképező könyvtárra lenne szükségünk, például Jacksonra. A könyvtár átalakítási lehetősége csak egyszerű esetekre szolgál.
5.2. Űrlapadatok küldése (kódolt URL)
Az űrlapadatok (URL kódolású, mint a HTML űrlapok) küldéséhez a adat érvelés a Térkép:
khttp.post (url = "//httpbin.org/post", data = mapOf ("key1" - "value1", "keyn" - "valuen"))
5.3. Fájlok feltöltése (többrészes űrlap)
Küldhetünk egy vagy több fájlt többrészes adatkérésként kódolva.
Ebben az esetben a fájlokat érv:
khttp.post (url = "//httpbin.org/post", files = listOf (FileLike ("file1", "content1"), FileLike ("file2", File ("kitty.jpg"))))
Láthatjuk, hogy a khttp a FileLike absztrakció, amely névvel és tartalommal rendelkező objektum. A tartalom lehet karakterlánc, bájt tömb, a File, vagy a Pálya.
5.4. Nyers tartalom küldése
Ha a fenti lehetőségek egyike sem megfelelő, használhatunk egy InputStream nyers adatok HTTP-kérelem törzseként történő küldéséhez:
khttp.post (url = "//httpbin.org/post", data = someInputStream)
Ebben az esetben nagy valószínűséggel manuálisan is be kell állítanunk néhány fejlécet, amelyeket egy későbbi szakaszban tárgyalunk.
6. A válasz kezelése
Eddig számos módot láttunk az adatok szerverre történő elküldésére. De sok HTTP művelet hasznos a visszaadott adatok miatt is.
A khttp tehát az I / O blokkolásán alapul a HTTP metódusoknak megfelelő összes függvény visszaadja a Válasz tárgy tartalmazza a szervertől kapott választ.
Ennek az objektumnak különféle tulajdonságai vannak, amelyekhez hozzáférhetünk, a tartalom típusától függően.
6.1. JSON válaszok
Ha tudjuk, hogy a válasz JSON objektum vagy tömb, akkor használhatjuk a jsonObject és jsonArray tulajdonságok:
val response: Response = khttp.get ("// httpbin.org/get") val obj: JSONObject = response.jsonObject print (obj ["someProperty"])
6.2. Szöveges vagy bináris válaszok
Ha a választ a-ként szeretnénk olvasni Húr ehelyett használhatjuk a szöveg ingatlan:
val üzenet: Karakterlánc = válasz.szöveg
Vagy ha bináris adatként szeretnénk olvasni (pl. Fájlletöltés), akkor a tartalom ingatlan:
val imageData: ByteArray = response.content
Végül hozzáférhetünk az alapjához is InputStream:
val inputStream: InputStream = response.raw
7. Haladó használat
Vessünk egy pillantást néhány fejlettebb használati mintára, amelyek általában hasznosak, és amelyeket az előző szakaszokban még nem kezeltünk.
7.1. Fejlécek és sütik kezelése
Minden khttp függvény a fejlécek érv ami a Térkép fejléc nevek és értékek.
val response = khttp.get (url = "//httpbin.org/get", header = mapOf ("header1" - "1", "header2" - "2"))
Hasonlóan a sütik esetében:
val response = khttp.get (url = "//httpbin.org/get", cookies = mapOf ("cookie1" - "1", "cookie2" - "2"))
Hozzáférhetünk a kiszolgáló által a válaszban küldött fejlécekhez és sütikhez is:
val contentType: String = response.headers ["Content-Type"] val sessionID: String = response.cookies ["JSESSIONID"]
7.2. A hibák kezelése
Kétféle hiba fordulhat elő a HTTP-ben: hibaválaszok, például a protokoll részét képező 404 - Nem található; és alacsony szintű hibák, például a „kapcsolat elutasítása”.
Az első fajta nem eredményez khttp-s kivételeket; helyette, ellenőriznünk kell a Válasz statusCode ingatlan:
val response = khttp.get (url = "//httpbin.org/nothing/to/see/here") if (response.statusCode == 200) {process (response)} else {handleError (response)}
Alsó szintű hibák ehelyett kivételt dobnak az alapul szolgáló Java I / O alrendszerből, mint pl ConnectException.
7.3. Válaszok közvetítése
Néha a szerver nagy mennyiségű tartalommal tud válaszolni, és / vagy sokáig tarthat a válasz. Ezekben az esetekben érdemes a darabokat feldolgozni, ahelyett, hogy megvárnánk, amíg befejeződik és felemészti a memóriát.
Ha arra akarjuk utasítani a könyvtárat, hogy adjon nekünk streaming választ, akkor át kell mennünk igaz mint a folyam érv:
val response = khttp.get (url = "//httpbin.org", stream = true)
Ezután darabokban feldolgozhatjuk:
response.contentIterator (chunkSize = 1024) .forEach {arr: ByteArray -> handleChunk (arr)}
7.4. Nem szabványos módszerek
Abban a valószínűtlen esetben, hogy olyan HTTP metódust (vagy igét) kell használnunk, amelyet a khttp nem nyújt natív módon - mondjuk a HTTP protokoll bizonyos kiterjesztéseihez, például a WebDAV-hoz -, akkor is lefedjük.
Valójában a khttp csomag minden olyan funkciója, amely megfelel a HTTP metódusoknak, általános használatával valósul meg kérés funkció, amelyet mi is használhatunk:
khttp.request (módszer = "MÁSOLÁS", url = "//httpbin.org/get", fejléc = mapOf ("Cél" - "/ copy-of-get"))
7.5. Más funkciók
Nem érintettük a khttp összes funkcióját. Például nem beszéltünk időkorlátokról, átirányításokról és előzményekről, vagy aszinkron műveletekről.
A hivatalos dokumentáció a legfőbb információforrás a könyvtárról és annak minden funkciójáról.
8. Következtetés
Ebben az oktatóanyagban láthattuk, hogyan lehet HTTP-kéréseket készíteni Kotlinban a khttp idiomatikus könyvtárral.
Mindezen példák megvalósítása megtalálható a GitHub projektben.