Importer di migrazione TinyURL: come funziona e i suoi limiti

L'importer di migrazione TinyURL prende un token API, un dominio Elido di destinazione e una strategia di conflitto, poi copia i tuoi link TinyURL in Elido come un unico job in background. Ha un difetto noto serio: chiama GET /aliases su api.tinyurl.com, e quel percorso non è nell'API pubblicata di TinyURL. Questo articolo spiega cosa fa l'importer, cosa abbiamo verificato e cosa no.

Se ti serve la guida pratica per pianificare un passaggio da TinyURL (cosa si può reindirizzare, mappatura CSV, checklist di cutover), leggi Migrare da TinyURL. Questo è il lato ingegneristico.

Il bug noto

Il recupero della pagina da parte dell'importer costruisce questa richiesta:

GET https://api.tinyurl.com/aliases?page=1&per_page=100
Authorization: Bearer <token>

e si aspetta in risposta {"data": [{alias, url, title, tags}], "meta": {"total", "has_more"}}.

La specifica OpenAPI di TinyURL (consultata il 2026-10-02) non definisce alcun percorso /aliases. L'elenco è GET /urls/{type}, dove type è available o archived, con filtri facoltativi from, to e search (un prefisso alias: o tag:). La specifica non definisce parametri page o per_page né rate limit. Le operazioni sugli alias stanno sotto /alias/{domain}/{alias}.

Quindi il contratto di paginazione nel nostro codice non è mai stato preso da TinyURL. Il nostro test unitario serve una risposta scritta a mano in quella forma e passa, il che dimostra che il parser corrisponde alla nostra ipotesi e non dice nulla su TinyURL. Non abbiamo eseguito l'importer su un account TinyURL reale, perché serve un token di un piano a pagamento. Finché non lo facciamo, non pianificare una migrazione basandoti su di esso. La correzione è tracciata nel nostro backlog interno: passare a /urls/available (e /urls/archived dietro un flag), scorrere finestre from/to, fare il parsing in modo difensivo e testare con una risposta reale catturata. Se la risposta reale contenga una lista o un singolo oggetto è qualcosa che la specifica lascia poco chiaro.

Cosa fa il worker dopo aver ricevuto una pagina

La pagina delle integrazioni in un workspace DEMO con dati sintetici. La migrazione da TinyURL si avvia da qui.

Tutto ciò che viene dopo la chiamata HTTP è indipendente dalla questione dell'endpoint. Questa parte possiamo affermarla dal codice.

• Avvio. POST con token, target_domain_id e conflict_strategy facoltativo. Il gestore rifiuta un token vuoto, un dominio mancante e qualsiasi strategia diversa da suffix, skip, fail, poi risponde 202 con il job ed esegue il worker in una goroutine in background staccata dalla richiesta.
• Per ogni link. Una riga senza URL o senza alias viene contata come fallita con un motivo. Altrimenti l'alias diventa lo slug, destinazione e titolo vengono copiati (titolo troncato a 200 caratteri), e i tag vengono copiati con imported:tinyurl aggiunto in coda.
• Progressi. I contatori vengono scritti sulla riga del job ogni 50 link. Vengono registrate al massimo 1.000 righe di errore per job.
• Errori di autenticazione e di frequenza. Un 401 o 403 fa fallire il job con il messaggio "check the bearer token", un 429 lo fa fallire come limitato per frequenza. Non c'è retry né backoff: il job si ferma.

Regole sui conflitti

L'elenco dei link in un workspace DEMO. I link importati portano il tag imported:tinyurl, così puoi filtrare un lotto per la revisione.

Prima di ogni inserimento il worker fa una ricerca indicizzata per (domain, slug).

• suffix (predefinito) prova alias-2, alias-3, fino a alias-50, e fa fallire la riga se sono tutti occupati.
• skip lascia stare il link Elido esistente e registra la riga sorgente.
• fail fa fallire il job al primo conflitto.

TinyURL li chiama alias, Elido li chiama slug. È la stessa cosa: i caratteri dopo l'host. Se il tuo dominio di destinazione è vuoto, gli alias passano invariati.

Limiti

Un unico insieme di costanti, usato da ogni fornitore di migrazione: 50.000 link per esecuzione, un budget di 30 minuti, progressi ogni 50 link, 1.000 errori registrati.

Vale la pena conoscere due comportamenti. Quando si raggiunge il limite di 50.000, il ciclo si ferma semplicemente e il job si completa; non fallisce e non ti dice di contattare nessuno. Confronta i conteggi finali con il totale della tua sorgente. Quando il budget di 30 minuti si esaurisce, il job viene segnato come fallito con il numero di link importati fino a quel momento.

Il worker vive dentro api-core. Un deploy o un crash a metà esecuzione lo uccide, e uno sweep che gira ogni cinque minuti porta a failed i job senza progressi da 30 minuti. Non c'è un cursore salvato, quindi riavvii il job. Rieseguire è sicuro con suffix o skip, anche se con suffix creerà copie -2 dei link che la prima esecuzione aveva già scritto, quindi per una riesecuzione preferisci skip.

Gestione del token

Il token passa dal corpo della richiesta alla goroutine e da nessun'altra parte. La riga del job non registra alcun token, e nulla è cifrato a riposo perché nulla viene memorizzato. Il corpo della richiesta viene letto con un limite di 4 KB.

Ciò che il codice non fa: non convalida il token prima di partire e non controlla il piano. Un token errato emerge come job fallito dopo la prima richiesta, non come errore del modulo. Le versioni precedenti di questo articolo descrivevano un passaggio di preflight su un endpoint dei domini. Quel passaggio non esiste nel codice, e nemmeno la specifica di TinyURL ha un percorso del genere.

Cosa non viene migrato

• Storico dei clic. L'importer legge solo i campi dei link. I nuovi clic contano dal momento in cui un link è attivo in Elido.
• Stile dei QR, template, impostazioni del dominio brandizzato. Non letti. Un hostname brandizzato è un passaggio separato: aggiungilo come dominio Elido e cambia il DNS, come spiegato in domini personalizzati per gli short link.
• Link senza account. Nessun token può elencarli.

L'importer non crea il dominio per te, non gestisce un campo domain di TinyURL e non ha un proprio caricamento CSV. Per i passaggi basati su file usa il modulo di importazione in blocco o la guida in importazione in blocco da Google Sheets.

Testarlo e aggirarlo

Seguono due sezioni pratiche. Testare l'importer. Migrare senza di esso.

Un modo sicuro per controllare un'importazione

Quando l'endpoint sarà corretto, o se testi tu l'importer prima di allora, fallo in piccolo. Crea un workspace usa e getta, aggiungi un dominio vuoto ed esegui prima il job con la strategia fail. Un dominio vuoto significa nessun conflitto, quindi qualsiasi fallimento è un problema di parsing o di autenticazione e non una collisione. Poi confronta tre numeri: il conteggio sorgente in TinyURL, il total che il job riporta e i contatori di importati più saltati più falliti. Poiché il worker prende meta.total dalla risposta che si aspetta, una discrepanza tra total e il tuo conteggio reale è il primo segnale che la forma della risposta differisce da quella che il parser presuppone.

Poi filtra l'elenco dei link per imported:tinyurl e apri dieci link a caso. Controlla destinazione, slug e titolo rispetto a TinyURL. Dopodiché passa a skip per qualsiasi riesecuzione.

Come esportare da TinyURL senza l'importer

La chiamata di elenco documentata è GET /urls/available con un bearer token, e GET /urls/archived per i link archiviati. Restringi il risultato con datetime from e to se l'account è grande, dato che la specifica non fornisce parametri di pagina. Scrivi l'output su un file prima di fare qualsiasi altra cosa, riducilo a destination, slug, title e caricalo con il modulo in blocco. I dettagli di quella mappatura sono nella guida pratica. Nemmeno la forma della risposta reale è stata verificata, quindi ispeziona a mano una risposta prima di scriverci uno script.

Cosa succede dopo

La sequenza è: correggere l'endpoint, aggiungere una risposta reale catturata come fixture di test, poi ricontrollare ogni cifra nella guida pratica e nella pagina di destinazione della migrazione. La paginazione e il vero limite per richiesta vanno rimisurati su un account reale, dato che la specifica non fornisce né l'una né l'altro. Se devi lasciare TinyURL prima di allora, confronta le opzioni in Elido vs TinyURL e alternative a TinyURL, e usa il percorso CSV.

Correlati sul blog

• Migrare da TinyURL: cosa si sposta, cosa resta, cosa si rompe
• Rilasciare la migrazione da Bitly
• Rilasciare la migrazione da Rebrandly
• Rilasciare la migrazione da Short.io
• Short link come Terraform