JSON-objektien muuntaminen ja rakentaminen jq:lla

Tuotantokäytössä oleva JSON-data on usein sisäkkäistä. jq:n avulla voitte käsitellä sisäkkäisiä polkuja objektin muodostajan sisällä ja samalla litistää rakenteen.

Käyttäkää pistepolkumerkintää muodostajan arvolausekkeessa:

• { city: .address.city }
• { lat: .location.coords.lat }

Alla oleva esimerkki ottaa syvästi sisäkkäisen käyttäjätietueen ja tuottaa siitä litteän yhteenvedon, joka sopii CSV-otsikkoriville tai API-pyynnön rungoksi.

map(expr) vastaa jq:ssä for-each-rakennetta: se soveltaa expr-lauseketta syötetaulukon jokaiseen alkioon ja palauttaa uuden, yhtä pitkän taulukon.

Keskeiset asiat:

• map(expr) on lyhyt muoto ilmaisulle [.[] | expr]
• Sisäinen lauseke voi olla mikä tahansa jq-suodatin — myös objektin muodostaminen
• Yhdistäkää se select()-suodattimeen ennen muuntamista

Katkelma käsittelee tilausten luetteloa ja säilyttää vain toimitusluetteloon tarvittavat kentät.

map-funktion sisällä voitte laskea uusia arvoja, muuntaa tyyppejä ja yhdistää kenttiä — ette ainoastaan kopioida niitä. Yleisiä malleja ovat:

• Merkkijonojen interpolointi: "\(.first) \(.last)"
• Aritmetiikka: (.price * 1.2 | round) 20 prosentin hinnankorotukseen
• Ehdolliset lausekkeet: if .score >= 90 then "A" else "B" end

Alla oleva esimerkki täydentää työntekijäluetteloa lisäämällä lasketun fullName-kentän ja työkokemuksen vuosien perusteella määräytyvän seniority-tunnisteen.

to_entries muuntaa JSON-objektin taulukoksi, joka sisältää {key, value}-pareja. Näin objektin kenttiin voidaan soveltaa taulukko-operaatioita, kuten map-, select- ja sort-toimintoja — suoraan objektille niitä ei voi tehdä.

Esimerkki muunnoksesta:

• Syöte: {"a": 1, "b": 2}
• Tuloste: [{"key": "a", "value": 1}, {"key": "b", "value": 2}]

Käänteinen toiminto on from_entries, joka muuntaa taulukon takaisin objektiksi. Yhdessä ne muodostavat to_entries | map(...) | from_entries -idiomin objektitason muunnoksiin.

Yksi to_entries-toiminnon käytännöllisimmistä käyttötavoista on säilytettävien tai poistettavien avainten dynaaminen suodattaminen itse avaimen nimen perusteella — objektin muodostamisella tätä ei voi tehdä, jos avainten nimiä ei tiedetä etukäteen.

Malli:

• to_entries | map(select(.key | test("regex"))) | from_entries
• to_entries | map(select(.key != "secret")) | from_entries

Alla oleva katkelma poistaa kaikki alaviivalla alkavat avaimet (sisäiset/yksityiset kentät) ennen määritysobjektin välittämistä ulkoiselle palvelulle.

Objektin muodostamisella avaimet voidaan nimetä uudelleen, kun niiden nimet tiedetään kirjoitushetkellä. to_entries mahdollistaa avainten nimeämisen uudelleen ohjelmallisesti — esimerkiksi camelCase-muodon muuntamisen snake_case-muotoon tai etuliitteen lisäämisen.

map-funktion sisällä päivitätte kunkin tietueen .key-kentän ja välitätte tuloksen sitten from_entries-toiminnolle:

• map(.key |= gsub("(?<=[a-z])(?=[A-Z])"; "_") | .key |= ascii_downcase) — camelCase-muodosta snake_case-muotoon
• map(.key |= "app_" + .) — lisää etuliitteen jokaiseen avaimeen

Esimerkki lisää kaikkiin ympäristömuuttujien nimiin etuliitteen APP_, jotta ne saadaan omaan nimiavaruuteensa ennen niiden välittämistä säilöön.

Malli to_entries | map(...) | from_entries on niin yleinen, että jq tarjoaa sille lyhyen muodon: with_entries(expr).

Se vastaa täsmälleen samaa toimintoa, mutta on tiiviimpi:

• with_entries(.value |= . * 2) — kaksinkertaistaa jokaisen numeerisen arvon
• with_entries(select(.value != null)) — poistaa avaimet, joiden arvo on null
• with_entries(.key |= ascii_upcase) — muuttaa kaikki avaimet suuraakkosiksi

Katkelma poistaa kaikki avaimet, joiden arvo on null tai tyhjä merkkijono — tämä on yleinen siivousvaihe ennen PATCH-pyynnön lähettämistä REST-sovellusliittymään.

Reaalimaailman muunnoksissa useita jq-toimintoja ketjutetaan yhteen. Tyypillinen API-hyötykuorman valmisteluun käytettävä putki voi:

1. Suodattaa syötetaulukon komennolla map(select(...))
2. Muotoilla jokaisen alkion uudelleen objektin muodostuksella
3. Lisätä laskettuja kenttiä
4. Järjestää tuloksen

Alla oleva esimerkki lukee palvelinmittareiden luettelon, säilyttää vain paljon suoritinta käyttävät palvelimet ja tuottaa webhookiin POST-pyynnöllä lähetettävän tiiviin hälytyshyötykuorman.

jq voi yhdistää syötteitä ja muodostaa useista JSON-lähteistä tietoja kokoavia objekteja yhteenlaskuoperaattorin + ja as $var-muuttujasidonnan avulla.

Hyödyllisiä malleja:

• obj1 + obj2 — yhdistää kaksi objektia (oikeanpuoleinen voittaa avainristiriidoissa)
• --argjson — välittää toisen JSON-asiakirjan muuttujana
• $ENV — lukee ympäristömuuttujat suoraan jq:n sisällä

Katkelma yhdistää perusmäärityksen ympäristökohtaisiin ohituksiin — tämä on yleinen malli 12-factor-sovellusten määritysten hallinnassa komentotulkkiskripteissä.

Olette käsitelleet JSON-datan rakenteen muokkaamisen keskeiset tekniikat jq:llä:

• Objektin muodostaminen {} — muodostetaan uusia objekteja valitsemalla, nimeämällä uudelleen ja laskemalla kenttiä syötteestä
• map(expr) — sovelletaan mitä tahansa muunnosta taulukon jokaiseen alkioon, mukaan lukien sisäkkäinen objektin muodostaminen ja suodattamiseen käytettävä select()
• to_entries / from_entries — muunnetaan objekti {key, value}-parien taulukoksi, jolloin avaimille ja arvoille voidaan tehdä taulukko-operaatioita, ja muunnetaan se sitten takaisin
• with_entries(expr) — tiivis lyhyt muoto täydelle to_entries → map → from_entries -putkelle
• Objektien yhdistäminen komennolla + ja valitsimella --argjson useista lähteistä muodostettavia hyötykuormia varten

Nämä rakennuspalikat toimivat yhdessä: suodattakaa select-toiminnolla, muokatkaa rakennetta objektin muodostamisella, täydentäkää lasketuilla kentillä ja ketjuttakaa kaikki yhdeksi helposti luettavaksi jq-lausekkeeksi. Näiden mallien hallitseminen tarkoittaa, että voitte käsitellä käytännössä mitä tahansa JSON-hyötykuormaa suoraan komentotulkissa ilman erillisen Python- tai Node-komentosarjan kirjoittamista.