ПРИМЕЧАНИЕ: Эта статья первоначально появилась на блоге Contentful Blog
Поскольку веб-приложения остаются неотъемлемой и мощной движущей силой цифровой эпохи, разработчики, заинтересованные стороны и конечные пользователи могут выбирать из множества новейших технологий для поддержки своих приложений. Одним из таких инструментов является webhook, который практически любое веб-приложение может интегрировать для создания динамичного и отзывчивого контента.
Что такое веб-крючки?
Веб-крючки — это однонаправленный механизм, который приложения могут использовать для общения друг с другом при наступлении определенного события. Представьте себе веб-крючок как автоматизированную одностороннюю связь от одного приложения к другому. Первое приложение отправляет информацию получателю, не ожидая ответа. Затем оно полагается на то, что получатель обработает эту информацию.
Например, вы можете использовать платформу системы управления контентом (CMS) в качестве источника данных для вашего приложения. В идеале, когда вы обновляете поля CMS и публикуете их, вы хотите, чтобы ваше приложение знало, что нужно автоматически искать эти обновления. Таким образом, ваша CMS запускает веб-крючок, который перестраивает приложение для зеркального отображения CMS.
Односторонний характер веб-крючков отличает их от многих других коммуникационных систем, таких как API. Хотя веб-крючки служат во многом тем же целям, что и API, они менее ресурсоемки и более эффективны, когда вам нужно передать информацию куда-то асинхронно.
API требуют как запроса, так и ответа, что увеличивает задержку и, возможно, приводит к необходимости постоянно проверять данные. В отличие от этого, использование веб-крючков устраняет необходимость постоянно проверять наличие новых данных. Вместо этого, когда происходит определенное событие, веб-крючок автоматически уведомляет вас. Кроме того, односторонняя природа webhooks позволяет нескольким местам получать передаваемую информацию одновременно.
Варианты использования webhooks в основном зависят от того, чего вы хотите добиться от своего приложения. Существует несколько способов творческого использования webhooks для достижения ваших целей. Например, с помощью webhooks можно прослушивать изменения в базе данных для завершения профиля пользователя, а затем отправить пользователю электронное письмо с приветственной информацией, следующими шагами и так далее. Кроме того, вы можете интегрировать приложения, такие как Jira, Bitbucket или приложение календаря, с вашей платформой обмена сообщениями, чтобы получать обновления в режиме реального времени.
Теперь, когда вы лучше знакомы с общей идеей веб-крюков, давайте рассмотрим, как вы можете получить еще больше функций и гибкости с помощью веб-крюков Contentful.
Как работают вебхуки Contentful
Односторонняя связь, которую обеспечивают webhooks, идеально подходит для такой системы, как Contentful. Contentful webhooks позволяет получать обновления в режиме реального времени, поскольку любое изменение, происходящее в системе, может вызвать webhook. Затем веб-крючок отправляет информацию об этих изменениях или обновлениях в любое количество систем.
Эта архитектура с низкой задержкой обеспечивает гораздо более быструю связь, чем аналогичная система на базе API, гарантируя, что любое изменение контента в системе немедленно отражается во всех подключенных системах.
Большинство веб-крючков Contentful срабатывают при изменении данных, модели контента или состояния контента. В результате все сайты и приложения, прослушивающие этот веб-крючок, немедленно узнают о необходимости обновления. Эти функции позволяют инициировать событие чата, событие обновления для пользователей или перестройку статического сайта Next.js или Gatsby.
Вебхуки Contentful можно разделить на пять категорий типов: ContentType, Entry, Asset, Task и Release. Более того, каждый тип поддерживает различные действия. Например, для вебхука Entry Contentful поддерживает все возможные действия: создание, сохранение, автосохранение, архивирование, разархивирование, публикация, неопубликование и удаление.
В таблице ниже показаны возможности каждого типа веб-крючков:
В дополнение к типам, указанным в таблице, Contentful также предлагает несколько собственных веб-крюков для действий освобождения, массовых действий и действий по расписанию. Давайте рассмотрим каждый из них и то, как вы можете их использовать.
Освобождение и действия по освобождению
Чтобы понять действия релиза, сначала нужно понять, что такое релиз. Релиз — это поле или инструмент, который вы можете назначить своему содержимому. Основным применением релиза может быть массовая публикация или отмена публикации содержимого в вашей CMS. Например, если ваш бизнес электронной коммерции проводит распродажу и вы хотите опубликовать все товары, выделенные для продажи, вы можете создать и добавить релиз для этих товаров, а затем использовать его для публикации и неопубликования.
Затем веб-крючки действий освобождения могут прослушивать событие освобождения — в данном случае действия публикации и неопубликования. Contentful поддерживает два типа действий освобождения: создание и выполнение. Веб-крючок действия релиза в первую очередь предназначен для действия на другое действие. Например, после публикации релиза вы можете захотеть прослушать веб-крючок действия релиза. После успешного выполнения вы, возможно, захотите инициировать создание нового сайта для более эффективного получения данных.
Массовые действия
Массовые действия могут быть особенно полезны, когда данные, которые ваше приложение отображает конечному пользователю, постоянно меняются, и ваше headless-приложение должно постоянно обновляться, чтобы обеспечить наилучший пользовательский опыт. Как и веб-крючки release action, Contentful поддерживает создание и выполнение действий с помощью этого веб-крючка bulk action.
Возвращаясь к примеру с гипотетическим сайтом электронной коммерции, предположим, что вы собираетесь предоставлять скидки на определенные товары в зависимости от дня. Для этой ситуации вы можете создать массовые действия, которые публикуют новые товары в конце каждого дня и не публикуют товары со скидками предыдущего дня.
Прослушивая веб-крючки массовых действий, вы сможете точно знать, когда выполняется массовое действие, и, соответственно, запустить сборку. Таким образом, этот тип веб-крючков чрезвычайно полезен для любого сайта, на котором часто обновляется динамический контент.
Запланированные действия
В отличие от веб-крючков для массовых действий и действий по освобождению, действия по расписанию открывают веб-крючки для типов событий «создать», «сохранить», «выполнить» и «удалить». Эти веб-крючки могут быть полезны для выполнения таких действий, как создание сборки или запуск поиска после настройки запланированного действия для вашего контента.
Реализация веб-крючков
В этом разделе мы объясним, как реализовать веб-крючки Contentful с помощью панели инструментов Contentful и API Contentful.
Использование приборной панели Contentful
Интерфейс приборной панели Contentful позволяет легко создавать веб-крючки независимо от вашего уровня знаний.
Для начала войдите в свою учетную запись. Затем, как только вы окажетесь в пространстве, нажмите на выпадающий список Настройки на верхней навигационной панели, как показано ниже:
Развернув выпадающий список Настройки, выберите Webhooks, чтобы перейти к панели Webhooks.
На панели Webhooks вы увидите список уже созданных Webhooks (если они у вас есть), кнопку + Add Webhook в правом верхнем углу страницы и правую панель, где отображается еще одна полезная функция Contentful: выбор из нескольких вариантов шаблонов Webhook. Эти шаблоны обеспечивают удобный способ создания веб-крючков для интеграции непрерывной интеграции/непрерывного развертывания (CI/CD).
Пока что нажмите кнопку + Add Webhook, чтобы открыть форму, как показано ниже.
В форме необходимо указать имя и URL для веб-крючка. Кроме того, если не выбрать конкретный вариант, созданные веб-крючки будут вызывать все события.
Нажмите на радиокнопку рядом с Select specific triggering events (Выбрать определенные события), чтобы увидеть флажки для выбора событий и типов, которые должен прослушивать этот веб-крючок. Отключенные флажки представляют события, которые Contentful не поддерживает для данного типа действия.
Затем, после перехода к разделу «Триггеры», появляется возможность добавить фильтры к веб-крючку. Он предлагает множество вариантов для сравнения, таких как ID среды, ID типа содержимого, ID сущности, ID пользователя (создан пользователем), ID пользователя (обновлен пользователем), а также логические сравнения с помощью равно, не равно, в, не в, regexp и not regexp. Кроме того, обратите внимание, что вы можете использовать более одного фильтра для каждого веб-крючка, что позволяет создавать сложные условия.
После фильтров у вас есть возможность установить заголовки, тип содержимого, длину содержимого и полезную нагрузку.
Функциональность Payload дает возможность изменять формат веб-крючков в соответствии со структурой вашего приложения. Это может значительно сэкономить время.
После заполнения необходимых данных нажмите кнопку Сохранить. Теперь вы создали веб-крючок, который можно просмотреть в панели Webhooks.
Теперь вы знаете, как создать веб-крючок и добавить фильтр с помощью графического интерфейса пользователя (GUI) Contentful. В следующем разделе вы воспользуетесь API Contentful, чтобы сделать то же самое.
Использование API Contentful для создания веб-крючков
Contentful также предлагает маршруты API для создания и настройки веб-крючков. Но прежде чем продолжить использование API для получения веб-крючков, убедитесь, что у вас есть ключ API, который необходимо авторизовать.
Начните с получения списка существующих веб-крючков. Вы можете получить веб-крючок, который вы создали с помощью графического интерфейса, выполнив запрос curl. Единственное, что вам понадобится, это SPACE_ID и API_KEY. Запрос curl должен выглядеть следующим образом:
curl -X GET "https://api.contentful.com/spaces/<SPACE_ID>/webhook_definitions"
-H "Authorization: Bearer <API_KEY>"
-H "Content-Type: application/vnd.contentful.management.v1+json"
Импортировав этот запрос в Postman и нажав кнопку Send, вы получите ранее созданный webhook со всей информацией, включая имя, URL, пробел, фильтры и заголовки.
Аналогично, вы можете использовать API для создания веб-крючка. Для создания веб-крючка через API вам понадобится SPACE_ID и API_KEY. Вот как выглядит основной запрос curl:
curl -X POST "https://api.contentful.com/spaces/<SPACE_ID>/webhook_definitions"
-d '{"url": "<URL>", "name": "WEBHOOK_NAME", "topics": ["*.*"], , "filters": []}'
-H 'Authorization: Bearer <API_KEY>'
-H 'Content-Type: application/vnd.contentful.management.v1+json'
Он принимает четыре элемента в качестве части тела вызова API, которое включает URL, имя, темы в виде массива тем и фильтры в виде массива фильтров.
Темы относятся к тому, на какие изменения вы хотите подписаться (см. таблицу в начале статьи). Если вы хотите подписаться на все действия нескольких типов, вы можете использовать .
Подобно типам и событиям, фильтры также могут быть переданы в виде объекта JSON в тело вызова API для создания веб-крючка. Проверьте, какие ограничения для фильтров предоставляет API, просмотрев официальную документацию.
Итак, если вам нужен фильтр, подобный тому, который вы создали с помощью графического интерфейса, вам нужно передать следующий объект filters в теле JSON, как показано ниже:
"filters": [
{
"in": [
{
"doc": "sys.environment.sys.id"
},
[
"master"
]
]
}
]
Также можно добавить несколько логических условий, чтобы они вели себя как логическое «И»:
"filters": [
{
"in": [
{
"doc": "sys.environment.sys.id"
},
[
"master",
]
]
},
{
"equals": [
{
"doc": "sys.id"
},
"146353"
]
}
]
Имея в виду следующую информацию, вы можете использовать API с помощью Postman.
Следующий объект JSON был передан для создания вебхука, аналогичного тому, который вы создали с помощью графического интерфейса:
{
"url": "https://www.example-app.com/api/update",
"name": "Trigger Build API",
"topics": [
"*.*"
],
"filters": [
{
"in": [
{
"doc": "sys.environment.sys.id"
},
[
"master"
]
]
}
]
}
После успешного запроса вы должны получить аналогичный ответ от API:
Подведение итогов
Широкое разнообразие веб-крючков Contentful может быть очень полезным для выполнения различных задач, таких как создание статического веб-сайта после набора действий, запуск скрипта для генерации индексных файлов для поиска, отправка уведомления заинтересованным лицам после завершения запланированных или массовых действий.
Contentful также предлагает два способа создания веб-крючков с помощью API и графического интерфейса, обеспечивая баланс гибкости и функциональности. Зарегистрируйтесь в бесплатной учетной записи Contentful и узнайте, как наша ведущая на рынке платформа для работы с контентом может поддержать ваш проект или бизнес.