Веб-крючки запускают большую часть “магии”, которая происходит между приложениями. Их иногда называют обратными API, обратными вызовами и даже уведомлениями. Многие службы, такие как SendGrid, Stripe, Slack и GitHub, используют события для отправки веб-ссылок как часть своего API. Это позволяет приложению прослушивать события и выполнять действия, когда они происходят.
В предыдущей статье мы рассмотрели, как использовать веб-книги с помощью Node.js и экспресс . В этой статье мы рассмотрим, как вы можете прослушивать веб-книги с помощью Python (v3+) с помощью фреймворков Flask или Django .
Вы можете перейти непосредственно к коду для любого фреймворка по одной из приведенных ниже ссылок:
- Получите веб-крючок с колбой
- Получите веб-крючок с Django
В этом руководстве предполагается, что на вашем компьютере установлен Python v3. Вы можете найти подробную информацию об установке python на странице официальные загрузки . В зависимости от настроек, команда python , которую вы хотите использовать, может быть python3 .
Вы можете подтвердить установленную версию, выполнив следующие действия из терминала:
python --version
или, если это отображает версию ниже 3:
python3 --version
Для команд оболочки, перечисленных в этом руководстве, используйте любую команду, связанную с вашей локальной установкой python.
Что такое веб-крючок
Веб-крючки по какой-то причине называются обратными API. Вместо того, чтобы ваше приложение отправляло запрос в API, API отправляет запрос в ваше приложение. Хотя концепция может звучать по-другому, способ, которым мы используем webhooks, аналогичен тому, как API использует запрос.
В большинстве веб – фреймворков существует концепция маршрута. Маршрут позволяет приложению отвечать определенным контентом или данными, когда пользователь посещает определенный URL-адрес. Та же идея применима и к API. Когда вы отправляете запрос на GitHub для получения подробной информации о конкретной организации, например https://api.github.com/orgs/Bearer , маршрут /orgs/:org где :org – название организации.
Та же концепция применяется при получении веб-крючков. Мы устанавливаем маршрут, сообщаем службе, куда отправлять данные, и наше приложение сидит и ждет, пока на этот маршрут не поступит запрос.
Существует несколько последовательностей в реализациях webhook.
- Обычно это
POSTзапросы. - Они получают данные JSON.
- Им нужно быстро реагировать.
Некоторые API требуют, чтобы ваше приложение отвечало в течение определенного периода времени, в противном случае событие будет отправлено повторно. Например, API Slack ожидает ответ в течение трех секунд.
Получите веб-крючок с колбой
Фреймворк Flask – это легкий веб-фреймворк Python, который описывает себя как “микро”. Это позволяет вам использовать только то, что вам нужно, а затем добавлять больше структуры позже по мере роста вашего проекта.
Для наших целей это здорово, так как мы занимаемся только маршрутизацией. Убедитесь, что Python установлен, а затем выполните следующую команду в терминале, чтобы установить flask:
python -m pip install Flask
Вы можете найти полную информацию об установке и настройке в документации Flask .
Затем создайте файл .py , например main.py и добавить следующее:
from flask import Flask, request, Response
app = Flask( __name__ )
@app.route('/webhook', methods=['POST'])
def respond():
print(request.json);
return Response(status=200)
Этот код импортирует класс Flask вместе с объектами запроса и ответа. Затем создает экземпляр с именем __name__ , прежде чем назначить его переменной app . Эта схема именования описана в документации по колбе.
Затем мы используем @app.route декоратор для прослушивания POST запросов, сделанных по пути /webhook|/. Этот декоратор вызывает функцию, которая немедленно следует за ним при запросе маршрута. В данном случае это функция response .
Для целей этого примера мы распечатываем запрос как json, а затем возвращаем Ответ с кодом состояния 200. Этот ответ сообщает отправителю, что мы получили крючок. Вы должны иметь возможность запускать сервер, используя предпочтительную технику Flasks:
export FLASK_APP=main.py python -m flask run
Вот и все! Теперь у нас есть приложение, которое прослушивает веб-крючок с python и flask. После развертывания POST запросы, отправленные в конечную точку, вызовут функцию response . Например: https://exampledomain.com/webhook . Это также URL – адрес, который вы предоставите службе, отправляющей webhook.
Получите веб-крючок с Django
Настройка приложения в Django более автоматизирована, чем Flask, но это также связано с более сложной структурой файлов. Как более традиционная структура Model-View-Controller (MVC), Django создает для вас основные части проекта. Полное руководство по установке доступно на официальной странице документации Django , но его также можно установить с помощью pip с помощью следующей команды:
python -m pip install Django
Если вы настраиваете проект с нуля, используйте утилиту django-admin для создания нового проекта. Если у вас уже есть существующий проект Django, в который вы хотите добавить веб-крючки, перейдите к следующему шагу.
django-admin startproject example-project
Это создает основу для нового проекта Django. Перейдите в недавно созданную папку, и вы увидите структуру, похожую на следующую:
example-project/
manage.py
example-project/
__init__.py
settings.py
urls.py
asgi.py
wsgi.py
Мы можем подтвердить, что все работало, запустив python manage.py runserver .
Соглашение Джанго состоит в том, чтобы настроить “приложения” в рамках этого внешнего “проекта”. Вы можете избежать этого и настроить проект с одним приложением, запустив django-admin startproject example-project . с конечным периодом (.) вместо этого. В этом уроке мы отразим предпочтительный способ, как показано ранее.
Для этого мы создадим “приложение” под названием webhooks .
python manage.py startapp webhooks
При этом создается новый каталог с именем webhooks . Отлично! Теперь мы можем написать код. Мы сосредоточимся на трех файлах: webhooks/views.py , webhooks/urls.py (еще не создан), и example-site/urls.py .
Откройте файл webhooks/views.py . Здесь мы напишем логику обработки маршрута.
from django.http import HttpResponse
from django.views.decorators.http import require_POST
@require_POST
def example(request):
return HttpResponse('Hello, world. This is the webhook response.')
Этот код выполняет следующие действия:
- Он импортирует объект
HttpResponse, который будет использоваться для отправки ответа. - Он импортирует специальный декоратор, чтобы ограничить метод запроса. В Django маршруты по умолчанию принимают все методы HTTP и позволяют представлениям управлять тем, на какие методы они отвечают.
- Вызывает декоратор, чтобы ограничить функцию, которая следует за ним, только методом
POST. - Определяет функцию с именем
example, которая принимает запрос в качестве аргумента и возвращает ответ.
Это пример имя функции будет связано с вашим urls.py файл вкратце. Ему не нужно выравниваться по определенному пути.
Затем создайте webhooks/urls.py если он еще не существует. Именно здесь мы организуем маршруты в рамках этого приложения нашего проекта.
from django.urls import path
from . import views
urlpatterns = [
path('example/', views.example)
]
Здесь мы импортируем путь из django.urls . Он определяет отдельные маршруты и связывает их с видами. Затем мы импортируем все представления. Наконец, urlpatterns передается список путей. Этот список распознается Django как маршруты, связанные с приложением.
В этом случае мы определяем путь, который нацелен на пример/| и связан с представлением views.example , которое было именем нашей функции в views.py .
После этого наше приложение работает, но нам нужно рассказать об этом внешнему проекту. Открыть example-project/urls.py . Он должен выглядеть так же, как и предыдущий файл, но с существующим маршрутом admin . Добавьте новый путь, например:
urlpatterns = [
path('admin/', admin.site.urls),
path('webhooks/', include('webhooks.urls'))
]
Если ваш сервер остановился, запустите его снова с помощью python manage.py runserver . Теперь попробуйте сделать запрос POST на http://127.0.0.1:8000/webhooks/example/ (замените хост и порт на свой собственный, если они отличаются).
С помощью этого мы создали проект Django, который прослушивает веб-крючок в /webhooks/example . После развертывания добавьте этот путь к полному URL-адресу и предоставьте полный URL-адрес службе, которая отправляет webhook.
Тестирование веб-крючков локально
Чтобы протестировать webhooks локально без развертывания, нам нужно открыть соединение с нашей машиной разработки с внешним миром.
Один из вариантов-использовать ngrok . Эта служба позволяет предоставить внешний доступ к определенному порту на локальном компьютере. Это отлично подходит для наших нужд. Чтобы начать работу, зарегистрируйтесь и следуйте инструкциям по установке и началу работы.
После этого, если вы работаете на macOS, вы сможете запустить ./ngrok http 3000 в своем терминале, где 3000 заменяется портом вашего запущенного приложения Python. Например, сайт Django по умолчанию часто работает на порту 8000.
После запуска ngrok предоставит вам URL-адрес, который вы можете использовать для тестирования своего веб-крючка. В Bearer мы предоставляем кнопку “тест” в настройках уведомлений.
После настройки вы начнете получать веб-крючки по этому URL-адресу. Не забудьте изменить его на окончательный, развернутый URL-адрес webhook после завершения разработки и тестирования.
Как только веб-крючок настроен, вам решать, как обрабатывать полученную информацию. Вы можете использовать эту информацию для реагирования на события в режиме реального времени, изменения функций в приложениях или даже для записи данных в базу данных. Существует бесчисленное множество возможностей, которыми может обладать ваш webhook, в зависимости от того, какую информацию отправляет поставщик API.
Хотя в этой статье мы построили базовую реализацию, стоит отметить, что многие службы предлагают способы проверки того, что запрос поступает из фактического источника. Это можно сделать, ограничив URL-адреса, которые обращаются к вашему приложению, или сопоставив секретный ключ. Например, GitHub позволяет вам установить секрет, который будет отправляться с каждым веб-крючком.
Изучите документацию по используемым службам, чтобы узнать, как лучше всего работать в рамках их настройки. Если вам нравится идея использования webhooks для реагирования на изменения в мониторинге с помощью сторонних поставщиков API, ознакомьтесь с тем, что мы создаем Bearer.sh .