Перевірка зовнішніх посилань на сторінку під час публікації покроково
Один вебхук, один HTTP-запит, одне рішення. Цей рукавич проводить команду headless CMS через хук, запити та випадки помилок.
Дослідницька команда Contentin ·
Визначте, що може робити в'язка
Перевірка зовнішніх посилань на сторінку всередині процесу випуску — це невелике завдання. Зберігайте його невеликим. Складна частина полягає в тому, щоб вирішити, які відповіді дозволено змінювати, оскільки граф посилань, який оновлюється щомісяця, не може сам по собі заборонити сторінку.
Ми пропонуємо, щоб в'язка попереджала, логувала та дозволяла збірці продовжуватися. Типові налаштування можуть змінюватися. Суворі блоки належать до речей, якими ви керуєте, таких як зламана розмітка або відсутній тег canonical. Дані посилань — це сигнал, а сигнали змінюються.
Запишіть це. Зробіть це до того, як почнете кодити. Політика в один рядок, наприклад "попередити редактора, позначити запис, ніколи не зупиняти деплой", заощадить довгу дискусію о 18:00 в день випуску. Вона також повідомляє наступному інженеру, які помилки були заплановані, а які були багами, що важливіше, ніж може здатися. Оглядайте її раз на квартал.
Шість кроків від кліку публікації до збереженої нотатки
1
Виберіть тригер
Підпишіться на подію публікації вашої CMS. Contentful, Sanity та Strapi можуть викликати URL, яким ви володієте, коли запис публікується, а Storyblok та Payload також пропонують вебхуки або хуки. Відфільтруйте типи контенту, які містять зовнішні або canonical URL.
2
Зведіть URL до домену
API приймає домен у q, тому https://www.example.com/blog/post?x=1 спочатку має стати example.com. Вирішіть раз, як ви ставитеся до www, і протестуйте один реальний домен на безкоштовній дії domain, перш ніж щось будувати.
3
Спочатку викличте безкоштовну дію
overview коштує нічого. Якщо відповідь буде пустою, домен може бути новим або просто невідомим нашому індексу. Це не доказ чогось поганого.
4
Витрачайте кредити лише коли спрацьовує правило
Коли ваше правило каже подивитися ближче, викличте backlinks з per=100. Це 2 кредити, незалежно від кількості рядків, тому просіть корисну сторінку рядків, а не десять малих.
5
Напишіть нотатку, а не сирій JSON
Збережіть короткий вердикт у полі вашої власної структури, а також дату перевірки. Сирі відповіді роздувають записи і шкодують, оскільки індекс рухається щомісяця.
6
Пом'якшений відмов
HTTP 401 означає, що ключ відсутній або неправильний, тому сповістіть людину. HTTP 402 означає, що кредити закінчилися. Будь-яка інша помилка: залогуйте її, пропустіть перевірку, дозвольте публікації пройти.
Де живе ключ і що має робити 402
Кожен платний запит містить ваш ключ, або в рядку запиту, або в заголовку Bearer. Віддавайте перевагу заголовку. Рядок запиту може потрапити в логи сервера та проксі-трейси, а зазвичай заголовок залишається поза ними.
Збережіть ключ як секрет у вашій хостинг-платформі, ніколи в самому записі. Редактори можуть читати будь-яке поле, яке вони можуть відкрити, але середовище функції зазвичай видно лише людям, які керують деплоями.
Де повинен жити ключ?
Ключ, який протік, може витратити баланс на вашому рахунку, тому ставтеся до нього як до пароля. Тримайте його поза репозиторієм і поза CMS, і змініть його, якщо файл журналу коли-небудь покаже його відкритим текстом.
Позначте свої логи назвою хука. Витрати тоді легко відстежити до однієї функції, навіть коли кілька хуків ділять один обліковий запис.
Чи може no-code інструмент викликати запит?
Так, коли інструмент має крок звичайного HTTP-запиту. Багато конструкторів автоматизації можуть надсилати GET з рядком запиту і читати JSON назад, тому безкоштовна дія overview не потребує коду взагалі.
Почніть лише з безкоштовних дій. Потік, який спрацьовує при кожному збереженні чернетки, може витратити кредити швидше, ніж помітить редактор, тому додайте платний крок, коли безкоштовні запити тихо працювали протягом деякого часу.
Що має викликати 402?
402 означає, що баланс порожній. Це нічого не каже про сторінку. Пропустіть платну перевірку, залогуйте подію та надішліть одне сповіщення тому, хто поповнює рахунок, потім дозвольте публікації пройти.
Встановіть сигнал рівня балансу значно вище нуля, щоб попередження надходило, поки ще є час поповнити. Цикл повторних спроб тут не допоможе, оскільки кожен запит буде падати однаково, доки хтось не додасть кредит. Таблиця витрат містить цифри.
Протестуйте два запити з термінала
Запустіть їх один раз проти домену, який ви знаєте, перш ніж хук зробить це за вас. Прочитайте поле _credits у другій відповіді.
bash
# free, no key
curl -s "https://contentin.app/api.php?action=overview&q=example.com"
# 2 credits, key in a header
curl -s -H "Authorization: Bearer sk_live_..." \
"https://contentin.app/api.php?action=backlinks&q=example.com&per=100"
Який домен йде в параметр q
API приймає чистий домен у q, тому повний URL спочатку має бути зведений. Напишіть це скорочення раз, в одній функції. Потім протестуйте його на реальних URL.
Відносні посилання та відсутні схеми — це випадки, які зазвичай ламають хук. Скорочення, яке працює на чистих прикладах, все одно може не спрацювати на брудних URL, які редактор вставляє о 17:00.
Чи змінює www відповідь?
Може, і чесний спосіб дізнатися — запитати. Запустіть безкоштовну дію domain на обох формах одного сайту, який ви знаєте, а потім порівняйте дві відповіді поруч.
Яке б правило ви не обрали, запишіть його в коментарі коду, щоб наступному інженеру не довелося вгадувати. Коментар нічого не коштує і заощадить довгу дискусію пізніше.
Щодо перенаправлень і піддоменів?
Надсилайте хост, на який фактично потрапляють ваші читачі, а не посилання, який редактор вставив роки тому. Якщо це посилання перенаправляє, зведіть кінцеву адресу і ігноруйте стрибок посередині.
Блог на власному піддомені — це судження. Вирішіть заздалегідь, чи перевіряється він самостійно, чи разом зі своїм батьківським доменом, і запишіть цей вибір поруч із правилом.
Чек-лист перед випуском для хука
Хук спрацьовує лише при публікації, а не при кожному збереженні чернетки
URL зводиться до чистого домену перед викликом
Безкоштовні дії запускаються першими, а кредити витрачаються лише за прапорцем
401 та 402 мають своє власне сповіщення та своє власне повідомлення
Встановлено таймаут, тому повільний API ніколи не зупинить редактора
Збережена нотатка містить дату, тому ніхто не помилить її за дані в реальному часі
Один і той самий запис, опублікований двічі, не рахується двічі (див. список міфів)
Хтось прочитав таблицю витрат для вашого місячного обсягу
Що логувати, а що залишати поза записом
Рядок журналу для кожної пропущеної перевірки — найдешевший аудиторський слід, який ви можете створити. Запишіть ID запису, домен, який ви надіслали, код статусу та чи запустився платний крок. Зазвичай цього достатньо.
Збережена нотатка залишається короткою і датованою, як кажуть кроки вище. Повні відповіді належать у ваші власні логи, якщо вони належать кудись, оскільки вони великі і шкодують.
Які поля належать до рядка журналу?
Почніть з ID запису та версії публікації. Повторний вебхук тоді з'явиться як та сама пара двічі, що саме те, що ви хочете бачити.
Додайте домен, назву дії, код статусу та час, коли почався запит. Залиште сам ключ поза увагою, оскільки лог, який його тримає, стає другим місцем, де живуть секрети.
Як довго має жити збережена нотатка?
Стільки ж, скільки живе запис, якщо новіша перевірка не замінює її. Важливо, щоб читач міг зрозуміти, скільки років нотатці, оскільки нотатка з минулого місяця читається як дані в реальному часі.
Посібник з полів оцінки показує чотири поля, які ми пропонуємо для цієї нотатки, включаючи дату.
Протестуйте хук на staging перед запуском
Запустіть ці чотири перевірки, перш ніж хтось покладатиметься на хук.
1
Відтворіть одну минулу публікацію
Запустіть хук з копією запису, який ви вже опублікували. Порівняйте збережену нотатку з тим, що ви очікували, і підтвердіть, що той самий запис не був зарахований двічі.
2
Спробуйте домен, зареєстрований нещодавно
Використовуйте домен партнера, який є новим для вас. Пуста або тонка відповідь має бути збережена як невідома, а не як відмова, і нотатка має казати про це простими словами.
3
Свідомо викличте 402
Запустіть хук з ключем на тестовому обліковому записі, баланс якого ви порожнили. Підтвердіть, що пропуск, рядок журналу та сповіщення всі спрацьовують, і що публікація все одно досягає збірки.
4
Прочитайте повідомлення, яке бачить редактор
Попросіть когось із зовні команди прочитати текст помилки вголос. Якщо вони не можуть сказати, що робити далі, переписуйте повідомлення перед днем випуску. Постмортем показує, що коштувало неясне повідомлення одній вигаданій команді.
Що хук не бачить
Наш індекс оновлюється приблизно раз на місяць. Посилання, додане після останнього оновлення, не покажеться, а посилання, видалене з тих пір, може все ще з'явитися. Для доказу в той же день використовуйте звіт Links у Google Search Console.
