Skracacz URL w CLI: skracanie linków z terminala

Skrócenie adresu URL z terminala to jedna linia:

curl -s -X POST https://api.elido.app/v1/links \
  -H "Authorization: Bearer $ELIDO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"destination_url":"https://example.com/spring-sale"}' | jq -r .short_url

Wyświetla https://s.elido.me/ab12cd i nic więcej. curl wykonuje żądanie, jq wyodrębnia jedno pole z JSON-a, a -r usuwa otaczające cudzysłowy, dzięki czemu wartość można od razu przekazać do schowka albo innego polecenia.

Reszta tego wpisu opisuje cztery ulepszenia, które zamieniają tę linię w coś, czego naprawdę używasz: funkcję powłoki, uczciwe kody wyjścia, masowe skracanie z ograniczoną współbieżnością oraz schowek. Jeśli wolisz napisać to w języku programowania, a nie w powłoce, to samo wywołanie istnieje w Pythonie, Go oraz sześciu innych środowiskach uruchomieniowych.

Zmień je w polecenie

Alias nie może przyjmować argumentu, więc użyj funkcji. W pliku .zshrc lub .bashrc:

short() {
  [ -z "$1" ] && { echo "usage: short <url> [slug]" >&2; return 2; }

  local body
  body=$(jq -n --arg url "$1" --arg slug "${2:-}" \
    '{destination_url: $url} + (if $slug == "" then {} else {slug: $slug} end)')

  curl -s --fail-with-body -X POST https://api.elido.app/v1/links \
    -H "Authorization: Bearer $ELIDO_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $(printf %s "$1" | shasum -a 256 | cut -d' ' -f1)" \
    -d "$body" | jq -r .short_url
}

Trzy świadome decyzje.

Budowanie JSON-a za pomocą jq -n --arg, zamiast interpolacji ciągów znaków, sprawia, że adres docelowy zawierający cudzysłów albo ampersand nie psuje żądania. To powłokowy odpowiednik parametryzowanego SQL-a, a pominięcie tego kroku prowadzi do tej samej klasy błędu.

--fail-with-body to opcja, o której ludzie zapominają. Domyślnie curl kończy działanie kodem 0 dla każdej ukończonej wymiany, więc 401 przechodzi przez potok, jq wyświetla null, a skrypt działa dalej z null w miejscu, w którym powinien znajdować się link. Z tą opcją odpowiedź 4xx ustawia niezerowy status wyjścia, a treść błędu nadal można odczytać.

Idempotency-Key wyprowadzony z adresu URL sprawia, że dwukrotne uruchomienie tego samego polecenia zwraca ten sam link, zamiast tworzyć dwa. Ma to większe znaczenie w opisanej niżej sekcji o masowym skracaniu, a uzasadnienie znajduje się w tekście o limitach żądań i idempotencji.

Potrzebujesz klucza? Utwórz go w bezpłatnym planie, wyeksportuj z profilu powłoki, a funkcja zadziała w następnym nowym terminalu.

Bezpośrednio do schowka

Ostatnie kilka znaków, które sprawiają, że całość jest gotowa:

short "https://example.com/spring-sale" | tee /dev/tty | pbcopy      # macOS
short "https://example.com/spring-sale" | tee /dev/tty | xclip -sel c # Linux, X11
short "https://example.com/spring-sale" | tee /dev/tty | wl-copy     # Wayland
short "https://example.com/spring-sale" | tee /dev/tty | clip.exe    # WSL

tee /dev/tty wyświetla link i kopiuje go jednocześnie, co jest lepsze niż kopiowanie w ciemno i nadzieja, że wszystko się udało.

Masowo, bez zbierania odpowiedzi 429

Plik adresów URL, po jednym w wierszu, skracany po osiem naraz:

export -f short                      # bash; zsh users call the script directly
xargs -P 8 -I{} bash -c 'short "{}"' < urls.txt > short-urls.txt

-P 8 to cała strategia dotycząca limitu żądań: niezależnie od tego, czy plik ma pięćdziesiąt wierszy, czy pięćdziesiąt tysięcy, jednocześnie wykonywanych jest osiem żądań. Bez tego xargs uruchamia je tak szybko, jak potrafi tworzyć procesy, a API odpowiada na większość z nich statusem 429.

Dwie uwagi, o których warto wiedzieć przed użyciem tego polecenia na prawdziwym pliku. xargs -P przeplata wyniki, więc wiersze mogą przyjść w innej kolejności. Jeśli mapowanie między wejściem i wyjściem ma znaczenie, wyświetl oba:

xargs -P 8 -I{} bash -c 'printf "%s\t%s\n" "{}" "$(short "{}")"' < urls.txt > mapping.tsv

Adres URL zawierający spację albo cudzysłów nie przetrwa też -I{} bez zmiany znaczenia. W przypadku danych od użytkowników bezpieczną wersją jest xargs -0 z plikiem wejściowym rozdzielanym bajtami null. Na tym etapie prawdziwy skrypt w Pythonie jest zwykle mniej pracochłonny niż poprawne uporządkowanie cudzysłowów.

Nie zapisuj klucza w historii

ELIDO_API_KEY=abc123 short <url> umieszcza klucz w ~/.zsh_history i na liście procesów, gdzie każdy inny użytkownik komputera może go odczytać za pomocą ps.

Wyeksportuj go z profilu powłoki albo, jeszcze lepiej, pobieraj go przy uruchomieniu powłoki z magazynu sekretów:

export ELIDO_API_KEY="$(security find-generic-password -s elido -w)"      # macOS Keychain
export ELIDO_API_KEY="$(pass show elido/api-key)"                          # pass

Rotacja klucza oznacza wtedy aktualizację jednego wpisu, zamiast przeszukiwania ukrytych plików na trzech komputerach. Ta sama zasada obowiązuje po stronie serwera dowolnego zaplanowanego skryptu, a webhooki dla zdarzeń linków to sposób na odbieranie danych bez umieszczania kolejnego klucza w jakimś miejscu.

Kiedy terminal jest właściwym miejscem

Terminal jest właściwy, gdy adresy URL są już w pliku, gdy i tak pracujesz w powłoce albo gdy skracanie jest jednym z etapów większego skryptu: procesu wydania, który tworzy link dystrybucyjny, zadania CI skracającego adres URL wdrożenia podglądowego albo haka git tworzącego link do wpisu w dzienniku zmian.

To niewłaściwe miejsce do zarządzania kampanią. Foldery, tagi i porównywanie liczby kliknięć między miejscami publikacji wymagają dashboardu, a próba zrobienia tego za pomocą zapytań jq do endpointu listy to projekt, nie skrót. Rozwiązania dla deweloperów opisują możliwości API wykraczające poza tworzenie, a API i SDK opisują typowane klienty na wypadek, gdy skrypt powłoki przestanie wystarczać.

Przeczytaj serię cornerstone

Ten tekst należy do klastra inżynieryjnego. Zacznij od przewodnika po bezpłatnym API skracacza URL, który wyjaśnia kształt endpointów, a następnie przeczytaj o limitach żądań i idempotencji. Aktualną referencją jest dokumentacja API.

Powiązane wpisy na blogu

• Jak skrócić adres URL w Pythonie za pomocą biblioteki requests
• Jak skrócić adres URL w PowerShellu za pomocą Invoke-RestMethod
• Jak sprawdzić, dokąd prowadzi krótki URL, zanim go klikniesz
• Krótkie linki jako Terraform: deklaratywne zarządzanie linkami