estat-servei.sh ja distingeix procés, port i aplicació, però es queda a la porta: sap que /salud retorna un 200, no què diu. La veloz-api respon JSON —estat de la base de dades, enviaments a la cua, versió desplegada, mètriques—, i aquí el toolkit deixa de llegir fitxers que algú va deixar al disc per integrar-se amb la resta del sistema. Aquesta lliçó cobreix curl a fons per parlar amb APIs i jq per manejar JSON de debò: extreure'l, filtrar-lo, convertir-lo en columnes i també construir-lo de forma segura, perquè al final informe-diari.sh publicarà el seu resum diari en JSON.

1. curl als scripts: el trio -sSf
2. Mètodes, capçaleres i cossos
3. Fitxers, redireccions i temps d'espera
4. Credencials sense deixar rastre
5. Codis HTTP: què ha de distingir un script
6. Cos i codi d'estat en una sola crida
7. Per què NO s'analitza JSON amb grep o sed
8. jq: el model de filtres
9. Seleccionar, filtrar i agregar
10. Controlar la sortida: -r, -c, -e i @tsv
11. Construir JSON de forma segura
12. Llegir JSON a Bash, i JSON com a configuració
13. Aplicació: el toolkit parla amb l'API i publica JSON

Per defecte curl està pensat per a una persona en un terminal: escriu una barra de progrés i, si el servidor contesta un error, imprimeix la pàgina d'error i retorna 0. En un script això és exactament el contrari del que vols. Tres opcions ho arreglen:

Memoritza -sSf com un bloc: silenciós, però que es queixi, i que falli de debò. És l'error més estès als scripts que parlen amb APIs, i produeix la pitjor de les fallades possibles: una de silenciosa que fa creure que tot va bé.

Per a APIs REST calen quatre opcions més:

-X fixa el mètode (GET, POST, PUT, DELETE); no cal amb -d, que ja implica POST. -H afegeix una capçalera i es repeteix tantes vegades com calgui. -d envia el cos —si comença per @, el llegeix d'un fitxer: -d @cos.json—. Per a paràmetres amb caràcters especials existeix --data-urlencode, que codifica el valor: curl -sSfG --data-urlencode "ciudad=Palma de Mallorca" http://localhost:8080/envios. Aquest -G converteix les dades en paràmetres de l'URL en lloc de cos, així que el resultat és /envios?ciudad=Palma%20de%20Mallorca. Escriure aquest URL a mà amb una variable de Bash és una fallada esperant a passar: un espai, un & o un accent al valor i la petició canvia de significat.

Els dos temps d'espera són diferents i cal posar-los tots dos. --connect-timeout 5 talla ràpid quan la màquina no hi és; --max-time 30 protegeix del servidor que accepta la connexió i després es queda pensant indefinidament. Un curl sense --max-time en un script automàtic és una bomba de rellotgeria: el dia que el servei s'encalli, la teva tasca de cron es quedarà penjada per sempre i bloquejarà les següents (07-01).

-u usuari:clau fa autenticació bàsica, però escrita així la contrasenya apareix a ps, a l'historial (02-06) i a qualsevol registre de l'ordre. Les dues formes correctes:

--netrc-file llegeix màquina, usuari i clau d'un fitxer amb permisos 600, igual que veloz-ops.conf (05-06). La segona opció fa servir una variable d'entorn carregada des d'aquest fitxer de configuració: no queda a l'historial, encara que sí que és visible a /proc/<pid>/environ per al mateix usuari i per a root. El que no s'ha de fer mai és incrustar la credencial a l'URL, com ja es va veure a 06-04.

Aquesta distinció entre 4xx i 5xx és la que fa útil un script d'integració: reintentar un 404 és perdre el temps, i no reintentar un 503 és donar per caigut un servei que s'estava reiniciant. I recorda el punt de partida: sense -f, curl retorna 0 amb qualsevol codi, així que sense ell ni tan sols te n'assabentes.

-f et diu que hi ha hagut error, però descarta el cos, que sol contenir l'explicació. Per tenir totes dues coses sense fer dues peticions, es demana el codi amb -w al final i se separa després:

Aquí es juxtaposen tres coses de mòduls anteriors: -w '\n%{http_code}' afegeix el codi en una línia nova al final, les expansions ${var##*} i ${var%*} de 04-04 el separen del cos sense llançar processos, i el case amb globs de 04-05 classifica per família amb 2??. Fixa't que aquí no es fa servir -f: volem el cos de l'error, així que la decisió la pren el case.

La temptació és enorme i el resultat sempre acaba malament. Per treure l'estat de /salud, el que tothom escriu la primera vegada és curl -s $API/salud | grep -o '"estat":"[^"]*"' | cut -d'"' -f4. Funciona fins que deixa de fer-ho, i les raons no són rebuscades: el JSON pot venir compacte o amb salts de línia (la teva regex depèn del format, que el servidor pot canviar sense avisar); l'ordre de les claus no està garantit; pot aparèixer un objecte imbricat amb una altra clau estat i el teu grep agafarà la primera que trobi; un valor pot contenir cometes escapades ("missatge":"error \"greu\"") que destrossen [^"]*; i null, els números i els booleans no porten cometes, així que el patró ni els veu. En resum: JSON no és un format de línies, i les eines de línies no el poden entendre amb fiabilitat. El que fa falta és un analitzador, i aquest és jq.

jq és un llenguatge de filtres: rep un document JSON, li aplica una expressió i emet JSON. La idea central és que tot filtre transforma una entrada en zero, una o diverses sortides, i s'encadenen amb | com les canonades del shell.

Suposem que /salud retorna {"estat":"ok","versio":"2.4.1","bd":{"connectada":true,"latencia_ms":12},"cua":[3,7,2]}:

Les dues últimes files són les que eviten la meitat dels ensurts: // dona un valor per defecte quan l'API omet un camp, i ? impedeix que un error de tipus avorti tot el filtre. La diferència entre .cua (un array) i .cua[] (tres sortides) és el concepte que cal interioritzar: la majoria dels filtres interessants treballen sobre fluxos de valors, no sobre un de sol.

Sobre una resposta de /envios?ciudad=Madrid, que retorna un array d'objectes amb id, estat i import:

Els claudàtors de [.[] | .import] són importants: .[] | .import emet tres valors solts, i add necessita un array, així que cal recollir-los. Confondre «flux de valors» amb «array» és l'error número u amb jq, i s'arregla sempre amb [ ] o amb map(). Veuràs que group_by + map és la mateixa agregació que feies amb arrays associatius a awk (06-01), només que sobre JSON.

Per defecte jq emet JSON, així que una cadena surt entre cometes: "ok", no ok. En assignar-la a una variable de Bash, aquestes cometes hi viatgen i espatllen qualsevol comparació posterior.

-e converteix una consulta JSON en una condició de shell, sense variables intermèdies. I per tornar al terreny d'awk, @tsv i @csv converteixen arrays en columnes:

Aquest encadenament és el pont entre els dos mons: jq entén l'estructura i l'aplana a columnes; awk agrega. @csv posa els camps entre cometes segons les regles de CSV, i tots dos necessiten -r perquè no surti tot com una cadena JSON escapada.

Generar JSON a mà —printf '{"ciutat":"%s","nota":"%s"}\n' "$ciutat" "$nota"— funciona fins al primer valor amb una cometa, una barra invertida o un salt de línia, i llavors produeix JSON invàlid o, pitjor, JSON vàlid amb el contingut canviat. La forma correcta és jq -n, que construeix des de zero, amb --arg per a cadenes i --argjson per a valors que ja són JSON (números, booleans, objectes):

jq s'encarrega de l'escapada: una cometa dins de $nota surt com a \", un salt de línia com a \n i els accents es codifiquen correctament. La distinció entre --arg i --argjson és el parany habitual: --arg total 1001 produeix "1001" (cadena) i --argjson total 1001 produeix 1001 (número). Si el valor pot venir buit, --argjson fallarà —jq no accepta JSON invàlid—, així que convé un ${total:-0}. I com amb awk -v a 06-01, el principi és el mateix: els valors de Bash entren com a paràmetres, mai interpolats dins del filtre, perquè interpolar-los és injecció de codi.

Per recórrer una resposta a Bash, la combinació és jq -r '.[] | @tsv' amb el bucle de 04-01:

@tsv és preferible a separar per espais perquè els valors en poden contenir, i a més escapa els tabuladors i els salts de línia que hi hagués dins d'un camp. La substitució de processos < <( ) de 05-05 manté el bucle al shell actual. Quan el que necessites és un array de Bash amb una sola columna, mapfile -t ids < <(jq -r '.[].id' <<< "$json") (04-03) és més directe.

JSON també serveix com a format de configuració, i jq el llegeix amb les mateixes regles: jq -r '.llindars.disc // 85' etc/veloz.json retorna el valor o el defecte si falta. Davant del clau=valor de veloz-ops.conf (05-06), guanya en estructura imbricada i tipus, i perd en què no es pot carregar amb source i no admet comentaris. Per a YAML —el format dels fitxers de CI i de Kubernetes— existeix yq, que replica la sintaxi de jq sobre YAML i fins i tot converteix entre tots dos amb yq -o=json. Si ja saps jq, saps yq.

Primer, estat-servei.sh consulta l'API de debò i distingeix caiguda d'error d'aplicació, que és la diferència entre reiniciar el servei i avisar l'equip de desenvolupament:

Els tres desenllaços són diferents a propòsit: sense resposta (el curl falla), resposta amb error HTTP (s'extreu .missatge del cos per a l'avís) i resposta correcta però amb estat degradat. jq -e fa servir el JSON com a condició i l'if ... then ... else ... end de jq formata el booleà per al missatge. Fixa't en el <<< "$cos", la cadena-document de 05-05: evita rellegir la resposta de la xarxa cada vegada.

I informe-diari.sh tanca el cercle publicant el seu resum com a JSON, construït amb jq -n:

El mktemp amb trap de 05-01 i el mv final garanteixen que ningú no llegeixi mai un fitxer a mig escriure: o existeix el resum complet o existeix el del dia anterior. now | todate genera la marca de temps en UTC ISO-8601 sense cridar date. I ara l'informe ja no és només un text per llegir: és una dada que un altre programa —un panell, una alerta, el projecte 09-05— pot consumir sense tornar a analitzar res.

• curl sense -f (o sense comprovar el codi). Retorna 0 amb un 500 i l'script continua com si res. Fes servir -sSf, o -w '%{http_code}' i un case.
• curl sense --max-time. Un servei encallat penja la tasca de cron indefinidament.
• Analitzar JSON amb grep/sed. Falla amb el format compacte, l'ordre de claus, els imbricats i les cometes escapades. Fes servir jq.
• Oblidar -r. estat=$(jq '.estat') desa "ok" amb cometes i [[ $estat == ok ]] falla.
• Confondre flux amb array. .[] | .import emet valors solts; add necessita [.[] | .import].
• --arg per a números. Produeix "1001" en comptes de 1001; per a números i booleans, --argjson.
• Interpolar variables de Bash dins del filtre jq. Mateix risc d'injecció que a awk: fes servir --arg.
• Reintentar un 4xx. No s'arreglarà sol. Reintenta els 5xx i les fallades de xarxa, amb retrocés (06-04).
• Consell: construeix els filtres per passos (jq '.', després jq '.camp'…) contra una resposta d'exemple desada en un fitxer: és més ràpid que cridar l'API, funciona sense connexió i jq es depura molt millor en increments que d'una tirada.

Exercici 1. Escriu una funció veloz_api_get per a lib/comu.sh que faci GET a un camí de l'API, retorni el cos per la sortida estàndard, distingeixi xarxa / 4xx / 5xx amb missatges diferents i codis de sortida diferents, i no es pugui penjar.

Exercici 2. Amb /metricas retornant {"peticions":48210,"errors":37,"latencia_p95_ms":210,"enviaments_cua":14}, escriu una comprovació que avisi si la taxa d'errors supera el 0,1 % o si la latència p95 passa de 500 ms, tractant els camps que faltin com a 0.

Exercici 3. Converteix la sortida de /envios?ciudad=Madrid (array d'objectes amb id, repartidor, estat, import) en un resum per repartidor amb nombre d'enviaments i import total, ordenat de major a menor, fent servir només jq.

Solució 1.

Els tres codis són deliberats i segueixen la taula de 05-03: 69 (EX_UNAVAILABLE) quan no hi ha resposta, 64 (EX_USAGE) per a un 4xx —l'error és nostre— i 75 (EX_TEMPFAIL) per a un 5xx, que és precisament el codi que diu a qui la crida «això és temporal, pots reintentar». El cos surt net per stdout i els diagnòstics per stderr (02-04), de manera que dades=$(veloz_api_get /salud) captura només el que interessa.

Solució 2.

El // 0 de cada camp evita que una mètrica absent es converteixi en null i trenqui els comptes. Els tres valors s'extreuen en una sola invocació de jq amb @tsv i un read, en comptes de cridar-lo tres vegades. La taxa d'errors és decimal, així que la comparació va a awk amb l'idioma exit !(...) de 06-03; la latència és entera i en té prou amb (( )).

Solució 3.

group_by produeix un array d'arrays —un per repartidor—, i map el converteix en objectes: .[0].repartidor pren el nom de qualsevol element del grup, length compta i map(.import) | add suma. sort_by(-.total) ordena descendent negant el valor, més net que ordenar i després reverse. Al final, @tsv aplana a columnes i column -t (02-02) les alinea. És exactament l'agregació de la solució 1 de 06-01, però partint de JSON en comptes de CSV.

Parlar amb una API des d'un script són dues eines i unes quantes regles. De curl: -sSf com un bloc indivisible —silenciós, queixós davant de fallades de xarxa i fallant de debò davant d'un error HTTP, perquè sense -f retorna 0 amb un 500—; -X, -H, -d i --data-urlencode per construir la petició; -L, -o/-O per al cos; --connect-timeout i --max-time sempre, o el dia que el servei s'encalli penjaràs la tasca de cron; credencials per --netrc o capçalera des d'un fitxer 600, mai a l'URL; i -w '\n%{http_code}' per quedar-te amb cos i codi en una sola crida i classificar amb un case que distingeixi 4xx (no reintentar) de 5xx (reintentar amb retrocés). De jq: un llenguatge de filtres encadenats amb | on .camp, .a.b, .[], select, map, group_by, add, sort_by, length, to_entries, // i ? cobreixen gairebé tot; -r per treure cadenes sense cometes, -e per fer servir JSON com a condició, @tsv/@csv per tornar al terreny d'awk; i jq -n --arg/--argjson per construir JSON amb l'escapada resolta, passant els valors de Bash com a paràmetres i mai interpolats. I la regla que ho engloba tot: JSON no és un format de línies, així que grep i sed no serveixen per llegir-lo.

Amb això es tanca el Mòdul 6 i el toolkit de Veloz Envíos canvia de naturalesa. informe-diari.sh agrega en una sola passada amb awk i publica el seu resum en JSON; estat-servei.sh reuneix el context del sistema, comprova xarxa i port, interroga la veloz-api i distingeix una caiguda d'un error d'aplicació. Ja no és un lector de fitxers: és una peça integrada amb la resta del sistema. Però fixa't en el que tenen en comú totes les execucions d'aquest mòdul: has estat tu qui ha escrit l'ordre. L'informe diari només existeix si algú es recorda de llançar-lo, i una comprovació d'estat que s'executa quan ja sospites que alguna cosa va malament arriba tard per definició. Al Mòdul 7 això s'acaba: cron perquè les tasques s'executin soles (07-01), el disseny de tasques veritablement desateses (07-02), còpies de seguretat automàtiques (07-03), monitoratge i registre continus (07-04), serveis i temporitzadors de systemd (07-05) i automatització remota amb ssh (07-06). El toolkit deixa d'esperar les teves ordres.