URL-Shortener-CLI: Links vom Terminal aus kürzen

Eine URL vom Terminal aus zu kürzen, ist eine Zeile:

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

Das gibt https://s.elido.me/ab12cd und sonst nichts aus. curl stellt die Anfrage, jq zieht ein Feld aus dem JSON, und -r entfernt die umschließenden Anführungszeichen, sodass der Wert direkt in die Zwischenablage oder in einen anderen Befehl gelangen kann.

Der Rest dieses Beitrags behandelt die vier Erweiterungen, die aus dieser Zeile etwas machen, das Sie tatsächlich verwenden: eine Shell-Funktion, aussagekräftige Exit-Codes, Stapelverarbeitung mit begrenzter Parallelität und die Zwischenablage. Wenn Sie lieber in einer Sprache als in der Shell schreiben, gibt es denselben Aufruf in Python, Go und sechs weiteren Laufzeitumgebungen.

Machen Sie daraus einen Befehl

Ein Alias kann kein Argument übernehmen, verwenden Sie daher eine Funktion. In .zshrc oder .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
}

Darin stecken drei bewusste Entscheidungen.

Wenn Sie das JSON mit jq -n --arg statt durch String-Interpolation erstellen, beschädigt ein Ziel mit Anführungszeichen oder einem kaufmännischen Und die Anfrage nicht. Das ist das Shell-Gegenstück zu parametrisiertem SQL; darauf zu verzichten, führt zur gleichen Fehlerklasse.

--fail-with-body ist das Flag, das viele übersehen. Standardmäßig beendet sich curl bei jedem abgeschlossenen Austausch mit 0, sodass eine 401 durch die Pipeline läuft, jq null ausgibt und ein Skript mit null an der Stelle weiterläuft, an der ein Link stehen sollte. Damit setzt ein 4xx einen Exit-Status ungleich null, und Sie erhalten weiterhin den Fehler-Body zum Lesen.

Der aus der URL abgeleitete Idempotency-Key sorgt dafür, dass derselbe Befehl zweimal ausgeführt denselben Link zurückgibt, statt zwei Links zu erstellen. Im Abschnitt zur Stapelverarbeitung weiter unten ist das noch wichtiger; die Begründung finden Sie unter Rate-Limits und Idempotenz.

Sie brauchen einen Schlüssel? Erstellen Sie einen im kostenlosen Tarif, exportieren Sie ihn aus Ihrem Shell-Profil, und die Funktion funktioniert im nächsten neuen Terminal.

Direkt in die Zwischenablage

Die letzten Kleinigkeiten, die den Aufruf fertig wirken lassen:

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 gibt den Link aus und kopiert ihn gleichzeitig, was besser ist, als blind zu kopieren und zu hoffen.

Stapelverarbeitung ohne gesammelte 429-Antworten

Eine Datei mit URLs, eine pro Zeile, die jeweils zu acht gekürzt werden:

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

-P 8 ist die gesamte Strategie für das Rate-Limit: Es sind immer acht Anfragen gleichzeitig unterwegs, egal, ob die Datei fünfzig oder fünfzigtausend Zeilen enthält. Ohne diese Begrenzung führt xargs die Befehle so schnell aus, wie es Prozesse starten kann, und die API beantwortet die meisten mit 429.

Zwei Einschränkungen sollten Sie kennen, bevor Sie das auf eine echte Datei anwenden. xargs -P verschachtelt die Ausgaben, daher können die Zeilen in falscher Reihenfolge eintreffen. Wenn die Zuordnung zwischen Ein- und Ausgabe wichtig ist, geben Sie beides aus:

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

Und eine URL mit einem Leerzeichen oder Anführungszeichen übersteht -I{} nicht ohne Escaping. Für alle von Benutzern gelieferten Werte ist xargs -0 mit einer nullterminierten Eingabedatei die sichere Variante. An diesem Punkt ist ein echtes Skript in Python meistens weniger Arbeit, als die Anführungszeichen korrekt zu behandeln.

Halten Sie den Schlüssel aus Ihrer History heraus

ELIDO_API_KEY=abc123 short <url> legt den Schlüssel in ~/.zsh_history und in der Prozessliste ab, wo jedes andere Konto auf dem Rechner ihn mit ps lesen kann.

Exportieren Sie ihn stattdessen aus Ihrem Shell-Profil oder rufen Sie ihn, noch besser, beim Start der Shell aus einem Secret-Store ab:

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

Einen Schlüssel zu rotieren bedeutet dann, einen Eintrag zu aktualisieren, statt Dotfiles auf drei Rechnern mit grep zu durchsuchen. Dasselbe Prinzip gilt für die Serverseite jedes Skripts, das Sie planen, und Webhooks für Link-Ereignisse sind das Muster, um Daten zurückzubekommen, ohne dass irgendwo ein weiterer Schlüssel liegen muss.

Wann das Terminal der richtige Ort ist

Das Terminal ist richtig, wenn die URLs bereits in einer Datei liegen, Sie sich ohnehin in einer Shell befinden oder das Kürzen ein Schritt in einem größeren Skript ist: ein Release-Prozess, der einen Distributionslink erzeugt, ein CI-Job, der die URL eines Preview-Deployments kürzt oder ein Git-Hook, der einen Link für einen Changelog-Eintrag erzeugt.

Für die Verwaltung einer Kampagne ist es der falsche Ort. Ordner, Tags und der Vergleich des Klickvolumens über verschiedene Platzierungen hinweg benötigen ein Dashboard, und der Versuch, dies mit jq-Abfragen gegen einen Listenendpunkt zu erledigen, ist ein Projekt statt einer Abkürzung. Lösungen für Entwickler zeigen, was die API über das Erstellen hinaus bereitstellt, und die API und SDKs behandeln die typisierten Clients für den Fall, dass ein Shell-Skript nicht mehr ausreicht.

Die Cornerstone-Serie lesen

Dieser Beitrag gehört zum Engineering-Cluster. Beginnen Sie mit dem Leitfaden zur kostenlosen URL-Shortener-API für den Aufbau des Endpunkts und lesen Sie danach Rate-Limits und Idempotenz. Die aktuelle Referenz finden Sie in der API-Dokumentation.

Verwandte Beiträge im Blog

• Eine URL in Python mit der requests-Bibliothek kürzen
• Eine URL in PowerShell mit Invoke-RestMethod kürzen
• Vor dem Klick sehen, wohin eine Kurz-URL führt
• Kurzlinks als Terraform: deklaratives Link-Management