Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 8: curl und jq

Ziel: HTTP-Anfragen mit curl gezielt stellen und auswerten, JSON mit jq lesen, filtern und sicher erzeugen. Am Ende legt notes-add jeden Text richtig an, und notes-export schreibt alle Notizen als CSV. · Dauer: ca. 75 min · Voraussetzung: Tag 7

Briefing

  • curl spricht HTTP: Methode (-X), Kopfzeilen (-H), Daten (-d), Zeitlimits (--max-time), Wiederholungen (--retry). Mit -w gibt es Statuscode und Zeiten aus, ohne den Inhalt anzufassen.
  • jq ist sed und awk für JSON: .feld, .[], select(), map(), length. -r gibt Text ohne Anführungszeichen aus.
  • JSON baut man nie mit printf oder "{\"text\":\"$x\"}" zusammen, sondern mit jq -n --arg. Nur dann sind Anführungszeichen, Backslashes und Zeilenumbrüche im Text sicher.
 notes-add 'Er sagte "hallo"' ─► jq -n --arg t … '{text: $t}' ─► curl -d @- ─► 201
 notes-export ─► curl /notes ─► jq -r '.[] | [.id, .text] | @csv' ─► notes.csv

Drill 1: curl gezielt

source ~/sh-lab/setup/env.sh
mkdir -p ~/sh-lab/tag08 && cd ~/sh-lab/tag08
curl -s -i $NOTES_URL/healthz | sed -n '1p;4p'
curl -s -o /dev/null -w '%{http_code} %{content_type} %{size_download} B\n' \
  $NOTES_URL/version
curl -s $NOTES_URL/version; echo
curl -s -o /dev/null -w 'DNS %{time_namelookup}s, gesamt %{time_total}s\n' \
  $NOTES_URL/notes | sed -E 's/[0-9]+\.[0-9]+s/…s/g'
curl -sS --max-time 2 --retry 2 --retry-delay 1 http://127.0.0.1:9/ 2>&1 | tail -1

Erwartet:

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
200 text/plain; charset=utf-8 6 B
0.4.0
DNS …s, gesamt …s
curl: (7) Failed to connect to 127.0.0.1 port 9 after 0 ms: Could not connect to se…
Option Wirkung
-s / -S still / Fehler trotzdem zeigen
-f HTTP-Fehler (≥ 400) als Exit-Code 22
-i Kopfzeilen mit ausgeben
-o datei Inhalt in eine Datei (/dev/null verwirft ihn)
-w '…' nach der Anfrage Werte ausgeben: %{http_code}, %{time_total} …
--retry n bei vorübergehenden Fehlern bis zu n-mal wiederholen

Fortschritt speichern? Kostenlos registrieren

Drill 2: jq lesen

curl -s $NOTES_URL/notes > notes.json
jq 'length' notes.json
jq '.[0] | keys' notes.json
jq -r '.[0].text' notes.json
jq -c '[.[] | select(.text == "erste Notiz")] | length' notes.json
jq -r '.[].text' notes.json | grep -c '^Lastnotiz'
jq -c 'map(.text | length) | {"kürzeste": min, "längste": max}' notes.json

Erwartet (die Zahlen hängen davon ab, wie oft du notes-last und notes-add aufgerufen hast):

28
[
  "id",
  "text"
]
erste Notiz
1
22
{"kürzeste":11,"längste":28}
  • .[0] ist das erste Element, .[] sind alle, | reicht das Ergebnis weiter – wie in der Shell, nur innerhalb von jq.
  • select(bedingung) behält nur, was passt. map(f) wendet f auf jedes Element an.
  • Schlüssel mit Umlauten oder Sonderzeichen stehen in Anführungszeichen: {"kürzeste": min}.
  • -r (raw) gibt Text ohne JSON-Anführungszeichen aus – Pflicht, wenn das Ergebnis in eine Shell-Variable oder an grep geht. -c gibt kompakt eine Zeile aus.

Fortschritt speichern? Kostenlos registrieren

Drill 3: JSON sicher erzeugen

text='Er sagte "hallo" und ging\ – mit Tab: Ende'
printf '{"text":"%s"}\n' "$text" | jq . 2>&1 | head -1
jq -n --arg t "$text" '{text: $t}'
jq -nc --arg t "$text" --argjson prio 2 '{text: $t, prio: $prio, tags: ["a", "b"]}'

Erwartet:

jq: parse error: Invalid numeric literal at line 1, column 25
{
  "text": "Er sagte \"hallo\" und ging\\ – mit Tab:\tEnde"
}
{"text":"Er sagte \"hallo\" und ging\\ – mit Tab:\tEnde","prio":2,"tags":["a","b"]}

--arg name wert übergibt Text, --argjson echtes JSON (Zahlen, true, Listen). jq schützt ", \ und Steuerzeichen selbst. Damit baust du notes-add neu:

cat > ~/sh-lab/werkzeug/bin/notes-add <<'EOF'
#!/usr/bin/env bash
# notes-add – legt eine Notiz an und gibt ihre ID aus: notes-add Text der Notiz
set -euo pipefail
source "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/../lib/lib.sh"
need curl jq
(($# > 0)) || die "Aufruf: $PROG Text der Notiz" 2
key="${NOTES_API_KEY:?fehlt – source ~/sh-lab/setup/env.sh}"

antwort=$(jq -n --arg t "$*" '{text: $t}' \
  | curl -fsS -A "notes-add" -X POST -H "X-API-Key: $key" \
    -H 'Content-Type: application/json' -d @- "$(notes_url)/notes") \
  || die "Anlegen gescheitert"
jq -r '.id' <<<"$antwort"
EOF
shellcheck -x ~/sh-lab/werkzeug/bin/notes-add && echo sauber
id=$(notes-add 'Er sagte "hallo"')
curl -s $NOTES_URL/notes | jq -r --arg id "$id" '.[] | select(.id == $id) | .text'
grep 'notes-add$' "$NOTES_LOG" | tail -1 | awk '{print $4, $5, $7, $10}'

Erwartet:

sauber
Er sagte "hallo"
"POST /notes 201 notes-add
  • -d @- liest den Inhalt der Anfrage von stdin – das JSON kommt aus der Pipe, nie steht es in einer Befehlszeile.
  • <<<"$antwort" ist ein Here-String: Der Text wird zu stdin von jq.
  • notes-add gibt jetzt nur noch die ID aus. So taugt es für id=$(notes-add …).

Fortschritt speichern? Kostenlos registrieren

Drill 4: Metriken lesen

notes-api liefert unter /metrics Kennzahlen im Textformat von Prometheus – kein JSON, also wieder ein Fall für grep und awk:

curl -s $NOTES_URL/metrics | grep -E '^notes_(db_up|build_info)'
curl -s $NOTES_URL/metrics \
  | awk -F'[{}]' '/^notes_http_requests_total/ {split($3, w, " "); s += w[1]}
    END {print "Anfragen seit Start:", s}' | sed -E 's/[0-9]+$/…/'

Erwartet:

notes_build_info{store="postgres",version="0.4.0"} 1
notes_db_up 1
Anfragen seit Start: …

-F'[{}]' teilt an geschweiften Klammern: Feld 2 sind die Labels, Feld 3 der Wert. split() zerlegt Feld 3 noch einmal an Leerzeichen.

Fortschritt speichern? Kostenlos registrieren

Drill 5: notes-export

cat > ~/sh-lab/werkzeug/bin/notes-export <<'EOF'
#!/usr/bin/env bash
# notes-export – schreibt alle Notizen als CSV nach stdout
set -euo pipefail
source "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/../lib/lib.sh"
need curl jq
echo '"id","text"'
curl -fsS -A notes-export "$(notes_url)/notes" | jq -r '.[] | [.id, .text] | @csv'
EOF
chmod +x ~/sh-lab/werkzeug/bin/notes-export
shellcheck -x ~/sh-lab/werkzeug/bin/notes-export && echo sauber
notes-export > notes.csv
head -1 notes.csv
grep -F 'hallo' notes.csv | cut -d, -f2-

Erwartet:

sauber
"id","text"
"Er sagte ""hallo"""

@csv setzt jedes Feld in Anführungszeichen und verdoppelt Anführungszeichen im Text – so wie Tabellenprogramme es erwarten. Für Tabulatoren gibt es @tsv, für die Shell @sh.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

notes-add Kontrollpunkt Tag 8 | grep -cE '^[0-9a-f-]{36}$'

Erwartet: eine ID im UUID-Format.

1
curl -s $NOTES_URL/notes | jq -r '.[] | select(.text == "Kontrollpunkt Tag 8") | .text'

Erwartet:

Kontrollpunkt Tag 8
jq -n --arg x 'a"b' '$x | length'

Erwartet:

3

Challenge

Schreib notes-find wort: Es listet die Texte aller Notizen, die das Wort enthalten, ohne Rücksicht auf Groß- und Kleinschreibung.

Hinweis: In jq prüft test(muster; "i") einen regulären Ausdruck ohne Beachtung der Schreibweise. Das Wort gehört mit --arg hinein, nicht in den Filtertext.

Lösung

cat > ~/sh-lab/werkzeug/bin/notes-find <<'EOF'
#!/usr/bin/env bash
# notes-find – Notizen mit einem Wort finden: notes-find wort
set -euo pipefail
source "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/../lib/lib.sh"
need curl jq
(($# == 1)) || die "Aufruf: $PROG wort" 2
curl -fsS -A notes-find "$(notes_url)/notes" \
  | jq -r --arg w "$1" '.[] | select(.text | test($w; "i")) | .text'
EOF
chmod +x ~/sh-lab/werkzeug/bin/notes-find
shellcheck -x ~/sh-lab/werkzeug/bin/notes-find && echo sauber
notes-find HALLO
notes-find einkaufen | sort

Erwartet:

sauber
Er sagte "hallo"
Einkaufen:   Milch und  Brot
Einkaufen: Milch und Brot

Mit "…$1…" im Filter könnte ein Wort wie ") | halt_error den Filter verändern – mit --arg bleibt es immer ein Wert.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Zeitlimits immer: curl ohne --max-time wartet im schlimmsten Fall unbegrenzt. In Skripten gehören --connect-timeout und --max-time zu jeder Anfrage.
  • Secrets nicht in die Befehlszeile: -H "Authorization: Bearer $TOKEN" sieht jeder mit ps. Besser: curl -H @datei oder eine --config-Datei mit Rechten 600.
  • jq-Versionen: Ubuntu 26.04 bringt jq 1.8. Ältere Server haben 1.6 – Funktionen wie ltrimstr, getpath oder @base32d vorher testen.