Настройка инициализатора Vonage для Rails с помощью vonage-rails

Если у Rails и есть основополагающая религия, то это «соглашение важнее конфигурации». Одна из её самых строгих заповедей: держите контроллеры «тонкими». Действие контроллера должно получать запрос, координировать ответ и не мешать. Оно не должно отвечать за создание экземпляра и настройку API-клиента. Это отдельная задача, и её смешивание нарушает принцип единственной ответственности (Single Responsibility Principle), на котором строится архитектура Rails.

Поэтому вы можете делать это снова и снова по всему коду:

Гем vonage-rails решает эту проблему в стиле Rails: одна команда генератора создает инициализатор в config/initializers/, запускает глобальный клиент Vonage при старте и не мешает вашим контроллерам.

В этом руководстве рассматривается настройка инициализатора Rails с помощью гема vonage-rails, конфигурирование учетных данных с помощью переменных окружения и создание рабочего эндпоинта, который отправляет текстовое сообщение через Vonage Messages API, демонстрируя, как инициализаторы Rails позволяют вынести настройку SDK из контроллеров в правильное место.

TL;DR Пример кода на GitHub

TL;DR Пример кода на GitHub

Предварительные требования

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

• Установленный Ruby 3.x (проверьте с помощью ruby -v)

Установленный Ruby 3.x (проверьте с помощью ruby -v)

• Rails 6.1 или новее

Rails 6.1 или новее

• Учетная запись Vonage с приложением Vonage, идентификатором приложения и закрытым ключом

Учетная запись Vonage с приложением Vonage, идентификатором приложения и закрытым ключом

Если вы еще не создали приложение Vonage, перейдите в панель управления Vonage, создайте новое приложение и включите возможность Messages. При появлении запроса сгенерируйте пару открытого/закрытого ключей и загрузите файл закрытого ключа. Держите их под рукой. Они скоро вам понадобятся.

При создании приложения Vonage панель управления запросит у вас URL-адреса для входящих сообщений и статусов вебхуков. Пока используйте значения-заполнители (например, https://example.com/webhooks/inbound и https://example.com/webhooks/status). Вы сможете обновить их на реальные URL-адреса после развертывания приложения.

• Чтобы создать приложение, перейдите на страницу Создание приложения в панели управления Vonage и укажите имя для вашего приложения.

Чтобы создать приложение, перейдите на страницу Создание приложения в панели управления Vonage и укажите имя для вашего приложения.

• Если вы планируете использовать API, который работает с вебхуками, вам понадобится закрытый ключ. Нажмите «Generate public and private key», загрузка должна начаться автоматически. Храните его в безопасности; этот ключ нельзя будет загрузить повторно, если он будет утерян. Он будет следовать соглашению об именовании private_<ваш id приложения>.key. Этот ключ теперь можно использовать для аутентификации вызовов API. Примечание: ваш ключ не будет работать, пока приложение не будет сохранено.

Если вы планируете использовать API, который работает с вебхуками, вам понадобится закрытый ключ. Нажмите «Generate public and private key», загрузка должна начаться автоматически. Храните его в безопасности; этот ключ нельзя будет загрузить повторно, если он будет утерян. Он будет следовать соглашению об именовании private_<ваш id приложения>.key. Этот ключ теперь можно использовать для аутентификации вызовов API. Примечание: ваш ключ не будет работать, пока приложение не будет сохранено.

• Выберите необходимые возможности (например, Voice, Messages, RTC и т. д.) и укажите требуемые вебхуки (например, URL-адреса событий, URL-адреса ответов или URL-адреса входящих сообщений). Они будут описаны в руководстве.

Выберите необходимые возможности (например, Voice, Messages, RTC и т. д.) и укажите требуемые вебхуки (например, URL-адреса событий, URL-адреса ответов или URL-адреса входящих сообщений). Они будут описаны в руководстве.

• Чтобы сохранить и развернуть, нажмите «Generate new application» для завершения настройки. Ваше приложение теперь готово к использованию с API Vonage.

Чтобы сохранить и развернуть, нажмите «Generate new application» для завершения настройки. Ваше приложение теперь готово к использованию с API Vonage.

Создание нового Rails API приложения

Начните с чистого Rails API приложения:

Флаг --api делает проект легким, удаляя представления и промежуточное ПО браузера, которые не понадобятся для бэкенд-сервиса обмена сообщениями.

Добавление гема

Откройте Gemfile в редакторе и добавьте:

Обратите внимание на подчеркивание в vonage_rails — имя гема в Gemfile использует подчеркивания, а не дефисы. Сохраните файл, затем выполните:

Посмотреть на GitHub: Gemfile

vonage_rails поставляется с dotenv-rails в качестве зависимости времени выполнения, поэтому он устанавливается автоматически. Стоит знать: поскольку это зависимость времени выполнения (не ограниченная :development или :test), файлы .env будут загружаться во всех средах, включая production. В production предпочтительнее устанавливать переменные окружения напрямую через менеджер секретов или конфигурацию вашей платформы, а не полагаться на файл .env.

Настройка переменных окружения

Поместите файл закрытого ключа в корень проекта. Затем создайте файл .env в корне:

Посмотреть на GitHub: .env.example

Замените your_application_id_here на идентификатор приложения из панели управления Vonage и убедитесь, что private.key совпадает с именем загруженного вами файла. Замените 447700900000 на виртуальный номер Vonage, привязанный к вашему приложению Vonage.

Примечание: значение для VONAGE_PRIVATE_KEY — это путь к файлу вашего закрытого ключа, а не содержимое ключа. Vonage.setup считывает файл автоматически.

Перед тем как делать коммит, добавьте оба файла в .gitignore:

Посмотреть на GitHub: .gitignore

Запуск генератора инициализатора

После установки гема запустите генератор:

Это создаст файл config/initializers/vonage.rb.

Сгенерированный файл

Откройте файл, и вы увидите блок Vonage.setup с пятью явными обращениями к ENV:

Как это работает

При загрузке Rails загружает инициализатор, вызывает Vonage.setup и настраивает модуль Vonage. Гем использует модуль Ruby Forwardable для делегирования каждого вызова метода в Vonage базовому экземпляру Vonage::Client. Константа Vonage — это сам модуль, а не переназначенный экземпляр клиента, поэтому Vonage.messaging, Vonage.voice и остальные работают корректно.

С этого момента любой контроллер, сервис или фоновая задача имеют доступ ко всем API, поддерживаемым Ruby SDK, через ту же константу Vonage:

Константа

API

Vonage.messaging

Messages API (SMS, MMS, WhatsApp, RCS)

Vonage.voice

Voice API

Vonage.verify

Verify API

Vonage.numbers

Numbers API

Vonage.number_insight

Number Insight API

Vonage.account

Account API

Vonage.applications

Applications API

Vonage.conversations

Conversation API

Vonage.subaccounts

Subaccounts API

Vonage.redact

Redact API

Vonage.sms

SMS API (устаревший)

В этой таблице показан часто используемый набор. Ruby SDK в настоящее время предоставляет в общей сложности 29 делегированных пространств имен. Делегирование настраивается один раз при загрузке гема для Vonage::Client.instance_methods(false). Когда SDK добавляет новый API, он становится доступным через Vonage после выполнения bundle update vonage и перезапуска сервера.

Создание эндпоинта

После настройки инициализатора подключите контроллер и маршрут.

Создайте контроллер:

Это создаст файл контроллера, а также добавит get "messages/create" в config/routes.rb. Замените все содержимое config/routes.rb на правильный POST-маршрут:

Посмотреть на GitHub: config/routes.rb

Теперь обновите действие контроллера для отправки текстового сообщения с использованием глобальной константы Vonage:

Посмотреть на GitHub: app/controllers/messages_controller.rb

Успешный ответ Messages API содержит message_uuid. Если это поле присутствует, сообщение было принято к доставке. Обработка ошибок сбоев сети и ошибок API здесь опущена для краткости; полный репозиторий включает более полную реализацию.

Запустите сервер:

В новом окне терминала отправьте тестовый запрос. Параметр to — это реальный мобильный номер получателя в формате E.164, на который вы хотите отправить сообщение:

При указании действительных учетных данных вы получите {"status":"sent","message_uuid":"..."} и текстовое сообщение на номер получателя.

Полезно знать

Тестирование

Вам не нужно выполнять реальные вызовы API во время тестов. Сначала добавьте rspec-rails в ваш Gemfile:

Затем выполните:

Заглушите константу Vonage на уровне метода с помощью тестового дублера:

Это обеспечивает быстроту набора тестов, избавляет от необходимости указывать учетные данные в CI и позволяет сосредоточить проверки на поведении контроллера.

Примечание: Убедитесь в соответствии Vonage::Messaging установленной версии SDK перед использованием instance_double. Если имя класса отличается, RSpec немедленно сообщит о несоответствии.

Примечание: Убедитесь в соответствии Vonage::Messaging установленной версии SDK перед использованием instance_double. Если имя класса отличается, RSpec немедленно сообщит о несоответствии.

API Key и Secret

Не всем API Vonage требуются API key и secret. Messages API использует JWT-аутентификацию (ваш идентификатор приложения и закрытый ключ), поэтому в данном случае можно оставить эти переменные окружения (ENV) не заданными. Для API, которым они требуются, обратитесь к документации Vonage API и добавьте их в файл .env при необходимости.

Vonage.messaging.send затеняет Object#send

Такова собственная архитектура SDK, и она работает, но это удивляет разработчиков при первом знакомстве. Vonage.messaging.send(...) — это не встроенный в Ruby метод Object#send. Это эндпоинт отправки Vonage Messages API, представленный в виде метода Ruby. Если вы выполняете отладку и пытаетесь вызвать метод динамически с помощью Object#send, используйте вместо него public_send во избежание конфликта.

Несколько клиентов Vonage

Константа Vonage представляет собой один настроенный экземпляр. Если вашему приложению требуется два отдельных клиента, например один для обмена сообщениями, а другой для другого приложения Vonage с отдельными учетными данными, определите вторую именованную константу в том же инициализаторе. Поскольку Vonage.setup выполняет разрешение путей File.exist?, а чистый Vonage::Client.new — нет, при обходе метода setup вам необходимо передавать содержимое ключей напрямую:

Это редкий сценарий для большинства приложений, но этот паттерн полезно знать до того, как он вам понадобится.

Заключение

Гем vonage-rails отлично справляется с одной задачей: он размещает настройку клиента Vonage там, где ей положено быть — в инициализаторе, который запускается один раз при загрузке. Ваши учетные данные остаются в окружении, контроллеры сосредоточены на логике приложения, а любой API Vonage доступен через вызов одного метода из любой точки приложения.