Імпортер міграції з TinyURL: як працює і які в нього прогалини

Імпортер міграції з TinyURL приймає токен API, цільовий домен Elido та стратегію конфліктів, а потім копіює ваші посилання TinyURL в Elido як одне фонове завдання. У нього є один серйозний відомий дефект: він викликає GET /aliases на api.tinyurl.com, а цього шляху немає в опублікованому API TinyURL. Ця стаття розповідає, що робить імпортер, що ми перевірили, а що ні.

Якщо вам потрібна інструкція з планування переїзду з TinyURL (що можна переспрямувати, зіставлення CSV, чекліст переходу), читайте Міграція з TinyURL. Тут інженерний бік.

Відома помилка

Запит сторінки в імпортері будує такий виклик:

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

і очікує у відповідь {"data": [{alias, url, title, tags}], "meta": {"total", "has_more"}}.

Специфікація OpenAPI TinyURL (доступ 2026-10-02) не визначає шляху /aliases. Перелік - це GET /urls/{type}, де type дорівнює available або archived, з необов'язковими фільтрами from, to і search (з префіксом alias: або tag:). Специфікація не визначає параметрів page чи per_page і жодних лімітів запитів. Операції з аліасами живуть під /alias/{domain}/{alias}.

Отже, контракт пагінації в нашому коді ніколи не брався з TinyURL. Наш юніт-тест віддає написану вручну відповідь такої форми й проходить, що доводить лише збіг парсера з нашим припущенням і нічого про TinyURL. Ми не запускали імпортер на живому акаунті TinyURL, бо для цього потрібен токен платного плану. Доти не плануйте міграцію навколо нього. Виправлення відстежується в нашому внутрішньому беклозі: перейти на /urls/available (і /urls/archived за прапорцем), проходити вікнами from/to, парсити обережно й тестувати на справжній знятій відповіді. Чи містить реальна відповідь список, чи один об'єкт, специфікація залишає неясним.

Що робить воркер після отримання сторінки

Сторінка інтеграцій у DEMO-просторі із синтетичними даними. Міграція з TinyURL запускається звідси.

Усе після HTTP-виклику не залежить від питання з endpoint. Цю частину ми можемо стверджувати за кодом.

• Старт. POST з token, target_domain_id і необов'язковим conflict_strategy. Обробник відхиляє порожній токен, відсутній домен і будь-яку стратегію поза suffix, skip, fail, потім відповідає 202 із завданням і запускає воркер у фоновій горутині, відокремленій від запиту.
• Для кожного посилання. Рядок без URL або без аліаса рахується невдалим із причиною. Інакше аліас стає slug, призначення й заголовок копіюються (заголовок обрізається до 200 символів), а теги копіюються з доданим imported:tinyurl.
• Прогрес. Лічильники скидаються в рядок завдання кожні 50 посилань. На завдання журналюється щонайбільше 1000 рядків помилок.
• Помилки автентифікації й ліміту. 401 або 403 завершує завдання невдало з повідомленням «перевірте bearer-токен», 429 - як перевищення ліміту. Повторних спроб чи затримок немає: завдання зупиняється.

Правила конфліктів

Список посилань у DEMO-просторі. Імпортовані посилання мають тег imported:tinyurl, тож партію можна відфільтрувати для перегляду.

Перед кожною вставкою воркер робить один індексований пошук за (domain, slug).

• suffix (типово) пробує alias-2, alias-3 до alias-50 і завершує рядок невдало, якщо всі зайняті.
• skip не чіпає наявне посилання Elido й записує вихідний рядок у журнал.
• fail завершує завдання невдало на першому конфлікті.

TinyURL називає їх аліасами, Elido - slug. Це те саме: символи після хоста. Якщо ваш цільовий домен порожній, аліаси переносяться без змін.

Ліміти

Один спільний набір констант, який використовують усі вендори міграції: 50 000 посилань за запуск, бюджет 30 хвилин, прогрес кожні 50 посилань, 1000 журналованих помилок.

Варто знати про дві поведінки. Коли досягнуто ліміту 50 000, цикл просто зупиняється, і завдання завершується; воно не падає й не просить звертатися до когось. Порівняйте підсумкові лічильники із загальною кількістю в джерелі. Коли 30-хвилинний бюджет вичерпано, завдання позначається невдалим із кількістю імпортованого на цей момент.

Воркер живе всередині api-core. Деплой або збій посеред запуску його вбиває, а перевірка, що працює кожні п'ять хвилин, переводить завдання без прогресу 30 хвилин у failed. Збереженого курсора немає, тож завдання запускають заново. Повторний запуск безпечний при suffix або skip, хоча при suffix він створить копії з -2 для посилань, які перший запуск уже записав, тому для повторного запуску віддавайте перевагу skip.

Обробка токена

Токен іде з тіла запиту в горутину й нікуди більше. Рядок завдання не фіксує токена, і нічого не шифрується у спокої, бо нічого не зберігається. Тіло запиту читається з обмеженням 4 КБ.

Чого код не робить: він не перевіряє токен перед стартом і не перевіряє план. Поганий токен проявляється як невдале завдання після першого запиту, а не як помилка форми. Попередні версії цієї статті описували крок попередньої перевірки через endpoint доменів. Цього кроку в коді немає, і в специфікації TinyURL такого шляху теж немає.

Що не мігрується

• Історія кліків. Імпортер читає лише поля посилань. Нові кліки рахуються з моменту, коли посилання стає активним в Elido.
• Стилізація QR, шаблони, налаштування брендованого домену. Не читаються. Брендований хост - окремий крок: додайте його як домен Elido й змініть DNS, це описано в власні домени для коротких посилань.
• Посилання без акаунта. Жоден токен не може їх перелічити.

Імпортер не створює домен за вас, не обробляє поле domain з TinyURL і не має власного завантаження CSV. Для переїздів через файли скористайтеся формою масового імпорту або інструкцією в масовий імпорт із Google Sheets.

Тестування і обхід

Далі два практичні розділи. Тестування імпортера. Переїзд без нього.

Безпечний спосіб перевірити імпорт

Коли endpoint виправлять, або якщо ви тестуєте імпортер самі до того, робіть це на малому. Створіть тимчасовий робочий простір, додайте порожній домен і спершу запустіть завдання зі стратегією fail. Порожній домен означає відсутність конфліктів, тож будь-яка невдача - це проблема парсингу чи автентифікації, а не колізія. Потім порівняйте три числа: кількість у джерелі в TinyURL, total, яке повідомляє завдання, і суму лічильників імпортованих, пропущених та невдалих. Оскільки воркер бере meta.total з відповіді, яку очікує, розбіжність між total і вашою реальною кількістю - перша ознака, що форма відповіді відрізняється від припущеної парсером.

Далі відфільтруйте список посилань за imported:tinyurl і відкрийте десять посилань навмання. Звірте призначення, slug і заголовок з TinyURL. Після цього для будь-якого повторного запуску перемкніться на skip.

Як експортувати з TinyURL без імпортера

Задокументований виклик переліку - GET /urls/available з bearer-токеном, а для архівних посилань - GET /urls/archived. Звужуйте результат датами from і to, якщо акаунт великий, оскільки специфікація не дає параметрів сторінок. Спершу запишіть вивід у файл, зведіть його до destination, slug, title і завантажте через форму масового імпорту. Подробиці цього зіставлення є в посібнику. Реальну форму відповіді ми теж не перевіряли, тож перш ніж писати скрипти, огляньте одну відповідь вручну.

Що буде далі

Послідовність така: виправити endpoint, додати справжню зняту відповідь як тестову фікстуру, а тоді перевірити кожну цифру в посібнику і на цільовій сторінці міграції. Пагінацію й реальний ліміт запитів треба заміряти знову на живому акаунті, бо специфікація не дає жодного. Якщо вам потрібно піти з TinyURL раніше, порівняйте варіанти в Elido проти TinyURL та альтернативах TinyURL і скористайтеся шляхом через CSV.

Читайте також у блозі

• Міграція з TinyURL: що переноситься, що лишається, що ламається
• Випуск міграції з Bitly
• Випуск міграції з Rebrandly
• Випуск міграції з Short.io
• Короткі посилання як Terraform