Linux Command Line & Bash Scripting Mastery · Lekcja

Korzystanie z REST API za pomocą curl i jq

Łącz żądania curl z jq, aby w skryptach wyodrębniać, stronicować i przekształcać odpowiedzi działających API.

Lekcja 3 z 413 kroki

Korzystanie z REST API za pomocą curl i jq to bezpłatna lekcja Linux Command Line & Bash Scripting Mastery na CoddyKit. To lekcja 3 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej Linux Command Line & Bash Scripting Mastery, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs Linux Command Line & Bash Scripting Mastery zawiera 4 lekcji w sumie.

Dlaczego curl + jq to tak skuteczne połączenie

Interfejsy REST API zwracają JSON. curl pobiera surową odpowiedź, a jq wycina z niej dane, filtruje je i zmienia ich strukturę — wszystko w jednym potoku. Nie potrzeba skryptu w Pythonie, Postmana ani pliku pośredniego.

curl obsługuje HTTP: metody, nagłówki, uwierzytelnianie i przekierowania.
jq obsługuje JSON: filtrowanie, mapowanie, przekształcanie i formatowanie.
Połączenie ich potokiem tworzy zwięzłe, łatwe do komponowania przepływy pracy z API.

W tej lekcji umiejętność ta zostanie przedstawiona od podstaw, aż po praktyczne wzorce stronicowania i skryptów.

Podstawowy potok curl do jq

Najprostszy wzorzec polega na przekazaniu wyniku curl bezpośrednio do jq. Proszę użyć -s (trybu cichego), aby ukryć miernik postępu curl i przekazać do jq wyłącznie treść JSON.

-s — tryb cichy, bez paska postępu.
. — filtr tożsamości jq; formatuje pełną odpowiedź w czytelny sposób.
-r w jq — surowy wynik (bez otaczających cudzysłowów w przypadku ciągów znaków).

#!/usr/bin/env bash
# Fetch a public endpoint and pretty-print the JSON
curl -s 'https://jsonplaceholder.typicode.com/todos/1' | jq '.'

# Extract just the title field as a plain string
curl -s 'https://jsonplaceholder.typicode.com/todos/1' | jq -r '.title'

Ustawianie nagłówków żądania i przekazywanie tokenów uwierzytelniających

Większość produkcyjnych interfejsów API wymaga nagłówka Authorization lub klucza API. Nagłówki należy przekazywać za pomocą -H, a dane wrażliwe przechowywać w zmiennych środowiskowych — nigdy nie wpisywać ich bezpośrednio w kodzie.

-H 'Authorization: Bearer $TOKEN' — wstrzykuje nagłówek uwierzytelniania.
-H 'Accept: application/json' — jawnie żąda odpowiedzi w formacie JSON.
Zmienne rozwijają się wewnątrz cudzysłowów podwójnych; wokół ciągu nagłówka należy użyć ".

#!/usr/bin/env bash
TOKEN="${GITHUB_TOKEN}"   # set in your shell environment
USER="octocat"

curl -s \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Accept: application/vnd.github+json" \
  "https://api.github.com/users/${USER}" \
| jq '{login: .login, repos: .public_repos, followers: .followers}'

Filtrowanie tablic — .[] i select()

Interfejsy API często zwracają tablice. Proszę użyć .[], aby przeiterować po każdym elemencie, a następnie select(), aby zachować tylko elementy spełniające określony warunek.

.[] — rozbija tablicę na strumień obiektów.
select(.field == value) — zachowuje tylko pasujące obiekty.
Wiele filtrów można łączyć za pomocą |.

#!/usr/bin/env bash
# Fetch all todos and keep only the completed ones
curl -s 'https://jsonplaceholder.typicode.com/todos' \
| jq '[.[] | select(.completed == true) | {id, title}]'

# Count how many are completed
curl -s 'https://jsonplaceholder.typicode.com/todos' \
| jq '[.[] | select(.completed == true)] | length'

Wyodrębnianie wielu pól za pomocą map()

map() stosuje transformację do każdego elementu tablicy i zwraca nową tablicę — odpowiednik [.[] | ...], ale czytelniejszy.

map({key: .field}) — zmienia strukturę każdego obiektu.
Połącz z @csv lub @tsv, aby wygenerować dane tabelaryczne.
Użyj -r z @csv/@tsv, aby uzyskać surowy tekst (bez cudzysłowów JSON).

#!/usr/bin/env bash
# Reshape a posts list into id + title pairs
curl -s 'https://jsonplaceholder.typicode.com/posts' \
| jq 'map({id, title: .title[0:40]})'

# Output as CSV for import into a spreadsheet
curl -s 'https://jsonplaceholder.typicode.com/posts' \
| jq -r '.[] | [.id, .userId, .title] | @csv'

Wzorzec paginacji — pętla do napotkania pustej strony

Większość interfejsów API dzieli wyniki na strony. Typowy wzorzec to pętla while, która zwiększa licznik stron i kończy działanie, gdy zwrócona tablica jest pusta.

Zapisz odpowiedź curl w zmiennej za pomocą $(curl ...).
Użyj jq 'length', aby sprawdzić, czy strona zawiera elementy.
Gromadź wyniki za pomocą jq -s (slurp) lub dopisuj je do pliku.

#!/usr/bin/env bash
# Paginate through jsonplaceholder posts (simulated: page stops at page 2
# because the API returns the full list regardless of ?_page, but the
# pattern is correct for real paginated APIs)

PAGE=1
PER_PAGE=10
OUTPUT="all_posts.json"
echo '[]' > "$OUTPUT"

while true; do
  RESPONSE=$(curl -s "https://jsonplaceholder.typicode.com/posts?_page=${PAGE}&_limit=${PER_PAGE}")
  COUNT=$(echo "$RESPONSE" | jq 'length')

  if [ "$COUNT" -eq 0 ]; then
    echo "No more pages. Stopping at page $((PAGE - 1))."
    break
  fi

  # Merge new items into the accumulated JSON array
  CURRENT=$(cat "$OUTPUT")
  echo "$CURRENT" "$RESPONSE" | jq -s '.[0] + .[1]' > "$OUTPUT"
  echo "Page $PAGE: fetched $COUNT items."
  PAGE=$((PAGE + 1))
done

echo "Total collected: $(jq 'length' "$OUTPUT")"

Paginacja za pomocą nagłówka Link (styl GitHub)

GitHub i wiele innych interfejsów API używa nagłówka odpowiedzi Link, aby podać adres URL następnej strony. Należy przeanalizować ten nagłówek, zamiast zgadywać adres URL.

curl -i dołącza nagłówki odpowiedzi do stdout; można też użyć -D -, aby zrzucić nagłówki do stdout.
Przeanalizuj nagłówek Link: <url>; rel="next" za pomocą grep i sed.
Wykonuj pętlę, dopóki nie zabraknie odsyłacza rel="next".

#!/usr/bin/env bash
# Follow Link-header pagination (GitHub repos example)
# Requires GITHUB_TOKEN in environment
TOKEN="${GITHUB_TOKEN}"
NEXT_URL="https://api.github.com/users/torvalds/repos?per_page=5"
ALL_REPOS="[]"

while [ -n "$NEXT_URL" ]; do
  # Capture full response (headers + body) to a temp file
  TMPFILE=$(mktemp)
  curl -sD "$TMPFILE" \
    -H "Authorization: Bearer ${TOKEN}" \
    -H "Accept: application/vnd.github+json" \
    "$NEXT_URL" \
  | {
      BODY=$(cat)
      ALL_REPOS=$(echo "$ALL_REPOS" "$BODY" | jq -s '.[0] + .[1]')
      echo "$ALL_REPOS" > /tmp/repos_acc.json
    }

  # Extract next URL from Link header
  NEXT_URL=$(grep -i '^link:' "$TMPFILE" \
    | sed -E 's/.*<([^>]+)>; rel="next".*/\1/;t;d')
  rm -f "$TMPFILE"
done

echo "Total repos: $(jq 'length' /tmp/repos_acc.json)"

Łączenie żądań — używanie wyniku jednego wywołania jako danych wejściowych kolejnego

Typowy przepływ pracy: pobierz listę, wyodrębnij identyfikator, a następnie pobierz szczegóły dla każdego identyfikatora. Zapisuj wartości pośrednie za pomocą podstawiania poleceń $() i przekazuj je do kolejnego adresu URL.

Wyodrębnij pojedynczą wartość za pomocą jq -r '.field'.
Iteruj po wielu identyfikatorach za pomocą jq -r '.[].id' wewnątrz pętli while read.
Używaj sleep między żądaniami, aby przestrzegać limitów zapytań.

#!/usr/bin/env bash
# Step 1: get all user IDs from the /users endpoint
# Step 2: for each user, fetch their posts and count them

curl -s 'https://jsonplaceholder.typicode.com/users' \
| jq -r '.[].id' \
| while read -r USER_ID; do
    POST_COUNT=$(curl -s "https://jsonplaceholder.typicode.com/posts?userId=${USER_ID}" \
                 | jq 'length')
    echo "User ${USER_ID}: ${POST_COUNT} posts"
    sleep 0.1   # be polite to the API
done

Żądania POST — wysyłanie danych JSON

Aby utworzyć lub zaktualizować zasoby, wyślij żądanie POST lub PUT z treścią w formacie JSON. Użyj -X POST, -H 'Content-Type: application/json' oraz -d do przekazania treści. Zbuduj dane za pomocą jq -n, aby uniknąć problemów z cudzysłowami.

jq -n --arg key value '{key: $key}' — bezpieczne podstawianie zmiennych w jq.
Przekaż skonstruowany JSON bezpośrednio do -d @- w curl (odczyt treści ze standardowego wejścia).
Natychmiast przeanalizuj odpowiedź za pomocą kolejnego filtra jq.

#!/usr/bin/env bash
TITLE="My New Post"
BODY_TEXT="Written via curl and jq."
USER_ID=1

# Build the JSON payload safely and POST it
RESPONSE=$(jq -n \
  --arg title   "$TITLE" \
  --arg body    "$BODY_TEXT" \
  --argjson userId "$USER_ID" \
  '{title: $title, body: $body, userId: $userId}' \
| curl -s \
    -X POST \
    -H 'Content-Type: application/json' \
    -d @- \
    'https://jsonplaceholder.typicode.com/posts')

echo "Created post ID: $(echo "$RESPONSE" | jq '.id')"
echo "Full response:"
echo "$RESPONSE" | jq '.'

Obsługa błędów — kody statusu HTTP i błędy API

Pomyślne połączenie HTTP nie oznacza, że wywołanie API zakończyło się powodzeniem. Sprawdź osobno kod statusu HTTP i pole błędu w formacie JSON.

curl -w '%{http_code}' dopisuje kod statusu do stdout; użyj -o, aby zapisać treść do pliku.
Porównaj kod w skrypcie i obsłuż kody 4xx/5xx w różny sposób.
Wiele interfejsów API umieszcza w treści element {"error": "..."} — sprawdź go za pomocą funkcji has() lub type w jq.

#!/usr/bin/env bash
API_URL='https://jsonplaceholder.typicode.com/todos/99999'
TMPBODY=$(mktemp)

HTTP_CODE=$(curl -s -o "$TMPBODY" -w '%{http_code}' "$API_URL")

if [ "$HTTP_CODE" -ge 200 ] && [ "$HTTP_CODE" -lt 300 ]; then
  echo "Success ($HTTP_CODE):"
  jq '.' "$TMPBODY"
elif [ "$HTTP_CODE" -eq 404 ]; then
  echo "Resource not found (404). Body:"
  jq '.' "$TMPBODY"
elif [ "$HTTP_CODE" -ge 500 ]; then
  echo "Server error ($HTTP_CODE). Retrying later."
else
  echo "Unexpected status: $HTTP_CODE"
  cat "$TMPBODY"
fi

rm -f "$TMPBODY"

Budowanie wielokrotnego użytku pomocniczej funkcji API

Umieść powtarzalny kod curl i sprawdzania błędów w funkcji powłoki. Funkcja obsługuje uwierzytelnianie, sprawdzanie statusu i wyodrębnianie danych JSON — wywołujący przekazuje tylko endpoint i filtr jq.

Zwracaj niezerowe kody zakończenia w przypadku błędów HTTP, aby wywołujący mógł użyć || lub set -e.
Przyjmuj argument zawierający filtr jq, aby ta sama funkcja obsługiwała wiele endpointów.
Dołączaj plik z tą funkcją do dowolnego skryptu, który potrzebuje dostępu do API.

#!/usr/bin/env bash
# api_get <endpoint_path> <jq_filter>
# Returns filtered JSON or exits non-zero on error.
api_get() {
  local PATH_PART="$1"
  local JQ_FILTER="${2:-.}"
  local BASE_URL='https://jsonplaceholder.typicode.com'
  local TMPBODY
  TMPBODY=$(mktemp)

  local HTTP_CODE
  HTTP_CODE=$(curl -s \
    -o "$TMPBODY" \
    -w '%{http_code}' \
    "${BASE_URL}${PATH_PART}")

  if [ "$HTTP_CODE" -lt 200 ] || [ "$HTTP_CODE" -ge 300 ]; then
    echo "[ERROR] HTTP $HTTP_CODE for ${PATH_PART}" >&2
    rm -f "$TMPBODY"
    return 1
  fi

  jq -r "$JQ_FILTER" "$TMPBODY"
  rm -f "$TMPBODY"
}

# Usage examples
api_get '/todos/1' '.title'
api_get '/posts?userId=1' '[.[] | .title]'
api_get '/users' '.[] | "\(.id) \(.name) <\(.email)>"'

Sprawdzenie wiedzy: strategia paginacji

Sprawdź, czy rozumiesz, jak obsługiwać stronicowane odpowiedzi REST API w skrypcie Bash za pomocą curl i jq.

Odpowiedz w interaktywnej lekcji

Podsumowanie lekcji: skrypty API z curl i jq

Masz teraz kompletny zestaw narzędzi do korzystania z interfejsów REST API z poziomu wiersza poleceń Bash:

Podstawowy potok: curl -s URL | jq 'filter' — fundament wszystkich działań.
Nagłówki uwierzytelniania: przekazuj tokeny za pomocą -H ze zmiennych środowiskowych, nigdy nie wpisuj ich bezpośrednio w kodzie.
Obsługa tablic: .[], select() i map() filtrują oraz zmieniają strukturę odpowiedzi API.
Paginacja: wykonuj pętlę z licznikiem stron (pusta tablica jako sygnał zakończenia) lub analizuj nagłówki Link w interfejsach API podających adres URL następnej strony.
Łączenie żądań: wyodrębniaj identyfikatory z jednej odpowiedzi i przekazuj je do kolejnego żądania wewnątrz pętli while read.
POST z bezpiecznymi danymi: buduj treść JSON za pomocą jq -n --arg i przekazuj ją potokiem do -d @- w curl.
Obsługa błędów: oddzielaj status HTTP (-w '%{http_code}') od błędów na poziomie API znajdujących się w treści odpowiedzi.
Pomocnicza funkcja wielokrotnego użytku: umieść powtarzalny kod w funkcji powłoki, aby skrypty pozostały zwięzłe i zgodne z zasadą DRY.

Połącz te wzorce, a zautomatyzujesz dowolny przepływ pracy z JSON API całkowicie z poziomu powłoki — bez konieczności używania dodatkowego środowiska uruchomieniowego.

Bezpłatny start

Ucz się Bash dzięki korepetycjom AI — za darmo

Pisz i uruchamiaj kod w przeglądarce, otrzymuj natychmiastową pomoc od korepetytora AI dostępnego 24/7 i kontynuuj naukę w sieci lub w aplikacji.

Kursy: 22
Lekcje: 88

Zacznij naukę bezpłatnie Wyświetl pełny kurs

Często zadawane pytania

Czy lekcja „Korzystanie z REST API za pomocą curl i jq” jest bezpłatna?

Tak — pełny tekst „Korzystanie z REST API za pomocą curl i jq” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu Linux Command Line & Bash Scripting Mastery, przejdź na CoddyKit PRO. Kurs Linux Command Line & Bash Scripting Mastery zawiera 4 lekcji w sumie.

Co nauczysz się w „Korzystanie z REST API za pomocą curl i jq”?

Łącz żądania curl z jq, aby w skryptach wyodrębniać, stronicować i przekształcać odpowiedzi działających API. Ćwiczysz Linux Command Line & Bash Scripting Mastery z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć Linux Command Line & Bash Scripting Mastery?

Nie wymagamy żadnego doświadczenia. Linux Command Line & Bash Scripting Mastery w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 3 z 4.

Ile czasu zajmuje lekcja „Korzystanie z REST API za pomocą curl i jq”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji Linux Command Line & Bash Scripting Mastery?

Tak. Każda lekcja Linux Command Line & Bash Scripting Mastery zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

Filtrowanie i wybieranie JSON za pomocą potoków jq
Przekształcanie i tworzenie obiektów JSON za pomocą jq
Korzystanie z REST API za pomocą curl i jq
Edycja plików konfiguracyjnych YAML za pomocą yq

← Powrót do Linux Command Line & Bash Scripting Mastery