... Старый API после некоторых доработок потерял совместимость, поэтому мы решили выпустить вторую версию. {toc} Рекомендуем использовать эту версию для написания запросов. Формат дат для параметров запросов: {code} %Y-%m-%d %H:%M:%S {code} {code} %Y-%m-%d {code} Отличия от старой версии: * Новый адрес для запросов: 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 запрос для абонентов и по запросу на каждого абонента для получения его учетных записей)* h2. Описание формата *Формат ответа:* {code} {"call": "/rest_api/v2/<model_name>/", "result": [<объект>, ...]} {code} тип поля result будет меняться в соответствии с данными (список для перечня объектов (objects.filter), словарь для 1 объекта (objects.get), значение метода при вызове метода и.т.д). *Формат ошибки:* {code} {"call": "/rest_api/v2/<model_name>/", "error": "..."} {code} если в результате есть не пустое поле error, то значит запрос завершился неуспешно *Формат объекта:* {code} {"pk": <id>, "model": "<model>", "fields": {"<field>": <value>, ...} {code} Если поле является ссылкой fk (например поле tarif у модели Abonents), то объект тарифа можно получить, задав fields=\["tarif"\], а pk тарифа, задав fields=\["tarif_id"\], например: {code} {"pk": <id>, "model": "Abonents", "fields": {"tarif": {"pk": <id тарифа>, "model": "Tarif", "fields": {<поля тарифа>}, "tarif_id": <id тарифа>} {code} Также, можно вывести только определенные поля тарифа через двойное подчеркивание: fields=\["tarif__name"\]: {code} {"pk": <id>, "model": "Abonents", "fields": {"tarif": {"pk": <id тарифа>, "model": "Tarif", "fields": {"name": <имя тарифа>}, "tarif_id": <id тарифа>} {code} Еще пример. Запрос ip адресов всех учетных записей абонента fields=\["abonent_id_users__ip"\]: {code} {"pk": <id>, "model": "Abonents", "fields": {"abonent_id_users": [{"pk": <id учетной записи>, "model": "Users", "fields": {"ip": "<ip>"}}, ...]}} {code} h3. Формирование запросов {code} 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 - {code} h3. Документация по методам и моделям Вызовите в браузере http://<ip>:8082/rest_api/v2/ и выберите интересующую модель. Например, демо: [http://demo5.carbonsoft.ru/rest_api/v2/] h2. Примеры Готовые примеры работы с API с помощью Python вы можете посмотреть здесь: [github|https://github.com/carbonsoft/rest_api_example] *Пример 1. Вывести абонентов, у которых есть учетная запись с ip = 127.1.2.3:* {code} curl -XPOST -d 'method1=objects.filter&arg1={"abonent_id_users__ip":"127.1.2.3"}' http://<ip>:8082/rest_api/v2/Abonents/ -D - {code} *или количество таких абонентов:* {code} 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 - {code} *Пример 2. Установить абоненту с id = 45 номер квартиры 3:* {code} 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={}'; {code} *Пример 3. Подключение услуги id=532 абоненту с номером договора BILL0000021* {code} 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}' {code} *Пример 4. Сколько абоненту с номером договора 1005633 нужно заплатить что проработать до 2016-10-20* {code} 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/ {code} *Пример 5. Выполнение отчёта 1003 с параметром phone="+79222222222"* {code} 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 - {code} *Пример 6. По абоненту с id=1383 вывести значение реквизита с id=26* {code} curl -XPOST -d 'method1=objects.filter&arg1={"abonent":"1383", "attribute":"26"}' http://<ip-биллинга>:8082/rest_api/v2/AttributeValues/ -D - {code} *Пример 7. Пример создания абонента с именем abonent, в папке 1 с тарифом с id 1* {code} 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)) {code} *Пример 8. Установить абоненту с id 1321 тариф с именем Тестовый* 1. Получаем id тарифа по имени {code} curl -XPOST -d 'method1=objects.get&arg1={"name":"Тестовый"}' http://<ip-биллинга>:8082/rest_api/v2/tarif/ -D - {code} В поле pk получаем id тарифа, в данном случае 1118 2. Устанавливаем тариф абоненту по id {code} 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 - {code} *Пример 9. Установить абоненту с номером учетной записи 1361 коммутатор с IP 1.1.1.1* 1. Получаем id коммутатора по IP {code} curl -XPOST -d 'method1=objects.get&arg1={"ip":"1.1.1.1"}' http://<ip-биллинга>:8082/rest_api/v2/Switch/ -D - {code} В поле pk получаем id коммутатора, в данном случае 1113 2. Устанавливаем коммутатор в учетную запись по id {code} 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 - {code} *Пример 10. Установить абоненту с номером учетной записи 1361 vlan 8* {code} 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 - {code} *Пример 11. Установить абоненту с номером учетной записи 1361 mac-адрес 00:AA:CC:11:44:88* {code} 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 - {code} *Пример 12. Установить абоненту с номером учетной записи 1361 галочку opt82* {code} 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 - {code} *Пример 13. Установить абоненту с номером учетной записи 1361 порт номер 8 коммутатора 2.2.2.2* 1. Получаем id коммутатора по IP {code} curl -XPOST -d 'method1=objects.get&arg1={"ip":"2.2.2.2"}' http://<ip-биллинга>:8082/rest_api/v2/Switch/ -D - {code} В поле pk получаем id коммутатора, в данном случае 1114 2. Получаем id порта по его номеру {code} curl -XPOST -d 'method1=objects.get&arg1={"switch_id":"1114","num":"8"}' http://<ip-биллинга>:8082/rest_api/v2/SwitchPorts/ -D - {code} В поле pk получаем id порта коммутатора, в данном случае 1168 3. Устанавливаем порт в учетной записи по id порта из БД {code} 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 - {code} *Пример 14. Установить абоненту с id 1321 заявку на смену тарифа с именем "Другой" на 2016-05-26* 1. Получаем id тарифа по имени {code} curl -XPOST -d 'method1=objects.get&arg1={"name":"Другой"}' http://<ip-биллинга>:8082/rest_api/v2/tarif/ -D - {code} В поле pk получаем id тарифа, в данном случае 1119 2. Добавляем заявку на смену и дату смены {code} 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 {code} *Пример 15. Создание абонента и добавление ему учетной записи* 1. Создаем абонента abonent с тарифом Основной(id=1) в группе Все (id=1) {code} curl -XPOST -d 'method1=objects.create&arg1={"name":"abonent", "parent_id":1, "tarif_id":1}' http://<ip-биллинга>:8082/rest_api/v2/Abonents/ -D - {code} В поле pk получаем id абонента. В данном случае id 1339 2. Создаем учетную запись по id абонента, указывая логин abonent1. {code} curl -XPOST -d 'method1=objects.create&arg1={"abonent_id":"1339", "login":"abonent1"}' http://<ip-биллинга>:8082/rest_api/v2/Users/ -D - {code} Пароль при этом генерирует биллинг. *Пример 16. Получить данные по учетным записям абонента* {code} curl -XPOST -d 'method1=objects.filter&arg1={"abonent__pk":"1234"}' 'http://169.254.80.82:8082/rest_api/v2/Users/' -D - {code} *Пример 17. Получить логин, ip адрес, название атрибута в тарифе абонента, значение атрибута в тарифе абонента по незаблокированным абонентам* {code} 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"]' {code} *Пример 18. Добавить абоненту с id 100 атрибут, который имеет id 200 со значением 300* {code} 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"}' {code} BASH скрипт, который добавляет физ.лицам атрибут, который имеет id 200 со значением 300 {code} 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 {code} *Пример 19. Отправить абоненту id 1313 сообщение по шаблону с id 1 методом sms-оповещения* {code}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 -{code} *Пример 20. Сделать приход 10 рублей абоненту с номером договора BILL0000021* {code}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 -{code} *Пример 21. Создать абонента ФИО abonent в директории с id 1 (Все), tarif_id 1 (Основной тариф) и балансом 10р* {code}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 -{code} *Пример 22. Ввод начальных остатков/синхронизация балансов. Установить абоненту с id 1111 баланс бухгалтерский в объёме 50.5р, комментарий к финансовой операции "Миграция балансов"* {code}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 -{code} h6. Пример 22.1 Ввод начальных остатков в зависимости от номера договора. В примере указан номер договора 'test'. Номер договора обязательно должен быть экранирован кавычками ''. {code} 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 {code} *Пример 23. Добавление дома в справочник "Дома". Дом будет создан с адресом г.Москва Ленина 5* {code}curl -XPOST -d 'method1=objects.create&arg1={"city":"Москва", "street":"Ленина", "s_number":'5'}' http://169.254.80.82:8082/rest_api/v2/Homes/ -D{code} *Пример 24. Добавления пула домов с помощью Bash скрипта. Будет создано 5 домов :1,2,3,4,5 c адресом г. Москва Ленина 1, г. Москва Ленина 2 и т.д. X - номер первого дома в пуле.* {code}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{code} *Пример 25. Получение баланса по абоненту.* {code}curl -XPOST -d 'method1=objects.get&arg1={"account_id_abonents":"<ID-абонента>"}&fields=["balance"]' http://<ip-биллинга>:8082/rest_api/v2/AdminAccounts/ -D -{code} *Пример 25. Установка значения в поле "Порог отключения"* {code}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 -{code} *Пример 26. Установка значения в поле "Порог предупреждения" всей группе с помощью bash скрипта. В примере указана группа с id 1316 и Порог предупреждения - 12000* {code} 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 {code} *Пример 27. Получить полный лог звонков абонентов за указанный период (включая обе даты)* {code}curl -XPOST -d 'method1=objects.filter&arg1={"s_time__gt":"2017-11-20", "s_time__lte":"2017-12-01"}' http://168.254.80.82:8082/rest_api/v2/VoipLog/ -D -{code} *Пример 28. Поменять учетной записи с id 1395 snatip на 8.8.8.8* {code} curl -XPOST -d 'method1=objects.get&arg1={"id":'1395'}&method2=set&arg2={"snatip":"8.8.8.8"}&method3=save&arg3={}' http://169.254.80.82:8082/rest_api/v2/Users/ -D - {code} *Пример 29. Поменять всем абонентам из папки с id 1000 snat_pull на snat_pull с id 1030* {code}
|