telphin_api

telphin_api
— ruby-адаптер для Телфин. Он позволяет вызывать методы API, а также поддерживает получение токена для работы с API.
Установка
gem 'telphin_api'
или просто
$ gem install telphin_api
Использование
Вызов методов
@tph = TelphinApi::Client.new
@tph.extensions.phone_call_events(:user_id => '@me', :extension_number => '00000*101', :method => :get)
@tph.extensions.phone_call_events
call_events.first.id
call_events.first.url
call_events.first.method
call_events.first.status
call_events.first.type
@tph.extensions.phone_call_events(:user_id => '@me', :extension_number => '00000*101', :method => :get) do |event|
"#{event.id} '#{event.url}' #{event.method}"
end
Авторизация
Для авторизации необходимо задать параметры app_key
(Ключ клиента), app_secret
(Секрет клиента) и site
(адрес вашего API сервера, полученного при заключении договора) в настройках TelphinApi.configure
. Более подробно о конфигурировании telphin_api
см. далее в соответствующем разделе.
telphin_api
предоставляет метод TelphinApi.authorize
, который делает запрос к Телфин, получает токен и создает клиент:
@tph = TelphinApi.authorize
@tph.token
Клиент будет содержать token пользователя, авторизовавшего приложение
Также в этот момент полезно сохранить полученный токен в БД либо в сессии, чтобы использовать их повторно:
current_user.token = @vk.token
current_user.save
@tph = TelphinApi::Client.new(current_user.token)
Прочее
Если клиент API (объект класса TelphinApi::Client
) был создан с помощью метода TelphinApi.authorize
, он будет содержать информацию о времени истечения токена (expires_at
). Получить их можно с помощью соответствующих методов:
@tph = TelphinApi.authorize
tph.expires_at
tph.expired?
Чтобы создать короткий синоним TPH
для модуля TelphinApi
, достаточно вызвать метод TelphinApi.register_alias
:
TelphinApi.register_alias
TPH::Client.new
При необходимости можно удалить синоним методом TelphinApi.unregister_alias
:
TPH.unregister_alias
TPH
Обработка ошибок
Если Телфин API возвращает ошибку, выбрасывается исключение класса TelphinApi::Error
.
tph = TPH::Client.new
@tph.extensions.phone_call_events
Логгирование
telphin_api
логгирует служебную информацию о запросах при вызове методов.
По умолчанию все пишется в STDOUT
, но в настройке можно указать
любой другой совместимый логгер, например Rails.logger
.
Есть возможность логгирования 3 типов информации,
каждому соответствует ключ в глобальных настройках.
| ключ настройки | по умолчанию | уровень логгирования |
---|
URL запроса | log_requests | true | debug |
JSON ответа при ошибке | log_errors | true | warn |
JSON удачного ответа | log_responses | false | debug |
Таким образом, в rails-приложении с настройками по умолчанию в production
записываются только ответы сервера при ошибках;
в development также логгируются URL-ы запросов.
Настройка
Глобальные параметры telphin_api
задаются в блоке TelphinApi.configure
следующим образом:
TelphinApi.configure do |config|
config.app_key = '123'
config.app_secret = 'AbCdE654'
config.site = 'https://pbx.telphin.ru/uapi'
config.adapter = :net_http
config.faraday_options = {
ssl: {
ca_path: '/usr/lib/ssl/certs'
},
proxy: {
uri: 'http://proxy.example.com',
user: 'foo',
password: 'bar'
}
}
config.max_retries = 2
config.logger = Rails.logger
config.log_requests = true
config.log_errors = true
config.log_responses = false
end
По умолчанию для HTTP-запросов используется Net::HTTP
; можно выбрать
любой другой адаптер,
поддерживаемый faraday
.
При необходимости можно указать параметры для faraday-соединения — например,
параметры прокси-сервера или путь к SSL-сертификатам.
Чтобы сгенерировать файл с настройками по умолчанию в rails-приложении,
можно воспользоваться генератором telphin_api:install
:
$ cd /path/to/app
$ rails generate telphin_api:install
JSON-парсер
telphin_api
использует парсер Oj
Также в библиотеке multi_json
(обертка для различных JSON-парсеров,
которая выбирает самый быстрый из установленных в системе и парсит им)
Oj
поддерживается и имеет наивысший приоритет; поэтому если он установлен
в системе, multi_json
будет использовать именно его.
Участие в разработке
Если вы хотите поучаствовать в разработке проекта, форкните репозиторий,
положите свои изменения в отдельную ветку, покройте их спеками
и отправьте мне pull request.
telphin_api
тестируется под MRI 2.1.2
.
Если что-то работает неправильно, либо вообще не работает,
то это следует считать багом, и написать об этом
в issues на Github.