Интеграция Twilio Monitor с HipChat

Вспомните свой последний инцидент. Это было посреди ночи (всегда посреди ночи). Вам позвонили в 2 часа ночи. Полусонный, вы сделали все возможное, чтобы воспринять плохие новости.

После короткого разговора ваши операционные и инженерные команды решают работать над проблемой через HipChat. Для тех из вас, кто живет в HipChat, вы знаете, что жизнь в 2 часа ночи намного лучше, когда ваши ИТ-инструменты интегрированы туда. Наличие критически важной информации под рукой может означать разницу между решением проблемы за 5 минут или за 5 часов.

Сегодня я покажу вам, как это сделать в HipChat с Twilio. Чтобы помочь вам отлаживать проблемы, связанные с вашим приложением Twilio, мы создали Monitor. Monitor предоставляет вам доступ к журналам ошибок и событий, которые помогают понять, что происходит. Кроме того, с помощью Monitor Alerts вы можете попросить Twilio оповещать конечную точку по вашему выбору, когда Twilio обнаружит ошибку. В этом примере мы будем использовать Twilio Alerts для отправки обновлений в комнату HipChat.

Следуйте приведенным ниже шагам, и вы получите рабочую интеграцию Twilio Monitor и HipChat за 20 минут. В качестве бонуса вы получите краткое руководство по отладке и криминалистике с помощью Runscope и узнаете, как настроить безопасный туннель к локальному веб-серверу на вашей машине с помощью инструмента под названием ngrok.

На Рисунке 1 ниже вы можете увидеть, к чему мы стремимся. Twilio отправляет оповещения из вашего приложения Twilio непосредственно в вашу комнату HipChat.

Прежде чем мы начнем, вот что вам нужно знать об инструментах.

О Twilio Monitor: Это система оповещений, уведомлений и мониторинга событий Twilio. Она отслеживает эксплуатационную готовность ваших приложений Twilio, а также вашего аккаунта Twilio и информирует вас через гибкий механизм оповещений об оповещениях безопасности или эксплуатации. Для получения более подробной информации о Monitor вы можете прочитать здесь или увидеть это в вашем портале аккаунта Twilio здесь.

О HipChat – HipChat — это безопасный облачный инструмент для совместной работы для групповых и личных чатов. Вы можете получить доступ к комнатам HipChat через браузер, автономные настольные приложения, мобильные клиенты и многое другое. Вы можете прочитать об HipChat здесь.

**Начнем**

Готовы к небольшому приключению? Давайте начнем.

Для интеграции Twilio Monitor с HipChat нам, по сути, нужно сделать 3 вещи:

— Создать комнату HipChat для нашей системы оповещений. В этом примере мы работаем с одной комнатой, но при желании вы можете использовать несколько комнат HipChat.

— Настроить способ программного отправки сообщений в комнату HipChat.

— Настроить Twilio Monitor для выполнения веб-хуков для отображения ваших оповещений в комнате HipChat.

**Создание комнаты HipChat – Шаг 1**

В частности, мы будем настраивать облачную комнату HipChat. Если у вас есть существующий экземпляр HipChat, любой администратор может предоставить вам права на публикацию в этой комнате. Просто спросите!

Давайте зайдем на HipChat и используем кнопку регистрации в правом верхнем углу. Затем зарегистрируйтесь для своей учетной записи.

Чтобы изолировать наши усилия, мы просто создадим новую команду, вместо того чтобы присоединяться к существующей. В вашем случае, вероятно, вы захотите сделать прямо противоположное и присоединиться к существующей команде. Я называю свою команду «twiliomonitor», что приводит к URL-адресу доступа twiliomonitor.hipchat.com. Готово. Этот зарезервирован……

На следующем экране вы можете пригласить кого-нибудь или нет. Это зависит от вас. Помните, что мы просто тестируем.

При регистрации вы получите подтверждающее письмо для подтверждения вашей учетной записи. Это открывает некоторые функции HipChat, поэтому лучше сделать это сейчас.

Хорошо, теперь у вас есть учетная запись пользователя и комната HipChat. Мы можем пригласить других людей в нашу комнату, если захотим, и начать общаться, но отложим социальные условности до тех пор, пока не будем готовы похвастаться нашей интеграцией Twilio.

Поскольку вы администратор, вы можете перейти к правой стороне списка значков и щелкнуть «Действия комнаты», значок с тремя точками, а затем выбрать «Интеграции».

На экране интеграций нажмите кнопку *Создать* под «Создайте свой собственный!», чтобы продолжить.

Давайте дадим нашей интеграции имя и создадим ее.

Экран «Создайте свой собственный!» предоставляет вам точный URL-адрес для отправки POST-запроса для создания пользовательского сообщения в вашей комнате HipChat. В моем случае URL-адрес:

https://api.hipchat.com/v2/room/2036312/notification?auth_token=qXXXXXXXXXXXXXXXXXXXXXXLB8uRyuIzq8m5Xq

В URL вы увидите свой auth_token. Это ваш секретный пароль. Берегите его и не публикуйте в блоге 🙂 Под URL-адресом запроса вы найдете рабочий пример curl, который вы можете скопировать в терминал (командная строка в Windows), чтобы попробовать получить ваше сообщение, или просто использовать кнопку «Попробовать!».

Вот что я вижу в своей комнате twiliomonitor после нажатия «Попробовать!»: «Мое первое уведомление», да!

Мы, по сути, закончили с шагом 1. Мы создали комнату HipChat и можем программно отправлять в нее сообщения.

**Создание комнаты HipChat – Шаг 2: Получение оповещений Twilio в формате HipChat**

Перейдем к программированию. Вот что нам нужно достичь. Когда Twilio отправляет оповещение, Twilio отправляет полезную нагрузку в теле POST-запроса, которая предоставляет подробности об ошибке или предупреждении, вызвавшем оповещение. Чтобы проанализировать, что происходит, мне нравится использовать Runscope. Runscope — это, по сути, прокси-сервер, который регистрирует все пары запрос/ответ, проходящие через вашу систему. Это фантастический инструмент. На приведенном ниже рисунке вы можете увидеть веб-хук Twilio для уведомления об оповещении.

Runscope разбирает параметры из тела запроса и упорядоченно отображает их в разделе ПАРАМЕТРЫ.

Здесь вы можете увидеть, что оповещение сработало впервые сегодня ( Период: ежедневно, Значение триггера: 1 ) связанное с AppMonitorTriggerSid: ATcb…..

Через минуту я расскажу, откуда берутся эти значения и как их настроить.

Но прежде чем мы продолжим, нам нужно решить пару вещей. С одной стороны, у нас есть механизм оповещений Twilio, который использует параметры запроса в теле, а с другой стороны, у нас есть HipChat, который ожидает, что сообщения, отправляемые в комнату HipChat, будут настроены как JSON-полезная нагрузка. Кроме того, описание ошибки для Twilio находится в поле Description, в то время как HipChat ожидает его в поле под названием «message», которое вы видели, когда HipChat предоставил нам пример для отправки в комнату.

Проверьте содержимое между «{» и «}». Это JSON-объект, который отправляется в curl-запросе и показывает, как HipChat ожидает форматирования сообщений.

Итак, нам нужно что-то для преобразования между форматом сообщений из Twilio и тем, как HipChat ожидает сообщения. Вероятно, существует несколько подходов к этому. Чтобы упростить, я написал небольшую PHP-страницу для выполнения этой работы по преобразованию между параметрами POST и JSON-объектами. Возможно, вы захотите вместо этого использовать прокси-сервер с правилами перезаписи, хотя я не смог найти такой, который мог бы выполнить такую обработку.

В этом случае веб-хук Twilio Alert (по сути, веб-запрос) отправит POST-запрос на эту PHP-страницу, где мы программно извлечем параметры, переформатируем и переименуем их в JSON-объект и перенаправим их в комнату HipChat. Просто и ясно.

Позвольте мне быстро объяснить, что я сделал, чтобы вы могли взять этот код и изменить его в соответствии со своими потребностями.

Строка 2-3: Я всегда отправляю обратно 200 OK на запрос веб-хука Twilio. Я мог бы передать код состояния из HipChat, но Twilio не предпримет никаких действий при неудачных запросах (только при тайм-аутах), поэтому нет смысла в расширенной логике здесь.

Строки 5-26: Здесь я извлекаю параметры post из запросов веб-хука Twilio. Это те, о которых мы говорили ранее, те, которые, по сути, описывают причину оповещения, AccountSid и т. д.

Строка 29: Помните, когда я сказал, что ключевое имя JSON (=ключ) — это «message»? Так вот, что я делаю здесь, это агрегирую значимые, легко читаемые данные в длинную строку сообщения, которую мы затем можем отправить в комнату HipChat.

Строка 30: Сообщение, которое является строковой переменной, встраивается в более крупный массив с дополнительной информацией для HipChat. Например, «color» определяет базовый цвет сообщения. «Notify» определяет, должно ли сообщение приходить с Bang, ну, скорее с clang и т. д. Полный список параметров можно найти здесь. json_encode — это функция PHP, которая принимает массив PHP и преобразует его для нас в JSON-объект, здесь называемый $messagejson.

Строки 33-48: Это curl-запрос со страницы PHP к API HipChat. Есть и другие способы сделать это, но мне нравится этот подход. По сути, я делаю POST-запрос с Content-type, установленным на application/json, к API HipChat, и тело содержит наш объект $messagejson. Чтобы использовать это в вашей интеграции, вам нужно будет изменить URL в строке 39 на тот, который HipChat предоставил вам ранее. Позвольте мне сделать краткое замечание о CURLOPT_SSL_VERIFYPEER=false. Что это делает, так это игнорирует сертификат безопасности TLS HipChat. Я не знаю, является ли это большой проблемой. Мы не отправляем здесь конфиденциальную информацию, но вам следует спросить у своего отдела безопасности, что они думают.

Следующая диаграмма иллюстрирует, что мы делаем с нашим брокером запросов.

Ключевым моментом является то, что PHP-скрипт имеет две стороны: одна, которая получает и отвечает на запрос веб-хука Twilio. Другая, которая отправляет запрос JSON API через Curl и получает обратно информацию о статусе от HipChat.

**Шаг три – Укажите Twilio, куда идти**

Почти готово. Всего две вещи. Во-первых, нам нужно сделать нашу PHP-страницу доступной в Интернете, чтобы Twilio мог ее вызывать, а затем нам нужно сообщить Twilio, чтобы он вызывал нашу страницу, когда происходит оповещение.

Запустите PHP-страницу и сделайте ее видимой в сети.

Мы запускаем PHP-страницу как тестовую страницу не для производства с помощью встроенного сервера PHP. Позже вы можете разместить ее в своей среде критически важных систем, если захотите. Помните, мы делаем только POC.

Мой PHP-файл называется twiliomonitor.php. Давайте запустим встроенный сервер PHP из командной строки. Откройте терминал или командную строку и введите следующее.

php -S localhost:8000 -t path/to/directory

*(Я предполагаю, что у вас установлен PHP. Если нет, есть много веб-сайтов, которые помогут вам с установкой для вашей конкретной ОС)*

Эта команда запустит PHP-сервер на порту 8000, который отображает файлы в /path/to/directory. Вот как это выглядит на моей системе.

Вы можете использовать браузер и перейти по адресу http://localhost:8000/twiliomonitor.php (или какое бы ни было ваше конечное имя) и проверить, что файл загружается без ошибок. В этом случае пустая страница — это действительно хорошая страница.

Теперь нам нужно сделать наш локальный сервер доступным для Интернета, чтобы Twilio мог вызывать нас за нашим брандмауэром.

Для этого мы используем ngrok.

Скачайте ngrok отсюда. Ngrok — действительно простой в использовании инструмент, и документация написана хорошо, поэтому я не буду утомлять вас деталями настройки.

Вот как я запускаю свой экземпляр ngrok и направляю его на свой веб-сервер PHP.

./ngrok 8000

Это делает мой локальный PHP-сервер, прослушивающий порт 8000, доступным для всего Интернета как http://d40312e4.ngrok.io/.

Ngrok выведет полное доменное имя при запуске. Или вы можете зарегистрироваться у них и получить пользовательский поддомен. Важно, чтобы ngrok работал. Поэтому не закрывайте окно, в котором он работает.

Вот как выглядит ситуация в моем мире.

Опять же, вы можете проверить, что ваш веб-сайт доступен, открыв браузер с полным URL-адресом ngrok. В моем случае я перехожу по адресу http://d40312e4.ngrok.io/twiliomonitor.php.

Помните, поскольку мы просто возвращаем пустую страницу, это все, что вы хотите видеть в своем браузере. Ничего. Разница здесь в том, что мы получаем доступ к нашей PHP-странице через URL www, так же, как и Twilio позже, вместо localhost, который мы использовали раньше.

Хорошо, как и обещалось, последнее, что нам нужно сделать, это заставить Twilio вызывать нашу PHP-страницу, когда в вашем приложении возникает ошибка. Вот как мы это сделаем. Войдите на портал своего аккаунта Twilio и в меню выбора перейдите в Monitor. Вот как это выглядит.

В разделе «Триггеры» выберите кнопку «Создать триггер оповещения». Пока не усложняйте. Присвойте триггеру осмысленное имя, значение триггера «1», для кода ошибки выберите «любое оповещение», а в разделе «Повторяющиеся» выберите «Ежедневно». Вы можете вызывать оповещения на основе различных условий, как я упоминал ранее, поэтому не стесняйтесь настраивать эти поля по мере необходимости. По конкретным или общим ошибкам, предупреждениям, уведомлениям и т. д. Существует также отдельный раздел на портале для триггеров использования. (ссылка ведет наверх).

Самое важное для этой работы — выбрать в разделе «Действия» «Запустить веб-хук» и указать URL-адрес, который мы использовали ранее. В моем случае это было: http://d40312e4.ngrok.io/twiliomonitor.php.

Теперь мы настроили систему Twilio для запуска веб-хука на нашу PHP-страницу, которая, в свою очередь, отправляет сообщения в комнату HipChat. Магия!

В этом случае триггер сработает при первом возникновении кода ошибки в ежедневном интервале. Это интересный поворот: если оповещение происходит снова в том же повторяющемся интервале, мы не получим оповещение. Twilio сделал это намеренно, чтобы не перегружать внешние системы уведомлений или электронную почту. Однако это затрудняет тестирование, и вам придется удалять и повторно создавать оповещения (которые, кстати, также можно сделать с помощью curl-скрипта).

Итак, как нам вызвать ошибку? Просто, давайте настроим номер телефона Twilio с недопустимым URL-адресом для голосовой связи и совершим телефонный звонок на этот номер. Вы услышите пресловутое «Просим прощения. Произошла ошибка приложения», но как только вы зайдете в свою комнату HipChat и увидите сообщение об оповещении, вы будете в восторге от своего сегодняшнего достижения.

На рисунке ниже, в нашей комнате Twiliomonitor, вы можете увидеть два внешних оповещения. Первое — от нашей кнопки «Попробовать!», а второе — напрямую из Twilio.

То, что вы обычно делали бы здесь, — это вернуться к своему приложению Twilio и исследовать причины ошибки.

Это все на сегодня. Задавайте вопросы и дайте мне знать, когда у вас получится, в разделе комментариев ниже.

Не могу дождаться, чтобы увидеть, что вы создадите!