API REST v2.0

Skip to end of metadata
Go to start of metadata

Старый API после некоторых доработок потерял совместимость, поэтому мы решили выпустить вторую версию.

Рекомендуем использовать эту версию для написания запросов.
Формат дат для параметров запросов:

%Y-%m-%d %H:%M:%S
%Y-%m-%d

Отличия от старой версии:

  • Новый адрес для запросов: http://<ip>:8082/rest_api/v2/
  • Вместо передачи параметров в GET, перешли на POST
  • Убрали из вывода результаты промежуточных вызовов (method1, method2,..), оставили только result
  • Соответственно, немного поменялся схема вывода (см. соответствующий раздел)
  • Модель указывается в url напрямую, например: http://<ip>:8082/rest_api/v2/Abonents/
  • Атрибут запроса fields теперь не нужно маркировать номером метода. Он будет применяться к последнему объекту (возвращенному последним методом)
  • Документацию (пока что только перечень доступных полей для запроса) можно посмотреть, пройдя браузером по ссылке http://<ip>:8082/rest_api/v2/
  • Теперь можно в fields запрашивать вывод объектов по ссылкам (fk, m2m), обратным ссылкам и выводить property объектов, а также выводить конкретные поля этих объектов. Глубина запроса не ограничена, разделитель - двойное подчеркивание. Внимание! Django не объединяет запрос по обратной ссылке в один, поэтому он может выполняться заметно дольше для большого кол-ва объектов (например, если запросить все учетные записи у всех абонентов - будет 1 запрос для абонентов и по запросу на каждого абонента для получения его учетных записей)

Описание формата

Формат ответа:

{"call": "/rest_api/v2/<model_name>/", "result": [<объект>, ...]}

тип поля result будет меняться в соответствии с данными (список для перечня объектов (objects.filter), словарь для 1 объекта (objects.get), значение метода при вызове метода и.т.д).

Формат ошибки:

{"call": "/rest_api/v2/<model_name>/", "error": "..."}

если в результате есть не пустое поле error, то значит запрос завершился неуспешно

Формат объекта:

{"pk": <id>, "model": "<model>", "fields": {"<field>": <value>, ...}

Если поле является ссылкой fk (например поле tarif у модели Abonents), то объект тарифа можно получить, задав fields=["tarif"], а pk тарифа, задав fields=["tarif_id"], например:

{"pk": <id>, "model": "Abonents", "fields": {"tarif": {"pk": <id тарифа>, "model": "Tarif", "fields": {<поля тарифа>},  "tarif_id": <id тарифа>}

Также, можно вывести только определенные поля тарифа через двойное подчеркивание: fields=["tarif__name"]:

{"pk": <id>, "model": "Abonents", "fields": {"tarif": {"pk":  <id тарифа>, "model": "Tarif", "fields": {"name": <имя тарифа>},   "tarif_id": <id тарифа>}

Еще пример. Запрос ip адресов всех учетных записей абонента fields=["abonent_id_users__ip"]:

{"pk": <id>, "model": "Abonents", "fields": {"abonent_id_users": [{"pk": <id учетной записи>, "model": "Users", "fields": {"ip": "<ip>"}}, ...]}}

Формирование запросов

curl -XPOST -d 'method1=objects.all&arg1={}&fields=["tarif_id","tarif","abonent_id_users__ip","attr","child_folders_count"]' http://<ip>:8082/rest_api/v2/Abonents/ -D -
curl -XPOST -d 'method1=objects.all&arg1={}&fields=["tarif_id","tarif__name","tarif__reserve_plan","abonent_id_users__ip","attr","child_folders_count"]' http://<ip>:8082/rest_api/v2/Abonents/ -D -

Документация по методам и моделям

Вызовите в браузере http://<ip>:8082/rest_api/v2/ и выберите интересующую модель.

Например, демо:

http://demo5.carbonsoft.ru/rest_api/v2/

Примеры

Готовые примеры работы с API с помощью Python вы можете посмотреть здесь:

github

Пример 1. Вывести абонентов, у которых есть учетная запись с ip = 127.1.2.3:

curl -XPOST -d 'method1=objects.filter&arg1={"abonent_id_users__ip":"127.1.2.3"}' http://<ip>:8082/rest_api/v2/Abonents/ -D -

или количество таких абонентов:

curl -XPOST -d 'method1=objects.filter&arg1={"abonent_id_users__ip":"127.1.2.3"}&method2=count&arg2={}' http://<ip>:8082/rest_api/v2/Abonents/ -D -

Пример 2. Установить абоненту с id = 45 номер квартиры 3:

curl -XPOST 'http://<ip>:8082/rest_api/v2/Abonents/' --data 'method1=objects.get&arg1={"id":"45"}&method2=set&arg2={"a_home_number":"3"}&method3=save&arg3={}';

Пример 3. Подключение услуги id=532 абоненту с номером договора BILL0000021

curl -XPOST -d 'http://<ip>:8082/rest_api/v2/Abonents/' --data 'method1=objects.get&arg1={"contract_number":"BILL0000021"}&method2=add_service&arg2={"usluga_id":532}'

Пример 4. Сколько абоненту с номером договора 1005633 нужно заплатить что проработать до 2016-10-20

curl -XPOST -d 'method1=objects.get&arg1={"contract_number":"1005633"}&method2=get_credit_for&arg2={"end_credit_date":"2016-10-20"}' http://169.1.80.82:8082/rest_api/v2/Abonents/

Пример 5. Выполнение отчёта 1003 с параметром phone="+79222222222"

curl -XPOST -d 'method1=objects.get&arg1={"id":1003}&method2=get_data&arg2={"phone":"+79222222222"}' http://169.1.80.82:8082/rest_api/v2/AdminCustomReports/ -D -

Пример 6. По абоненту с id=1383 вывести значение реквизита с id=26

curl -XPOST -d 'method1=objects.filter&arg1={"abonent":"1383", "attribute":"26"}' http://<ip-биллинга>:8082/rest_api/v2/AttributeValues/ -D -

Пример 7. Пример создания абонента с именем abonent, в папке 1 с тарифом с id 1

def create_abonent(self, **kwargs):
params = {
'url': '(billing_url)/Abonents/'.format(self.api_url),
'method1': 'objects.create',
'arg1': {"name": "abonent", '"parent_id": 1,"tarif_id": 1}.
 }
 return self.get_api_result(self.post_request(**params))

Пример 8. Установить абоненту с id 1321 тариф с именем Тестовый

1. Получаем id тарифа по имени

 curl -XPOST -d 'method1=objects.get&arg1={"name":"Тестовый"}' http://<ip-биллинга>:8082/rest_api/v2/tarif/ -D -

В поле pk получаем id тарифа, в данном случае 1118

2. Устанавливаем тариф абоненту по id

 curl -XPOST -d 'method1=objects.get&arg1={"id":"1321"}&method2=set&arg2={"tarif_id":"1118"}&method3=save&arg3={}' http://<ip-биллинга>:8082/rest_api/v2/Abonents/ -D -

Пример 9. Установить абоненту с номером учетной записи 1361 коммутатор с IP 1.1.1.1

1. Получаем id коммутатора по IP

curl -XPOST -d 'method1=objects.get&arg1={"ip":"1.1.1.1"}' http://<ip-биллинга>:8082/rest_api/v2/Switch/ -D -

В поле pk получаем id коммутатора, в данном случае 1113

2. Устанавливаем коммутатор в учетную запись по id

curl -XPOST -d 'method1=objects.get&arg1={"id":"1361"}&method2=set&arg2={"switch_id":"1113"}&method3=save&arg3={}' http://<ip-биллинга>:8082/rest_api/v2/Users/ -D -

Пример 10. Установить абоненту с номером учетной записи 1361 vlan 8

curl -XPOST -d 'method1=objects.get&arg1={"id":"1361"}&method2=set&arg2={"router_vlan":"8"}&method3=save&arg3={}' http://<ip-биллинга>:8082/rest_api/v2/Users/ -D -

Пример 11. Установить абоненту с номером учетной записи 1361 mac-адрес 00:AA:CC:11:44:88

curl -XPOST -d 'method1=objects.get&arg1={"id":"1361"}&method2=set&arg2={"mac":"00:AA:CC:11:44:88"}&method3=save&arg3={}' http://<ip-биллинга>:8082/rest_api/v2/Users/ -D -

Пример 12. Установить абоненту с номером учетной записи 1361 галочку opt82

curl -XPOST -d 'method1=objects.get&arg1={"id":"1361"}&method2=set&arg2={"opt82":"1"}&method3=save&arg3={}' http://10.90.180.180:8082/rest_api/v2/Users/ -D -

Пример 13. Установить абоненту с номером учетной записи 1361 порт номер 8 коммутатора 2.2.2.2

1. Получаем id коммутатора по IP

curl -XPOST -d 'method1=objects.get&arg1={"ip":"2.2.2.2"}' http://<ip-биллинга>:8082/rest_api/v2/Switch/ -D -

В поле pk получаем id коммутатора, в данном случае 1114

2. Получаем id порта по его номеру

curl -XPOST -d 'method1=objects.get&arg1={"switch_id":"1114","num":"8"}' http://<ip-биллинга>:8082/rest_api/v2/SwitchPorts/ -D -

В поле pk получаем id порта коммутатора, в данном случае 1168

3. Устанавливаем порт в учетной записи по id порта из БД

curl -XPOST -d 'method1=objects.get&arg1={"id":"1361"}&method2=set&arg2={"switch_p":"1168"}&method3=save&arg3={}' http://<ip-биллинга>:8082/rest_api/v2/Users/ -D -

Пример 14. Установить абоненту с id 1321 заявку на смену тарифа с именем "Другой" на 2016-05-26

1. Получаем id тарифа по имени

 curl -XPOST -d 'method1=objects.get&arg1={"name":"Другой"}' http://<ip-биллинга>:8082/rest_api/v2/tarif/ -D -

В поле pk получаем id тарифа, в данном случае 1119

2. Добавляем заявку на смену и дату смены

curl -XPOST -d 'method1=objects.get&arg1={"id":"1321"}&method2=set&arg2={"tarif_next_id":"1119","tarif_next_date":"2016-05-26"}&method3=save&arg3={}' http://<ip-биллинга>:8082/rest_api/v2/Abonents/ -D

Пример 15. Создание абонента и добавление ему учетной записи
1. Создаем абонента abonent с тарифом Основной(id=1) в группе Все (id=1)

curl -XPOST -d 'method1=objects.create&arg1={"name":"abonent", "parent_id":1, "tarif_id":1}' http://<ip-биллинга>:8082/rest_api/v2/Abonents/ -D -

В поле pk получаем id абонента. В данном случае id 1339

2. Создаем учетную запись по id абонента, указывая логин abonent1.

curl -XPOST -d 'method1=objects.create&arg1={"abonent_id":"1339", "login":"abonent1"}' http://<ip-биллинга>:8082/rest_api/v2/Users/ -D -

Пароль при этом генерирует биллинг.

Пример 16. Получить данные по учетным записям абонента

curl -XPOST -d 'method1=objects.filter&arg1={"abonent__pk":"1234"}' 'http://169.254.80.82:8082/rest_api/v2/Users/' -D -

Пример 17. Получить логин, ip адрес, название атрибута в тарифе абонента, значение атрибута в тарифе абонента по незаблокированным абонентам

curl "http://169.254.80.82:8082/rest_api/v2/Users/" -XPOST -d 'method1=objects.filter&arg1={"abonent__deleted": 0, "abonent__abonent_id_abonentsblock__isnull": 1}&fields=["ip", "login", "abonent__tarif__tarif_id_tarifradiusparams__attribute", "abonent__tarif__tarif_id_tarifradiusparams__thevalue"]'

Пример 18. Добавить абоненту с id 100 атрибут, который имеет id 200 со значением 300

curl -XPOST 'http://169.254.80.82:8082/rest_api/v2/AttributeValues/' --data 'method1=objects.create&arg1={"abonent_id":"100","attribute_id":"200","attribute_value":"300"}'

BASH скрипт, который добавляет физ.лицам атрибут, который имеет id 200 со значением 300

sqlexec "set list on; select id from abonents where company=0" | awk ' {print $2} ' | sed '/^$/d' | while read line; do curl -XPOST 'http://169.254.80.82:8082/rest_api/v2/AttributeValues/' --data 'method1=objects.create&arg1={"abonent_id":'$line',"attribute_id":"200","attribute_value":"300"}'; done

Пример 19. Отправить абоненту id 1313 сообщение по шаблону с id 1 методом sms-оповещения

curl -XPOST -d 'method1=objects.create&arg1={"abonent_id": "1313", "admin_msg_id": "1", "ttype_id": "1"}' 'http://169.254.80.82:8082/rest_api/v2/MsgStack/' -D -

Пример 20. Сделать приход 10 рублей абоненту с номером договора BILL0000021

curl -XPOST -d 'method1=objects.get&arg1={"contract_number": "BILL0000021"}&method2=add_payment&arg2={"SUM_IN": "10"}' 'http://169.254.80.82:8082/rest_api/v2/Abonents/' -D -

Пример 21. Создать абонента ФИО abonent в директории с id 1 (Все), tarif_id 1 (Основной тариф) и балансом 10р

curl -XPOST -d 'method1=objects.create&arg1={"name":"abonent", "parent_id":1, "tarif_id":1}&method2=add_payment&arg2={"SUM_IN": "10"}' http://169.254.80.82:8082/rest_api/v2/Abonents/ -D -

Пример 22. Ввод начальных остатков/синхронизация балансов. Установить абоненту с id 1111 баланс бухгалтерский в объёме 50.5р, комментарий к финансовой операции "Миграция балансов"

curl -XPOST -d 'method1=objects.create&arg1={"abonent_id": 1111, "op_summa": "50.5", "op_type_id": 8, "descr": "Миграция балансов"}' 'http://169.254.80.82:8082/rest_api/v2/FinanceOperations/' -D -
Пример 22.1 Ввод начальных остатков в зависимости от номера договора. В примере указан номер договора 'test'. Номер договора обязательно должен быть экранирован кавычками ''.
sqlexec "set list on; select id from abonents where contract_number='test'" | awk ' {print $2} ' | sed '/^$/d' | while read line; do curl -XPOST -d 'method1=objects.create&arg1={"abonent_id":'$line', "op_summa": "50.5", "op_type_id": 8, "descr": "Миграция балансов"}' 'http://169.254.80.82:8082/rest_api/v2/FinanceOperations/' -D -; done

Пример 23. Добавление дома в справочник "Дома". Дом будет создан с адресом г.Москва Ленина 5

curl -XPOST -d 'method1=objects.create&arg1={"city":"Москва", "street":"Ленина", "s_number":'5'}' http://169.254.80.82:8082/rest_api/v2/Homes/ -D

Пример 24. Добавления пула домов с помощью Bash скрипта. Будет создано 5 домов :1,2,3,4,5 c адресом г. Москва Ленина 1, г. Москва Ленина 2 и т.д. X - номер первого дома в пуле.

X=1; while [ "$X" -lt "6" ]; do curl -XPOST -d 'method1=objects.create&arg1={"city":"Москва", "street":"Ленина", "s_number":'$X'}' http://169.254.80.82:8082/rest_api/v2/Homes/ -D -;X=$((X+1)); done

Пример 25. Получение баланса по абоненту.

curl -XPOST -d 'method1=objects.get&arg1={"account_id_abonents":"<ID-абонента>"}&fields=["balance"]' http://<ip-биллинга>:8082/rest_api/v2/AdminAccounts/ -D -

Пример 25. Установка значения в поле "Порог отключения"

curl -XPOST -d 'method1=objects.get&arg1={"account_id_abonents":"<ID-абонента>"}&method2=set&arg2={"limit":"-5000"}&method3=save&arg3={}' http://<ip-биллинга>:8082/rest_api/v2/AdminAccounts/ -D -

Пример 26. Установка значения в поле "Порог предупреждения" всей группе с помощью bash скрипта. В примере указана группа с id 1316 и Порог предупреждения - 12000

sqlexec "set list on; select id from abonents where parent_id=1316" | awk ' {print $2} ' | sed '/^$/d' | while read line; do curl -XPOST -d 'method1=objects.get&arg1={"account_id_abonents":'$line'}&method2=set&arg2={"limit_warning":"-12000"}&method3=save&arg3={}' http://169.254.80.82:8082/rest_api/v2/AdminAccounts/ -D -; done

Отладка

API-запросы и ошибки их выполнения логируются в следующие файлы:

/app/asr_billing/var/log/django/error.log
/app/asr_billing/var/log/django/api_v2.log

По-умолчанию, уровень логирования установлен в error. Для того, чтобы логировать все запросы, установите в конфигурационном файле /app/asr_billing/cfg/config уровень логирования django в info:

  • Откройте конфигурационный файл биллинга в любом удобном текстовом редакторе, например vim:
    vim /app/asr_billing/cfg/config
  • Найдите в файле опцию app['django.loglevel']= и установите её в значение info:
    app['django.loglevel']='info'
  • Перезапустите web-сервер биллинга:
    chroot /app/asr_billing/ service admin_web_server restart

По окончанию отдалдки, рекомендуется вернуть уровень логирования в статус error

Метки

Введите метки, чтобы добавить к этой странице:
Please wait 
Ищите метку? просто начните печатать.