Правило преобразования CallerId и CalledId (provider_callerid)

Содержание

Описание
Ограничения
Поля
См. также
- API

Описание

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

Обнаруженное правило модификации применяется для модификации и From username (number), и To username (number). В случае необходимости разделить модификации для сокращения количества правил, в качестве модификатора для To может быть применен специальный указатель "priority" (сначала применяется правило для FromNumber, а затем ищется и применяется правило для ToNumber, но с priority большим или равным исходному правилу и с фильтром по уже измененному FromNumber).

Настроенная совокупность правил преобразования CallerId может быть протестирована через диагностическое API. Однако следует иметь в виду, что существует разница применения в тесте и в звонке за счет того, что в звонке номер To берется из Request-Uri, а также при совпадении значения с username учетной записи сущности, в качестве номера для модификации подставляется пустая строка.

Ограничения

Коллекция недоступна в мастер-домене.

Поля

Структура сущности

{
  "id": uuid,
  "priority": int,
  "dir": str,
  "idprovider": uuid,
  "providercode": str,
  "fromdomain": str,
  "fromnumber": str,
  "tonumber": str,
  "modfromdisplay": str,
  "modfromnumber": str,
  "modtonumber": str,
  "ext": {
    "ct": date,
    "lwt": date
  },
  "opts": {
    "title": str,
    "comment": str
  }
}

Описание характеристик спецификации

Table 1. Поля
Спецификация	Описание
Поле: `id` Режим: `inout` Тип: `uuid` По умолчанию: generated	Идентификатор. Может быть задан при создании, иначе генерируется системой.
Поле: `priority` Режим: `in` Тип: `int` По умолчанию: required	Приоритет правила. Меньшее значение означает более высокий приоритет.
Поле: `dir` Режим: `in` Тип: `str` По умолчанию: required	Фильтр по направлению изменения. Правило применяется либо к данным внутреннего абонента, либо к данным внешнего абонента вне зависимости от того, в какую сторону проходит звонок. При этом звонок между внешними абонентами фактически имеет два диалога на роли esg, каждый из которых связывает внешнего абонента в качестве одного плеча диалога на роли B2BUA.
Поле: `idprovider` Режим: `in` Тип: `uuid \| str_empty` По умолчанию: str_empty	Фильтр по идентификатору провайдера SIP-телефонии. Применение этого фильтра кратно повышает скорость поиска правила.
Поле: `providercode` Режим: `in` Тип: `str` По умолчанию: empty	Маска-фильтр для кода провайдера SIP-телефонии. Режимы работы фильтров.
Поле: `fromdomain` Режим: `in` Тип: `str` По умолчанию: `"*"`	Маска-фильтр адреса/домена инициатора звонка (заголовок From SIP-запроса INVITE). Режимы работы фильтров.
Поле: `fromnumber` Режим: `in` Тип: `str` По умолчанию: `"*"`	Маска-фильтр номера/username инициатора звонка (заголовок From SIP-запроса INVITE). Режимы работы фильтров.
Поле: `tonumber` Режим: `in` Тип: `str` По умолчанию: `"*"`	Маска-фильтр номера/username назначения (заголовок To SIP-запроса INVITE). Режим работы фильтров.
Поле: `modfromdisplay` Режим: `in` Тип: `str` По умолчанию: `"*"`	Модификатор имени инициатора звонка. Результат попадает на вход процесса представления. Режимы работы модификаторов.
Поле: `modfromnumber` Режим: `in` Тип: `str` По умолчанию: `"*"`	Модификатор номера инициатора звонка. Результат попадает на вход процесса маршрутизации звонка. Режимы работы модификаторов.
Поле: `modtonumber` Режим: `in` Тип: `str` По умолчанию: `"*"`	Модификатор номера назначения звонка. Результат применения попадает на вход процесса маршрутизации звонка. Режимы работы модификаторов.
Поле: `opts` Режим: `in` Тип: `object` Составное поле
Поле: `opts.title` Режим: `in` Тип: `str` По умолчанию: empty	Произвольный заголовок
Поле: `opts.comment` Режим: `in` Тип: `str` По умолчанию: empty	Произвольный комментарий
Поле: `opts.tab` Режим: `in` Тип: `array<object>` По умолчанию: `[]`	Табличные данные для использования фильтров (и модификаторов) в рамках одной сессии поиска правила. Каждый объект в списке содержит произвольные поля, которые могут использоваться в маске в виде строки {tab:some_field}. Подробнее в разделе Режимы работы фильтра, пункт 'Таблица'". "Поле: `ext` Режим: `inout` Тип: `object` Составное поле
Позволяет расширять состав произвольными ключами и значениями	Поле: `ext.ct` Режим: `out` Тип: `date` По умолчанию: generated
Время создания объекта	Поле: `ext.lwt` Режим: `out` Тип: `date` По умолчанию: generated

Направление применения правила

Table 2. Направление применения правила
Значение	Описание
`"inner"`	В сторону от внутреннего абонента к внешнему. Правило применяется к данным внутреннего абонента при передаче их в сторону внешнего абонента.
`"outer"`	В сторону от внешнего абонента к внутреннему. Правило применяется к данным внешнего абонента при передаче их в сторону внутреннего абонента.

Режимы работы фильтров

Table 3. Режимы работы фильтров
Режим	Описание
`Посимвольный`	Подвергаемое проверке соответствия значение посимвольно проводится через фильтр. Могут применяться следующие спец-символы: `X` – любой символ; `*` – все оставшиеся символы; `?` – любой символ кроме точки; `$` – любое количество символов до ближайшей точки. При необходимости указать один из служебных символов как целевой, его следует заключать в квадратные скобки, например `[X]`.
`Таблица`	Может применяться подстрока `{tab:…}`. С помощью нее можно выделить группу символов в проверяемом значении и сопоставить их с таблицей, встроенной в правило (`opts.tab`). Например, `{tab:a}` - выделение подстроки и сопоставление ее с полем `a` всех объектов/строк в таблице. Таблица служет связке нескольких полей фильтров и модификаторов. На основании последовательной проверки фильтров в таблице остается меньшее количество строк с учетом обнаруженных совпадений. Первая из оставшихся строк служит для применения в модификаторах. При условии что в таблице не осталось строк - правило отклоняется. Захват символов из проверяемого значения на основе маски может происходить автоматически, либо со строгим указанием длины подстроки: `{tab:KEY}` - Автоматический захват из проверяемого значения. `{tab:KEY:LENGTH}` - Захват указанного количества символов из проверяемого значения. В качестве значений полей в таблице могут применяться: * константы; * регулярные выражения (для этого необходимо задать значение в формате `/reg/EXPRESSION`, например `/reg/^1[1-4]$`); * сопоставления с другими полями таблицы (для этого необходимо задать значение в формате `/tab/FIELD`, например `/tab/a`). Режим используется для связывания значений различных полей. Например, чтобы разрешить звонки только на собственный ящик голосовой почты. Необходимо строго соблюдать порядок связывания: если поле таблицы, на которое производится ссылка, еще не проверялось и не было заполнено реальным значением другого поля сущности, то сопоставление не пройдет. Порядок проверки полей сущности: fromnumber, fromdomain, tonumber. * любое значение, применяемого без регулярного выражения (для этого необходимо задать `/any`). Режим полезен исключительно при организации прямых сопоставлений со значениями других полей без дополнительных фильтров. Применение табличного модификатора допускается в комбинации с другими управляющими командами посимвольного режима. Допускается кратное указание полей в одном модификаторе, повторение, указание несуществующих полей. Например, `{tab:a:3}XXXXX{tab:b}` - позволяет выделить в номере 3-символьный код города и сопоставить с полем `a` в таблице, и одновременно выделить хвост начиная с 9 символа и сопоставить с полем `b` таблицы.
`Regex`	К исходному значению применяется шаблон Pattern. Структура значения regex-шаблона: `/reg/Pattern1`. Например,- значение: `"302"` - маска: `"/reg/0"` - результат: `true`. значение: `"302"` маска: `"/reg/^0$"` результат: `false`. значение: `"302"` маска: `"/reg/^302$"` результат: `true`. значение: `"302"` маска: `"/reg/^(301\|302\|305)$"` результат: `true`. При формировании шаблонов Pattern могут применяться все стандартные правила регулярных выражений.

Режимы работы модификаторов

Table 4. Режимы работы модификаторов
Режим	Описание
`Посимвольный`	Исходное значение посимвольно с накоплением проходит через указанный модификатор. Допускается применение следующих спец-символов и сочетаний: `X` – захватить текущий символ; `/` в сочетании c `X` – исключить текущий символ из результата, например `/XXX/` исключает 3 текущих символа; `` – захватить все оставшиеся символы; `[` в сочетании с `]` – включить в результат служебный символ, расположенный между скобками, например `[X]`; `{C}` – включить в результат код учетной записи провайдера SIP-телефонии; `{c}` – включить в результат lowercase код учетной записи провайдера SIP-телефонии; `{U}` – включить в результат username модифицируемой стороны; `{u}` – включить в результат lowercase username модифицируемой стороны; `{D}` – включить в результат displayname модифицируемой стороны; `{d}` – включить в результат lowercase displayname модифицируемой стороны; `{E}` и `{e}` – включить в результат пустое значение; любой другой символ захватывается в результат в соотстствующую ему позицию. Например,- значение: `"123456"` - From displayname: `"Abonent"` - Code: `"R1"` - модификатор: `"/X/XX5[]67{E}8T{d}{C}"` - результат: `"235678456123456abonentR1"`.
`Таблица`	Может применяться подстрока `{tab:…}`. С помощью нее в модифицируемое значение можно подставить подстроку из указанного поля таблицы (`opts.tab`). В качестве источника выступает первая оставшаяся после фильтрации строка в таблице. Например, `{tab:ссс}` - подстановка в соответствующую позицию итогового результата значения из поля `ccc` первой оставшейся строки в таблице. Если в первой строке/объекте указанное поле отсутствует, то подставляется пустое значение. Таблица служет связке нескольких полей фильтров и модификаторов. На основании последовательной проверки фильтров в таблице остается меньшее количество строк с учетом обнаруженных совпадений. Первая из оставшихся строк служит для применения в модификаторах. При условии, что в таблице не осталось строк - правило отклоняется на этапе проверки фильтров. Применение табличного модификатора допускается в комбинации с другими управляющими командами посимвольного режима. Допускается кратное указание полей в одном модификаторе, повторения, указания несуществующих полей.
`Regex`	К исходному значению применяется шаблон Pattern с опциями Opts, и обнаруженный(-ые) блок(-и) заменяется(-ются) на шаблон Replace. Результат может снова быть подан на следующую операцию Regex-модификации, и так далее конечное число раз. Общая структура значения regex-модификатора: `/reg/Pattern1/Replace1/Opts1 /reg/Pattern2/Replace2/Opts2 …`. Опции могут быть опущены, либо содержать любую комбинацию из символов: `i` – case-insensitive `g` – global. Например,- значение: `"qwerty,qwerty"` - модификатор: `"/reg/t/E/g /reg/qwer/a/"` - результат: `"aEy,qwerEy"`. При формировании шаблонов Pattern и Replace могут применяться все стандартные правила регулярных выражений, включая группы захвата, поиск назад, подстановку именованных групп и т.д.
`"priority=…"`	Режим реализован в задаче #192. Для модификаторов `To:` username допускается указание в качестве модификатора значения `priority=X`, где `X` - любое неотрицательное число. Тем самым процесс модификации CallerId и CalledId становится следующим: (1) Ищется правило R1 по начальным From и To. (2) Из него применяется модификатор к From. (3) Если модификатор To равен 'priority=X', где X - любое неотрицательное число, то (3.1.1) ищется новое правило R2 по новому From и начальному To, с приоритетом, начиная с указанного X. (3.1.2) модификатор To из правила R2 применяется к начальному To. (3.2) иначе применяется модификатор To правила R1 к начальному To. Алгоритм построении компактного набора правил преобразования CallerId и CalledId может быть следующим: (1) Действовать как обычно. (2) Если возникает потребность сократить MN правил до M+N, то (2.1) Выделить M правил модификации From с высокими приоритетами, в них установить в значения модификаторов To в значения 'priority=X'. (2.2) Создать еще N правил, где фильтры From соответствуют результату модификации From, либо ``, и задать модификаторы To. (2.3) В случае, когда для определенных значений не требуется модификация From, то либо сразу модифицировать To, либо указывать priority=X, где X больше приоритета текущего правила.

См. также

API

/rest/v1/uc/provider_callerids