CLI de raccourcisseur d'URL : raccourcir des liens depuis le terminal

Raccourcir une URL depuis le terminal tient en une seule ligne :

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

Cette commande affiche https://s.elido.me/ab12cd et rien d'autre. curl effectue la requête, jq extrait un champ du JSON et -r supprime les guillemets environnants afin que la valeur puisse être envoyée directement vers le presse-papiers ou une autre commande.

Le reste de cet article présente les quatre améliorations qui transforment cette ligne en outil réellement utilisable : une fonction shell, des codes de sortie fiables, le traitement par lots avec une concurrence limitée et le presse-papiers. Si vous préférez l'écrire dans un langage plutôt qu'en shell, le même appel existe en Python, en Go et dans six autres environnements d'exécution.

En faire une commande

Un alias ne peut pas prendre d'argument, utilisez donc une fonction. Dans .zshrc ou .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
}

Trois choix délibérés se trouvent dans cette fonction.

Construire le JSON avec jq -n --arg plutôt qu'avec une interpolation de chaîne signifie qu'une destination contenant un guillemet ou une esperluette ne casse pas la requête. C'est l'équivalent shell du SQL paramétré, et l'omettre relève de la même catégorie de bug.

--fail-with-body est l'option que beaucoup oublient. Par défaut, curl se termine avec le code 0 pour tout échange terminé, donc une réponse 401 traverse le pipeline, jq affiche null et le script continue avec null à la place du lien. Avec cette option, une réponse 4xx définit un état de sortie non nul et vous obtenez toujours le corps de l'erreur à lire.

La clé Idempotency-Key dérivée de l'URL signifie que l'exécution de la même commande deux fois renvoie le même lien au lieu d'en créer deux. C'est encore plus important dans la section consacrée aux lots ci-dessous, et le raisonnement est expliqué dans les limites de débit et l'idempotence.

Besoin d'une clé ? Créez-en une avec le forfait gratuit, exportez-la depuis votre profil shell et la fonction sera opérationnelle dans votre prochain terminal.

Directement dans le presse-papiers

Voici les quelques derniers caractères qui donnent l'impression que tout est terminé :

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 affiche le lien et le copie en même temps, ce qui vaut mieux que de copier à l'aveugle en espérant que tout se soit bien passé.

Traiter des lots sans accumuler les réponses 429

Un fichier d'URL, une par ligne, raccourcies huit à la fois :

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

-P 8 constitue toute la stratégie de limitation de débit : huit requêtes en cours, que le fichier contienne cinquante lignes ou cinquante mille. Sans cette option, xargs les exécute aussi vite qu'il peut créer les processus et l'API répond 429 à la plupart d'entre elles.

Deux précautions méritent d'être connues avant d'utiliser cette commande sur un vrai fichier. xargs -P entrelace les sorties, les lignes peuvent donc arriver dans le désordre ; si la correspondance entre entrée et sortie compte, affichez les deux :

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

Par ailleurs, une URL contenant un espace ou un guillemet ne survivra pas à -I{} sans échappement. Pour toute donnée fournie par un utilisateur, xargs -0 avec un fichier d'entrée délimité par des caractères nuls est la version sûre. À ce stade, un vrai script en Python demande généralement moins de travail que de régler correctement les guillemets.

Garder la clé hors de l'historique

ELIDO_API_KEY=abc123 short <url> place la clé dans ~/.zsh_history et dans la liste des processus, où n'importe quel autre compte de la machine peut la lire avec ps.

Exportez-la plutôt depuis votre profil shell ou, mieux encore, récupérez-la dans un coffre de secrets au démarrage du shell :

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

Faire tourner une clé signifie alors mettre à jour une seule entrée au lieu de rechercher dans les fichiers cachés de trois machines. Le même principe s'applique au côté serveur de tout script que vous planifiez, et les webhooks pour les événements de lien sont la solution pour récupérer des données sans qu'une autre clé ne vive quelque part.

Quand le terminal est le bon endroit

C'est le bon endroit lorsque les URL se trouvent déjà dans un fichier, lorsque vous êtes déjà dans un shell ou lorsque le raccourcissement constitue une étape d'un script plus large : un processus de publication qui génère un lien de diffusion, une tâche CI qui raccourcit l'URL d'un déploiement d'aperçu, ou un hook Git qui produit un lien pour une entrée du changelog.

C'est le mauvais endroit pour gérer une campagne. Les dossiers, les tags et la comparaison du volume de clics entre les emplacements nécessitent un tableau de bord, et essayer de le faire avec des requêtes jq contre un endpoint de liste devient un projet plutôt qu'un raccourci. Les solutions pour les développeurs présentent ce que l'API expose au-delà de la création, et l'API et les SDK présentent les clients typés à utiliser lorsqu'un script shell ne suffit plus.

Lire la série pilier

Cet article appartient au cluster ingénierie. Commencez par le guide de l'API de raccourcissement d'URL gratuit pour comprendre la forme de l'endpoint, puis consultez les limites de débit et l'idempotence. La référence à jour est la documentation de l'API.

Articles connexes du blog

• Comment raccourcir une URL en Python avec la bibliothèque requests
• Comment raccourcir une URL en PowerShell avec Invoke-RestMethod
• Comment voir où mène une URL courte avant de cliquer
• Les liens courts comme Terraform : gestion déclarative des liens