Динамическое управление картой сети — различия между версиями

Текущая версия на 10:00, 2 марта 2018

Техническая документация / Администрирование / Карта сети / Редактор карты сети / Динамическое управление картой сети

Компонент Статус объекта позволяет управлять составом карты сети с помощью JSON-форматированных команд. Это может быть полезно для решения интеграционных задач, в многосерверных решениях с внешней логикой управления, а также в проектах с постоянно изменяющимися параметрами карты сети.

Описание

Определенным образом формируемые параметры позволяют:

• Добавлять шлюзы (операция gate-add).
• Добавлять потоки (операция stream-add).
• Добавлять телефоны (операция phone-add).
• Удалять шлюзы со всеми потоками (операция gate-del).
• Удалять отдельные потоки (операция stream-del).
• Удалять отдельные телефоны (операция phone-del).
• Изменять параметры шлюзов (операция gate-set).
• Изменять параметры потоков (операция stream-set).
• Изменять параметры телефонов (операция phone-set).
• Удалять единовременно все динамические объекты (команда clear).
• Изменять на постоянной основе свойства конфигурации аналогично модулю "Параметры аппаратуры" (команда hw-set).

Добавленные динамические объекты не появляются среди отображаемых объектов в карте сети, но доступны в мониторинге линий, параметрах аппаратуры, и прочих модулях системы, связанных с исполнением в реальном времени.

Жизненный цикл динамических объектов протекает от момента создания до момента удаления или перезапуска системы. Таким образом при необходимости формирования постоянных настроек карты сети с помощью динамических объектов, необходимо реализовывать однократное исполнение служебной задачи, загружающей требуемые динамические объекты всякий раз после перезапуска системы. Гарантировать однократность можно в том числе с помощью глобальных переменных сценариев.

После исполнения любой операции, связанной с динамическими объектами, автоматически происходит перезагрузка сервера состояний. Это затратная операция. В этой связи настоятельно рекомендуется комбинировать все операции в один запрос, и не исполнять их в цикле одну за другой.

При создании динамических объектов, создаются динамические линии с идентификаторами, задаваемыми в запросе. Формирование этих уникальных идентификаторов возложено на администратора, создающего сценарий, поскольку привязка к ним может потребоваться в бизнес-логике реализуемого процесса для решения внешних задач. Ожидается, что идентификаторы будут уникальны.

Создание динамических потоков в шлюзах может сопровождаться автоматическим созданием направления, состоящего из всех вновь-созданных линий потока.

При создании объектов и изменении их параметров могут указываться как настройки из «Карты сети», так и настройки из «Параметров аппаратуры».

Лицензирование

При добавлении динамических объектов расходуются свободные лицензии на соответствующие линии. При удалении объектов лицензии высвобождаются. Таким образом можно использовать конкурентный механизм в отличие от статической карты сети.

В случае, если после добавления очередного объекта итоговое количество линий превосходит количество линий в лицензии, сервер произведет стандартную процедуру отключения части линий по своему усмотрению (преимущественно выключенные, неактивные).

Формат команд

Команды управления динамической картой сети передаются в строковом виде в формате JSON.

Структура команд, передаваемых серверу через компонент сценария в общем виде выглядит следующим образом:

{
  "method":"complex",
  "actions":[
    {...},
    ...
    {...}
  ]
}

Команда полной очистки динамических объектов

{
  "method":"clear"
}

Каждая команда представляет собой одну или несколько операций, возможно различных. В простейшем случае в одной команде содержится одна операция. В каждой операции может присутствовать один или несколько объектов. Так, операция добавления шлюзов может содержать мета-данные нескольких шлюзов, операция добавления потоков - несколько потоков, операция добавления телефонов - несколько SIP-телефонов. То же самое с удалением и изменением параметров.

Структура операций

Структура одной операции добавления шлюза:

{
  "method":"gate-add",
  "gates":[
    {...},
    ...
    {...}
  ]
}

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

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

Структура операции изменения шлюза отличается значением ключа method (gate-set), а также невозможностью одновременно изменять параметры потоков внутри шлюза и изменять тип регистрации (regtype).

Операция удаления шлюза (gate-del) требует указания среди свойств шлюза только идентификатора, остальное игнорируется. При удалении шлюза удаляются все его потоки, линии и динамические направления, с ними связанные.

Структура одной операции добавления потока:

{
  "method":"stream-add",
  "gates":[
    {
      "id":"_guid_шлюза_",
      "streams":[
        {...},
        ...
        {...}
      ]
    },
    ...
    {...}
  ]
}

В свойстве gates могут перечисляться несколько шлюзов. Каждый шлюз должен содержать идентификатор и набор добавляемых потоков (streams), другие его свойства игнорируются. Создаваемые потоки привязываются к содержащим их шлюзам. Каждый поток в наборе представляет собой совокупность настроек: обязательных и необязательных параметров.

Структура операции изменения потока отличается значением ключа method (stream-set).

Операция удаления потока (stream-del) требует указания среди свойств шлюза только идентификатора, остальное игнорируется. При удалении потока удаляются динамическое направление и все линии, с ним связанные.

Структура одной операции добавления SIP-телефона:

{
  "method":"phone-add",
  "phones":[
    {
      "id":"_guid_телефона_",
      ...
    },
    ...
    {...}
  ]
}

В свойстве phones могут перечисляться несколько телефонов. Каждый телефон представляет собой совокупность настроек: обязательных и необязательных параметров. Администратор, производящий настройку, должен гарантировать уникальность идентификаторов, а также уникальность и сложность авторизационных параметров телефонов.

Структура операции изменения телефона отличается значением ключа method (phone-set).

Операция удаления потока (phone-del) требует указания среди свойств шлюза только идентификатора, остальное игнорируется. При удалении потока удаляются динамическое направление и все линии, с ним связанные.

Свойства объектов

Ниже приводится список свойств различных объектов, используемый при создании. Свойства разделены на группы: обязательные свойства при создании объекта, необязательные свойства при создании объекта, у которых существуют значения по умолчанию, а также внутренние SIP-свойства объектов, доступные также в модуле «Параметры аппаратуры».

Шлюзы

Обязательные параметры:

• "id":"01010101-0101-0101-0101-010101010101" - Guid-идентификатор шлюза.
• "name":"DynamicGate" - Название шлюза для отображения в модуле «Параметры аппаратуры».
• "regtype":2 - Тип регистрации (0 - без регистрации, 1 - регистрация на сервере, 2 - регистрация на шлюзе).

Обязательные параметры (кроме шлюзов с регистрацией на сервере):

• "address":"192.168.0.1" - Доменное имя, подставляемое в запрос.
• "sipproxyaddress":"192.168.0.1:5060" - Адрес и порт удаленного узла, на который отправлять пакеты.

Необязательные параметры:

• "expire":3600 - Период регистрации в секундах для шлюзов с внешней регистрацией. По умолчанию 3600.
• "freegate":false - Для шлюза без регистрации признак разрешения обработки неизвестных входящих. В системе не должно быть более одного шлюза для приема неизвестных входящих. По умолчанию false.
• "aliases":["Domain1", "Domain2", "212.212.121.121"] - Список дополнительных доменных имен, которые ассоциируются со шлюзом при поступлении входящих запросов. По умолчанию список пуст.

Дополнительные параметры SIP:

• "interface-address":"default" - Сетевой интерфейс сервера (или default - автоопределение). По умолчанию default.
• "search-in-from":"0" - Поиск соответствия между аккаунтом и входящим INVITE (0 - contact, 1 - contact+from). По умолчанию 0.
• "def-caller-id":"1234567" - Источник определения CallerId (0 - From:URI, 1 - From:DisplayName, 2 - Contact:URI, 3 - INVITE целиком). По умолчанию 0.
• "disabled-answer":"503" - SIP-ответ при вызове на отключенный поток.
• "declined-answer":"486" - SIP-ответ при отсутствии свободных транков.
• "error-answer":"500" - SIP-ответ при ошибке резервирования транка.
• "disconnect-answer":"480" - SIP-ответ при отказе сценария IVR.

Потоки

Обязательные параметры:

• "id":"12341234-1234-1234-1234-123412341234" - Guid-идентификатор потока.
• "name":"DynamicStream" - Название потока для отображения.
• "displayname":"stream1" - SIP DisplayName.
• "username":"stream1" - SIP UserName.
• "login":"stream1" - SIP Login.
• "password":"u74S3iiB" - SIP Password.
• "lines":[{...}, ..., {...}] - список новых линий с параметрами, соответствующих потоку (рассмотрено ниже).

Необязательные параметры

• "defaultcallerid":"1234567" - Подставляемый по умолчанию CallerId.
• "codecs":[0, 1] - Список используемых кодеков через запятую в порядке уменьшения приоритета (возможные значения: 0-711u, 1-711a, 2-gsm, 3-729). По умолчанию [0, 1].
• "numbers":["account1", "account2"] - Список дополнительных номеров для ассоциации входящих звонков с потоком. По умолчанию список пуст.
• "dialmode":0 - Способ набора номеров для шлюзов с регистрацией на сервере (0-сначала аккаунт потом номер, 1-сразу номер). По умолчанию 0.
• "route":{...} - Свойства направления, которое будет создано и привязано к линиям (рассмотрено ниже).

Свойства линий:

• "id":"79797979-7979-7979-7979-797979797979" - Guid-идентификатор линии.
• "caption":"LineCaption" - Имя линии для отображения.
• "code":"LineCode" - Код линии.

Свойства направления:

• "id":"68686868-6868-6868-6868-686868686868" - Guid-идентификатор направления.
• "name":"RouteName" - Название направления.
• "description":"Route description" - Описание направления.
• "code":"routecode" - Код направления (для указания в сценариях).
• "commandtype":"0" - Режим преобразования номера перед набором (0 - нет, 1 - выражение, 2 - служебный сценарий).
• "command":"" - Выражение или название служебного сценария для преобразования номера.

Дополнительные параметры SIP:

• "enabled":0 - Включен/выключен.
• "expires":0 - Максимальный период регистрации в секундах для шлюзов с регистрацией на сервере, 0 - не ограничено. По умолчанию 3600.
• "replace-user-name":0 - Место подстановки набранного номера при исходящем вызове (0 - To+RequestURI, 1 - To, 2 - RequestURI). По умолчанию 0.
• "dtmftype":0 - Способ отправки DTMF (0 - rfc 2833, 1 - SIP INFO, 2 - InBand). По умолчанию 0.
• "enable-inband-dtmf":0 - Включение детектора звукового DTMF во входящем rtp-потоке (0 -выключен, 1 - включен). По умолчанию 0, так как операция ресурсо-затратная.
• "wait-ack":1 - Ожидать поступления сообщения ACK перед продолжением обработки входящего звонка (0 - нет, 1 - да). По умолчанию 1.
• "can-reinvite":0 - Разрешить изменять параметры связи во время коммутации (0 - нет, использовать транскодинг; 1 - да). По умолчанию 1.
• "fax-enable":0 - Разрешить прием/передачу факсов T.30 (0 - нет, 1-да). По умолчанию 0.
• "fax-outgoing-timeout":60 - Время ожидания ответа факса в секундах при исходящем сеансе. По умолчанию 60.
• "fax-enable-ecm":1 - Error Correction Mode (ECM) для факсов (0 - выключено, 1-включено). По умолчанию 1.
• "use-remote-address":1 - Адрес назначения для RTP трафика (0 - адрес/порт из SDP, 1 - адрес/порт отправителя). По умолчанию 1.
• "g711-size":0 - Размен звукового пакета при отправке RTP данных в кодеке 711a/711u (0 - 40мс, 1 - 20мс). По умолчанию 1.

Телефоны

Обязательные параметры:

• "id":"35353535-3535-3535-3535-353535353535" - Guid-идентификатор телефона и связанной с ним линии.
• "name":"DynamicPhone" - Название телефона для отображения.
• "address":"192.168.0.231:5060" - Адрес устройства для работы в режиме без регистрации.
• "username":"user" - SIP UserName.
• "login":"phone" - SIP Login (по умолчанию совпадает с SIP UserName).
• "password":"7thNx2wf" - SIP Password.

Необязательные параметры:

• "codecs":[0, 1] - Список используемых кодеков через запятую в порядке уменьшения приоритета (возможные значения: 0-711u, 1-711a, 2-gsm, 3-729). По умолчанию [0, 1].
• "defaultuserid":"84848484-8484-8484-8484-848484848484" - Guid-идентификатор пользователя, привязанного к телефону как «пользователь по умолчанию». По умолчанию без привязки.
• "websocketuserid":"84848484-8484-8484-8484-848484848484" - Guid-идентификатор пользователя, привязанного к телефону как «пользователь webcrm». По умолчанию без привязки.
• "citystraight":-1 - (-1 - по умолчанию БД, 0 - нет, 1 - да). По умолчанию -1.
• "busymode":-1 - Режим отбоя (-1 - по умолчанию БД, 0 - SIP-disconnect, 1 - генерировать короткие гудки). По умолчанию -1.
• "translit":-1 - Производить транслитерацию (-1 - согласно общим настройкам, 0 - нет, 1 - да). По умолчанию -1.
• "linecode":"DynamicPhoneCode" - Код линии.
• "department":"57575757-5757-5757-5757-575757575757" - Идентификатор существующего подразделения для привязки и отображения в разделе «Сотрудники».

Дополнительные параметры SIP аналогичны параметрам потоков.

Изменение параметров аппаратуры на постоянной основе

Изменение параметров аппаратуры может потребоваться, например, для изменения параметров внешнего адреса в разделе SIP-сервера при наладке автоматической схемы переключения на резервный интернет из-под NAT. Для изменения доступны все параметры всех разделов модуля "Параметры аппаратуры".

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

Структура команды изменения параметров конфигурации аппаратуры:

{
  "method":"hw-set",
  "items":[
    {
      "key":"newvalue",
      ...
    },
    ...
    {...}
  ]
}

• key - название параметра, подлежащего замене
• newvalue - новое значение

Доступные для изменения параметры:

• "sip/p:interface":"sip:*:5060" - интерфейс и порт для подъема SIP-сервера (применяется только при перезагрузке сервера или HAL).
• "sip/p:domain-list":"x.oktell.ru y.oktell.ru" - дополнительные доменные имена, SIP запросы на которые сервер должен обрабатывать.
• "sip/p:if192.168.0.218":"" - Настройка для работы конкретного сетевого интерфейса сервера за NAT/ address:nat_addr port:nat_port [domain:nat_dns_name]. Обратите внимание, что название ключа динамически зависит от адресов серверных интерфейсов.

Чтобы выяснить key нужного параметра, следует в конфигурационном файле сервера добавить ключ (или изменить значение) <add key="TraceHWParams" value="1"/>, после чего перезагрузить сервер и открыть модуль "Администрирование. Параметры аппаратуры". В каталоге сервера появится файл hw_out_*.xml с настройками параметров аппаратуры. Эта структура представляет собой исчерпывающий конфиг настройки, где все ключи уникальны и заданы атрибутом name в тегах. В качестве key необходимо указать значение атрибута name.

Пример сценария

(Example) Dynamic SIP.oscr