Поиск возможностей для волонтерства с помощью Twilio, VolunteerMatch и ASP.NET

Наступает праздничный сезон. Для многих из нас это время, когда мы размышляем о том, насколько нам повезло в жизни, и как мы можем использовать свои навыки, чтобы помочь другим в наших сообществах. Существует множество организаций, посвятивших себя служению другим, и участие в их деятельности может стать невероятно полезным опытом. Но как узнать, какие организации и возможности доступны в вашем районе?

VolunteerMatch — это сайт, который упрощает поиск волонтерских возможностей в вашем районе, соответствующих вашим навыкам. У них также есть API, который очень нравится нам в Twilio. В духе праздничного сезона мы объединились с VolunteerMatch, чтобы создать приложение, которое делает поиск местных волонтерских возможностей ещё проще.

Попробуйте прямо сейчас: отправьте SMS с вашим почтовым индексом на номер (314)-282-8630.

В этой статье я покажу, как мы создали это приложение с помощью простого веб-сайта на ASP.NET MVC, API VolunteerMatch и Twilio SMS. Конечно, если вы хотите просто взять исходный код и настроить свою собственную службу, вы можете сделать это, перейдя в репозиторий на GitHub, но я думаю, что гораздо интереснее создать его с нуля. Давайте начнем!

Чтобы создать собственное приложение для поиска волонтерских возможностей, вам понадобится собрать несколько инструментов перед началом кодирования. Для начала вам потребуется:

— Бесплатная учетная запись API VolunteerMatch

— Бесплатная учетная запись Twilio. Зарегистрируйтесь, если у вас её ещё нет. Пробная учетная запись отлично подойдет для разработки приложения.

Вам также понадобятся:

— Visual Studio для создания приложения ASP.NET MVC 5. Здесь снова подойдет бесплатная Community Edition.

— ngrok — мой предпочитаемый инструмент для предоставления доступа к веб-серверу, работающему на моем локальном компьютере, через публичный URL.

Как только вы соберете все необходимые учетные записи и инструменты, можно приступать к кодированию. Начните с создания пустого проекта ASP.NET MVC в Visual Studio и добавьте новый контроллер с именем `HomeController`.

Затем добавьте два пакета NuGet в проект: Newtonsoft.Json и Twilio.Mvc. Мы будем использовать их для разбора данных о волонтерских возможностях, получаемых от API VolunteerMatch, и для того, чтобы указать Twilio, как отвечать на входящие текстовые сообщения с запросами поиска.

После установки пакетов NuGet внесем несколько изменений в контроллер. Начните с изменения базового класса контроллера на `TwilioController`. Затем, поскольку в дальнейшем нам нужно будет вызывать методы с await для объекта `HttpClient`, измените метод действия Index на асинхронный.

Внутри метода Index создайте новый объект `TwilioResponse`. Пока используйте метод `Message` для генерации TwiML, который указывает Twilio отправить SMS-ответ с сообщением «Hello World» обратно отправителю входящего сообщения. Позже мы изменим это, чтобы возвращать набор волонтерских возможностей.

Наконец, добавьте набор классов моделей, соответствующих данным, которые мы получим от API VolunteerMatch:

— OpportunityResult.cs — содержит список найденных возможностей

— Opportunity.cs — отдельная волонтерская возможность

— Availability.cs — информация о дате и времени возможности

— Organization.cs — детали об организации, опубликовавшей возможность

— Location.cs — местоположение возможности

Вы можете скопировать эти классы из репозитория GitHub или загрузить их в этом ZIP-файле.

Теперь у нас есть базовая настройка проекта, и мы готовы попробовать его в действии. Запустите ngrok и направьте его на ваш локальный веб-сервер. Чтобы запустить ngrok в Windows, возьмите порт, назначенный вашему сайту IIS Express, и используйте его с помощью следующих команд в командной строке:

Как только ngrok запущен, скопируйте публичный URL, назначенный вашему соединению:

Настройте URL запроса сообщения вашего номера телефона Twilio на этот URL.

Теперь отправьте текстовое сообщение со своего телефона на ваш номер телефона Twilio. Если всё работает правильно, вы должны получить ответное текстовое сообщение с текстом «Hello World».

Когда базовое приложение запущено и работает, мы можем подключить его к API VolunteerMatch, чтобы находить местные волонтерские возможности. API VolunteerMatch довольно прост. Он принимает GET-запросы с двумя параметрами:

`action` — конкретная операция, которую вы хотите выполнить. В API есть две основные операции: `searchOpportunities` и `searchOrganizations`.

`query` — набор параметров, доступных для каждой отдельной операции. Например, операция `searchOpportunities` включает параметры, которые позволяют фильтровать по местоположению и ключевому слову, а также контролировать количество возвращаемых возможностей.

Для нашего приложения мы будем использовать операцию `searchOpportunities` и параметр `location` для поиска волонтерских возможностей, которые находятся рядом с нами.

Создайте новый класс с именем `Match`. В этот класс добавьте:

— строковое свойство с именем `Action`, возвращающее `searchOpportunities` — название API-операции, которую мы хотим выполнить.

— метод с именем `Find`, который принимает строку с фильтром местоположения и возвращает `OpportunityResult`.

Далее нам нужно сформировать параметр `query`, чтобы ограничить поиск по местоположению. API VolunteerMatch ожидает, что параметр query будет объектом JSON, содержащим параметры и значения. Поскольку в данном случае объект JSON довольно прост, я просто сформирую его вручную и использую новую функцию интерполяции строк в C# 6, подставляя в строку параметр метода location:

Теперь мы готовы настроить объект `HttpClient`, который будет отправлять HTTP-запрос к API VolunteerMatch. Создайте новый экземпляр `HttpClient` и установите заголовок Content-Type в application/json.

Затем создайте экземпляр класса `HttpRequestMessage` и установите метод HTTP в GET, а Uri — в URL API VolunteerMatch. Убедитесь, что вы включили параметры action и query в строку запроса:

Далее отправьте запрос к API, прочитайте его ответ как строку, попытайтесь десериализовать ответ в тип `OpportunityResult` и верните его из метода `Find`.

Теперь, когда у нас есть класс, который может получать волонтерские возможности из API VolunteerMatch, мы будем использовать этот класс в методе действия нашего контроллера и вызывать его метод `Find`. Мы передадим содержимое входящего текстового сообщения, которое должно быть местоположением, например городом или почтовым индексом, в метод `Find`. Когда мы получим ответ от VolunteerMatch, мы используем его для ответа на входящее сообщение с найденными возможностями:

Запустите веб-приложение. Убедитесь, что ngrok всё ещё работает, и отправьте текстовое сообщение на ваш номер телефона.

Бац! Подождите… ничего не происходит. Почему? Ах да, мы не включили информацию для аутентификации в наш запрос к API VolunteerMatch, поэтому он не сработал. Давайте изменим запрос, чтобы включить необходимую аутентификацию.

API VolunteerMatch использует тип аутентификации, обычно называемый WSSE. Этот стиль аутентификации требует, чтобы мы создали токен на основе нескольких вычисленных значений и включили этот токен в пользовательский HTTP-заголовок. Давайте пройдем через создание этого токена и добавление заголовка.

Начните с добавления некоторых свойств конфигурации в наш файл web.config:

Значения Username и ApiKey вы должны были получить при регистрации в API VolunteerMatch. Значение DateFormat — это строка формата, которую мы будем использовать для отправки объекта DateTime в формате, ожидаемом API.

Вернемся в класс `Match` и добавим три строковых свойства и одно свойство DateTime:

Создайте конструктор, который загружает значения Username, ApiKey и DateFormat из файла web.config:

Отлично! Теперь давайте изменим `HttpClient`, чтобы он включал заголовок аутентификации:

Наконец, нам нужно добавить пользовательский заголовок X-WSSE и заполнить его UsernameToken. Для добавления пользовательского заголовка мы будем использовать существующий экземпляр `HttpRequestMessage`.

Как мы видели ранее, UsernameToken — это конкатенированная строка, содержащая имя пользователя API VolunteerMatch, дайджест пароля, одноразовый номер (nonce) и значение даты-времени. У нас уже есть имя пользователя из файла web.config, поэтому нам нужно написать код, который создаст значения даты-времени, nonce и дайджеста.

В класс Match добавьте новое свойство с именем `Nonce`, которое генерирует значение nonce и возвращает строку:

Свойство использует криптографический генератор случайных чисел для создания строки в кодировке Base64 из криптографически стойких случайных чисел.

Далее добавьте свойство, возвращающее строку нашего PasswordDigest. Это свойство объединяет Nonce, отформатированную дату-время, возвращаемую свойством Created, и ключ API. Оно хеширует эту строку, а затем кодирует хеш в Base64.

Теперь давайте используем свойства Nonce и PasswordDigest, а также дату Created для заполнения заголовка X-WSSE.

С добавленным кодом аутентификации попробуйте снова запустить веб-сайт и отправить текстовое сообщение на ваш номер Twilio. На этот раз запрос к API VolunteerMatch должен завершиться успешно, и вы должны получить ответное текстовое сообщение с перечнем возможностей в указанном вами местоположении.

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

VolunteerMatch — отличный ресурс, который поможет вам сопоставить ваши навыки с местными волонтерскими возможностями. Сочетание их данных с Twilio SMS делает поиск подходящей возможности простым и доступным.

Приложение, которое мы создали в этой статье, довольно простое, и существует множество способов расширить его с помощью API VolunteerMatch, включая:

— добавление возможности постраничного просмотра результатов,

— улучшение поиска по местоположению за пределами почтового индекса,

— или предоставление пользователю возможности получать более подробную информацию об отдельной волонтерской возможности через текстовое сообщение.

Дайте знать, как вы помогаете другим в этом сезоне. Свяжитесь со мной в Twitter или оставьте комментарий ниже.