Просмотр исходного текста страницы Динамическое управление картой сети

Компонент [[Общие компоненты сценариев#UserState|Статус объекта]] позволяет управлять составом карты сети с помощью [http://ru.wikipedia.org/wiki/JSON JSON]-форматированных команд. Это может быть полезно для решения интеграционных задач, в многосерверных решениях с внешней логикой управления, а также в проектах с постоянно изменяющимися параметрами карты сети.


__TOC__

=== Описание ===

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

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

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

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

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

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

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



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


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

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



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


Команды управления динамической картой сети передаются в строковом виде в формате [http://ru.wikipedia.org/wiki/JSON JSON].

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

<pre>
{
  "actions":[
    {...},
    ...
    {...}
  ]
}
</pre>


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

<pre>
{
  "method":"clear"
}
</pre>



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



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


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

<pre>
{
  "method":"gate-add",
  "gates":[
    {...},
    ...
    {...}
  ]
}
</pre>

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

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

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

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



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

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

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

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

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




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

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

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

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

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


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

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



==== Шлюзы ====

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

* "<span style="color:red;">id</span>":"<span style="color:gray;">01010101-0101-0101-0101-010101010101</span>" - Guid-идентификатор шлюза. 
* "<span style="color:red;">name</span>":"<span style="color:gray;">DynamicGate</span>" - Название шлюза для отображения в модуле [[Настройки оборудования|«Параметры аппаратуры»]].
* "<span style="color:red;">regtype</span>":<span style="color:gray;">2</span> - Тип регистрации (0 - без регистрации, 1 - регистрация на сервере, 2 - регистрация на шлюзе).

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

* "<span style="color:red;">address</span>":"<span style="color:gray;">192.168.0.1</span>" - Доменное имя, подставляемое в запрос.
* "<span style="color:red;">sipproxyaddress</span>":"<span style="color:gray;">192.168.0.1:5060</span>" - Адрес и порт удаленного узла, на который отправлять пакеты.


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

* "<span style="color:red;">expire</span>":<span style="color:gray;">3600</span> - Период регистрации в секундах для шлюзов с внешней регистрацией. По умолчанию ''3600''.
* "<span style="color:red;">freegate</span>":<span style="color:gray;">false</span> - Для шлюза без регистрации признак разрешения обработки неизвестных входящих. В системе не должно быть более одного шлюза для приема неизвестных входящих. По умолчанию ''false''.
* "<span style="color:red;">aliases</span>":["<span style="color:gray;">Domain1</span>", "<span style="color:gray;">Domain2</span>", "<span style="color:gray;">212.212.121.121</span>"] - Список дополнительных доменных имен, которые ассоциируются со шлюзом при поступлении входящих запросов. По умолчанию список пуст.


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

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



==== Потоки ====

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

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


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

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


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

* "<span style="color:red;">id</span>":"<span style="color:gray;">79797979-7979-7979-7979-797979797979</span>" - Guid-идентификатор линии.
* "<span style="color:red;">caption</span>":"<span style="color:gray;">LineCaption</span>" - Имя линии для отображения.
* "<span style="color:red;">code</span>":"<span style="color:gray;">LineCode</span>" - Код линии.


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

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


<div id="sipstreamprops"></div>
Дополнительные параметры SIP:

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



==== Телефоны ====


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

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


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

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


Дополнительные параметры SIP аналогичны [[#sipstreamprops|параметрам потоков]].


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


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

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

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

<pre>
{
  "method":"hw-set",
  "items":[
    {
      "key":"newvalue",
      ...
    },
    ...
    {...}
  ]
}
</pre>

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

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

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


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



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

[[Special:FilePath/(Example) Dynamic SIP.oscr|(Example) Dynamic SIP.oscr]]