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.