Создайте свой собственный Покедекс с помощью Django, MMS и PokéAPI

Это был портативный, всезнающий супергаджет, который был бесценен для любого тренера покемонов, пытающегося *поймать их всех* в конце 90-х и начале 2000-х. Благодаря своей энциклопедической базе знаний о покемонах, Покедекс был тем инструментом, который вы доставали из кармана всякий раз, когда хотели узнать о новом покемоне, обнаруженном в играх, телесериале или карточной игре.

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

Почти вся информация об играх про покемонов недавно была добавлена в веб-API (*отказ от ответственности: это я его создал*), который называется PokéAPI. Этот API содержит все данные из серии компьютерных игр про покемонов, включая спрайты (изображения из игры) и описания каждого карманного монстра. С помощью нескольких вызовов API и небольшой обработки данных вы можете воспроизвести контент, который Покедекс мог бы предоставить вам при обнаружении покемона в дикой природе.

Но как перенести эти данные на портативное устройство? Оказывается, сегодня у каждого из нас есть портативное устройство, которое *умеет всё*. Создание приложения для iOS или Android могло бы быть хорошим способом распространения этого контента, но для этого потребовалось бы подключение к интернету. Уговорить людей установить приложение сложно, да и разработчику это отнимает много времени. В Pokémon Покедекс работает почти везде: на леднике, в пустыне и даже в океане! Должно быть, он использует какую-то сеть PSTN и SMS/MMS в качестве средства связи, верно?

Поскольку мы пытаемся максимально приблизиться к аутентичному Покедексу, давайте используем Twilio MMS и PokéAPI, чтобы создать сервис, который можно будет запрашивать при обнаружении нового покемона, независимо от того, где вы находитесь, даже если у вас нет мобильного интернета!

Попробуйте прямо сейчас! Не хотите создавать свой Покедекс? Опробуйте тот, который я создал ранее, отправив имя покемона на номер **(740) 630-0051 (США)** или **+442030952965 (Великобритания — только SMS)**:

*Нет покемона лучше для демонстрации*

Чтобы создать собственный MMS Покедекс, нам потребуется:

— Делать HTTP-запросы к PokéAPI.co.

— Собирать все необходимые ресурсы из PokéAPI (покемон, описание и спрайт).

— Создать веб-приложение на Django и добавить в него код для запросов к PokéAPI.

— Добавить описание из PokéAPI в документ TwiML для Twilio.

— Развернуть приложение Django на Heroku, чтобы оно было доступно в интернете.

— Протестировать его.

— Быть лучшим, как никто другой.

Для выполнения этого руководства вам понадобятся:

— Python 2.7 (установлен по умолчанию на Mac OSX и Linux, или следуйте инструкциям для Windows здесь).

— Бесплатный аккаунт Twilio, настройка занимает всего 2 минуты.

— Бесплатный аккаунт Heroku, ещё 2 минуты.

И с этим вы готовы приступить!

Выполнение HTTP-запросов к PokéAPI.co

Ознакомление с PokéAPI также означает, что вы научитесь взаимодействовать с REST API — распространённым способом предоставления ресурсов и данных через API в интернете. В этом руководстве мы будем использовать **Python**, но API можно запрашивать на любом языке, даже с помощью *cURL*. Попробуйте выполнить эту команду в терминале:

PokéAPI вернёт данные в формате JSON, которые хранятся на серверах приложения. JSON — это распространённый формат данных, который легко преобразуется в собственное объектное представление языка программирования.

В Python мы начнём с использования библиотеки Requests для выполнения HTTP-запроса к PokéAPI для получения данных о покемоне (давайте выберем Чаризарда, потому что он крут) и загрузим эти данные JSON в собственное объектное представление Python с помощью библиотеки JSON.

Сначала установите библиотеку requests с помощью pip:

Создайте новую директорию под названием *pokemon* (или что-то описательное), затем откройте новый файл в этой директории и напишите следующий код. Сохраните файл как *query.py*:

Здесь мы импортируем requests и основную библиотеку JSON Python. Затем создаём переменную *url*, содержащую ссылку на PokéAPI. Ниже, на строке 5, мы выполняем HTTP-запрос с помощью функции *get()* из requests и сохраняем результаты в переменной response.

Условный оператор ниже проверяет, получили ли мы HTTP-ответ 200 OK (стандартный ответ для успешного запроса). Если ответ успешен, мы преобразуем строку JSON в собственный объект Python и выводим атрибут *name*. Если мы не получили HTTP 200 OK (проверьте подключение к интернету!), то просто выводим ошибку.

Запустим этот скрипт с помощью Python в терминале и посмотрим результат:

С помощью этого небольшого скрипта мы научились запрашивать REST API PokéAPI и форматировать ответ в Python. Отлично! Порадуйте себя громким победным рыком!

Победный рык заставил вас почувствовать себя круто? Хорошо. Давайте соберём ресурсы, относящиеся к Чаризарду, которые мы хотим использовать для нашего Покедекса: описание и спрайт.

Изменим наш скрипт, чтобы получить эти данные и вывести их:

Здесь произошло довольно много изменений, чтобы достичь желаемого результата, поэтому давайте разберёмся, что происходит. Мы взяли URL для PokéAPI и сохранили его в глобальной переменной *BASE_URL*, так как хотим использовать её на протяжении всего кода.

Ниже, на строке 6, мы создали функцию *query_pokeapi*, которая принимает один параметр *resource_url*. Эта функция выполняет большую часть работы из предыдущего скрипта, запрашивая PokéAPI и возвращая представление данных JSON в Python. Мы будем часто использовать этот блок кода, поэтому создание функции позволяет нам повторно использовать его.

На строке 14 мы делаем запрос к PokéAPI для получения данных о покемоне Чаризард. На строках 16 и 17 мы смотрим на данные Чаризарда и получаем атрибут *resource_uri* для связанных ресурсов описания и спрайта. Здесь используется ещё одна важная концепция REST API под названием HATEOAS, суть которой заключается в предоставлении гипермедийных ссылок (например, URL) на связанные ресурсы. Затем мы используем эти гипермедийные ссылки для запроса к PokéAPI ресурсов спрайта и описания.

Наконец, мы выводим информацию, которую хотим отображать в нашем Покедексе:

Если вставить ссылку на спрайт в браузер, мы увидим спрайт Чаризарда из компьютерных игр:

Этот вывод не так впечатляет, как настоящий Покедекс, поэтому давайте придумаем, как отправить это на наши мобильные телефоны через Twilio и MMS.

Создание веб-приложения Django и формирование TwiML-ответа

Чтобы разместить наш код в интернете и отправлять покемонов на телефоны, нам нужно установить несколько вещей и настроить базовое веб-приложение Django. Когда веб-приложение будет запущено, мы сможем отправить SMS на номер Twilio. Когда Twilio получит это SMS, он сделает HTTP-запрос к нашему приложению Django. Приложение Django выполнит написанный нами код и отправит ответ обратно Twilio, который затем обработает инструкции и отправит пользователю MMS (или SMS, если вы находитесь в Великобритании).

Чтобы начать создание нашего приложения, мы хотим использовать git для клонирования базового проекта Django (который я создал, чтобы сэкономить время) и переключиться на ветку start:

После того как вы клонировали проект и переключились на ветку start, нам нужно создать виртуальную среду Python и установить все необходимые программы для запуска этого проекта. Введите следующее в терминал:

Для работы Twilio с Django нам нужно добавить токены TWILIO_ACCOUNT_SID и TWILIO_AUTH_TOKEN в нашу среду. Откройте файл *venv/bin/activate* в текстовом редакторе, перейдите в конец и добавьте эти две строки:

Обязательно замените значения на свои собственные токены. Сохраните файл и активируйте виртуальную среду:

Затем с помощью pip установите все зависимости:

После установки всего необходимого убедитесь, что сервер работает:

Если вы видите следующий вывод, значит, всё в порядке:

Нажмите *CONTROL+C*, чтобы остановить сервер.

Давайте напишем немного кода! Откройте файл в директории poketext под названием *views.py* в вашем любимом текстовом редакторе. Здесь мы будем создавать представления, которые будет обслуживать наше веб-приложение. Сейчас он должен быть полностью пустым. Если вы видите здесь какой-то код, вероятно, вы забыли переключиться на ветку *start*:

С пустым файлом давайте скопируем содержимое из предыдущего файла *query.py* и добавим новую логику на Python для работы с Django. Все изменения выделены ниже:

Давайте разберём основные моменты и поймём, что происходит.

На строках 1 и 2 мы импортируем некоторые специфичные для Twilio инструменты Python: *twilio_view* — это декоратор, который помогает форматировать ответы от Django обратно в Twilio. Класс *Response* поможет нам программно генерировать ответ TwiML на Python. Ниже вы заметите ту же функцию *query_pokeapi*, что и раньше, она выполняет ту же задачу и здесь.

Функция *incoming_message*, начинающаяся на строке 17, — это представление Django, которое будет получать запросы от Twilio. Первый параметр, который она принимает, *request*, — это представление входящего HTTP-запроса на Python. Вы заметите, что чуть выше, на строке 16, мы написали *@twilio_view* — это «синтаксический сахар» в Python, который сообщает декоратору, что его нужно запустить при вызове этого представления.

Начиная со строки 18, мы создаём новый объект *Response* под названием *twiml*, который будем использовать позже. Строки 20 и 21 получают *Body* входящего SMS-сообщения, которое мы ожидаем от Twilio, и применяют к нему нижний регистр. Когда Twilio отправляет HTTP-запрос о входящем SMS-сообщении, мы получаем кучу POST-параметров. Полный список элементов, которые отправляются вам, можно найти в документации на twilio.com. Чуть ниже формируется URL из переменной *Body* и используется для запроса к PokéAPI о покемоне.

В строках с 26 по 31 мы говорим: «Если получен ответ о покемоне, получите ресурсы описания и спрайта для этого покемона», почти так же, как во втором скрипте, который мы написали.

Строки 33 и 34 форматируют правильное сообщение и изображение, которые мы будем использовать для нашего ответа, а строка 38 формирует этот ответ. Предпоследний шаг — посмотреть, с какого номера мы получили сообщение: если в номере есть ‘+44’, мы знаем, что это британский номер, и хотим отправить обратно просто стандартное SMS, в противном случае отправляем MMS.

Наконец, мы возвращаем переменную *twiml*. На этом этапе django-twilio правильно её отформатирует (добавив правильный тип содержимого и представив её в виде XML) и отправит обратно в Twilio.

Если на строке 26 мы не получили ответ о покемоне, то на строках 43 и 44 создаём другой набор TwiML с сообщением об ошибке.

Настройка маршрутизации URL и выполнение тестового запроса

Прежде чем мы сможем протестировать это, нужно связать функцию представления *incoming_message* с URL в конфигурации URL Django. Это можно сделать в файле *poketext/urls.py*:

Импортируйте файл *views* на строке 4 и создайте новый URL в кортеже на строке 11, как показано выше. Сохраните файл и снова запустите сервер:

В новом окне терминала отправьте cURL-запрос на сервер, чтобы убедиться, что мы получаем ожидаемый XML-ответ:

Вывод в терминале немного запутан, вот правильно отформатированный XML-вывод:

Ура! Наше приложение Django принимает HTTP-запрос, запрашивает PokéAPI и возвращает XML-ответ, который поймёт Twilio! Пора снова праздновать:

Похоже, Кабigon, Снаббулл и Райчу не впечатлены. Почему? Вероятно, потому что мы ещё не развернули приложение и не интегрировали его с Twilio. Давайте порадуем их и решим последнюю часть головоломки Покедекса.

Развёртывание нашего приложения на Heroku

Чтобы запустить наше приложение в интернете, нам нужно зафиксировать все внесённые изменения с помощью git:

После того как эти изменения зафиксированы (с соответствующим сообщением коммита), мы можем развернуть код.

Мы будем использовать Heroku — облачную платформу для размещения и запуска приложений. Если вы не хотите учиться работать с Heroku и просто хотите развернуть копию приложения, нажмите кнопку ниже и перейдите к следующему шагу:

Если вы хотите научиться работать с Heroku, у них есть отличное руководство для начинающих, которое я рекомендую прочитать, прежде чем продолжить. В частности, убедитесь, что у вас установлен Heroku Toolbelt и вы готовы его использовать.

После установки Toolbelt и входа в Heroku давайте создадим новое приложение Heroku:

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

Проект, который я создал и который мы клонировали с помощью git в начале этого руководства, уже содержит все необходимые файлы настроек для Heroku, поэтому Heroku определит, что это приложение на Python, и начнёт устанавливать нужные зависимости. Если всё пройдёт по плану, вы должны увидеть следующий вывод в терминале:

Обязательно замените значения на свои реальные учётные данные.

После установки учётных данных аккаунта Twilio мы должны иметь возможность отправить cURL-запрос к приложению Heroku:

Связывание нашего приложения с номером телефона Twilio

Теперь, когда у нас есть работающая, общедоступная версия нашего приложения, давайте свяжем её с номером телефона Twilio. В бесплатной пробной учётной записи Twilio у нас будет один номер телефона Twilio в панели управления номерами. Нам нужно убедиться, что он поддерживает MMS, что обозначается этой маленькой иконкой:

Если у вас нет номера с поддержкой MMS, получите новый номер телефона здесь.

В настройках номера телефона с поддержкой MMS измените Messaging URL, чтобы он указывал на наш URL Heroku, и нажмите «Сохранить».

Последний шаг — отправить SMS-сообщение на номер телефона Twilio, чтобы проверить его работу с разными покемонами:

Эш Кетчум сейчас бы радостно закричал, если бы был здесь.

Будь лучшим, как никто другой

Теперь вы должны стать гордым владельцем настоящего, сложного Покедекса. Во время любого будущего боя покемонов или когда вы пытаетесь показать своему племяннику, насколько вы всё ещё круты, MMS Покедекс станет бесценным инструментом.

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

— Взаимодействие с REST API с помощью Python

— Создание TwiML-ответа Twilio для отправки MMS

— Развёртывание приложения Django на Heroku

Каждый из этих навыков пригодится вам в будущих путешествиях по созданию ПО, связанного с покемонами, обещаю. Увидимся на Плато Индиго!