Провайдер SIP-телефонии (provider)

Описание

Учетная запись провайдера SIP-телефонии, посредством которой система «Era» присоединяется к внешним SIP-сетям.
Это может быть внешняя телефонная сеть, подключаемая через провайдеров, или корпоративные АТС, находящиеся выше или на одном уровне иерархии в номерном плане, что и система «Era».
Роль ESG производит регистрацию и поддержание канала связи с внешним оборудованием, указанным в учетной записи провайдера. Любой вызов, приводящий к звонку наружу, всегда происходит через нее. Любой вызов, поступающий снаружи в систему, может быть принят, авторизован и обслужен только той ролью ESG, которая определена в учетной записи провайдера.

Определение того, какой учетной записи соответствует поступивший снаружи вызов, определяется по совокупности условий:
- учетная запись с регистрацией в заголовке "To:" или "Contact:" SIP-запроса INVITE содержит "username@domain", где "username" соответствует значению поля "username" учетной записи, а "domain" соответствует одному из адресов учетной записи;
- учетная запись без регистрации в заголовке "Contact:" SIP-запроса INVITE содержит "username@domain", где "username" соответствует значению поля "username" учетной записи, а "domain" соответствует одному из адресов учетной записи;
- учетная запись без регистрации в заголовке "Contact:" SIP-запроса INVITE содержит "username@domain", где "domain" соответствует одному из адресов учетной записи, а значение поля "username" учетной записи пусто.

В любом случае адрес отправителя, откуда запрос поступил на SIP-порт роли ESG, должен быть известен из описания учетной записи (совокупность полей "domain", "proxyaddr"/"alternative_proxies", "extaddrs").

Подробнее о работе с провайдерами телефонии.

Ограничения

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

  • При изменении поля лицензии в БД после перезагрузки домена объект не будет загружен, действует проверка по hash.

  • Лицензируется количественным параметром: расходуется лицензия на допустимое одновременное количество активных транков.

Поля

Структура сущности
{
  "id": uuid,
  "code": str,
  "enabled": intbool,
  "username": str,
  "login": str,
  "pwd": str,
  "domain": str,
  "proxyaddr": str,
  "proxyport": int,
  "transport": str,
  "alternative_proxies": str,
  "extaddrs": array<str>,
  "serveridx": int,
  "reg": bool,
  "expires": int,
  "pingmode": str,
  "pingsrv": str,
  "pingtimeout": int,
  "localdomain": str,
  "media": intbool,
  "reinvite": intbool,
  "translit": intbool,
  "lic": object,
  "trunksout": int,
  "opts": {
    "title": str,
    "comment": str,
    "agat_port_id": uuid,
    "agat_chassis_id": uuid,
    "agat_lm_id": uuid
  },
  "ext": {
    "ct": date,
    "lwt": date
  }
}

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

Table 1. Поля
Спецификация Описание

Поле: id
Режим: inout
Тип: uuid
По умолчанию: generated

Идентификатор. Может быть задан при создании, иначе генерируется системой.

Поле: code
Режим: in
Тип: str
По умолчанию: required

Код учетной записи.
Используется для указания в правилах маршрутизации.

Поле: enabled
Режим: in
Тип: intbool
По умолчанию: 1

Выключатель учетной записи.
В случае выключения роль esg не обладает данными об учетной записи и не обрабатывает звонки по ней.

Поле: username
Режим: in
Тип: str
По умолчанию: required

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

Поле: login
Режим: in
Тип: str
По умолчанию: empty

Логин для авторизации.

Если отсутствует, то авторизация производится на основе username.
При этом в качестве username во время INVITE и re-INVITE подставляется username из From URI текущего запроса, что может повлечь неожиданный отказ.

Чтобы не получить отказ в ответ на запросы INVITE и re-INVITE, можно воспользоваться одним из методов:

  • Установить в качестве 'login' значения, совпадающего с 'username' учетной записи. Это обеспечит корректную авторизацию по инициативе провайдера во время INVITE.

  • Использовать режим 'reinvite'=0 и оппозитный ему 'media'=1 с добавлением в конфигурацию экземпляров bgmg. Это исключит отправку reinvite с измененным значением From URI.

  • Настроить правило нормализации для этой учетной записи провайдера, где 'dir' = 'inner', а в 'modfromnumber' значение идентичное 'username' учетной записи. Это обеспечит подстановку всегда одинакового username в заголовок From запросов INVITE в сторону провайдера, что обеспечит корректную авторизацию по инициативе провайдера во время INVITE.

Поле: pwd
Режим: in
Тип: str
По умолчанию: required

Пароль для авторизации.
Обязательное поле если учетная запись с регистрацией.
Используется также в учетных записях без регистрации в случае, если внешнее оборудование требует авторизации путем отправки ответов 401 или 407.

Поле: domain
Режим: in
Тип: str
По умолчанию: required

SIP сервер. Доменное имя, подставляемое в заголовок To при отправке запросов из системы к внешнему оборудованию.
Также используется для идентификации учетной записи при получении запросов извне.

Поле: proxyaddr
Режим: in
Тип: str
По умолчанию: empty

Адрес Outbound Proxy-сервера, куда фактически отправляются запросы из системы к внешнему оборудованию.
Если не указан, то адресом выступает результат определения адреса по значению поля domain, в том числе у DNS-серверов.
Также используется для идентификации учетной записи при получении запросов извне.

Поле: proxyport
Режим: in
Тип: int
По умолчанию: 0

Порт Outbound Proxy-сервера, куда фактически отправляются запросы из системы к внешнему оборудованию

Поле: transport
Режим: in
Тип: str
По умолчанию: "udp"

Транспортный протокол для основного прокси. Допустимые значения "udp", "tcp", "tls".

Поле: certificate_pem
Режим: in
Тип: str
По умолчанию: empty

Сертификат для подключения к провайдеру по TLS.
Содержимое PEM-файла с доверенной цепочкой, либо макро-путь к pem-файлу (например, ':SYNC_DOMAIN_DATA/files/certificates/provider1.pem').
Если значение не указано, то до версии 1.9.0 проверки цепочки сертификатов на стороне клиента не производится, а начиная с версии 1.9.0 применяются доверенные сертификаты из операционной системы.

Поле: alternative_proxies
Режим: in
Тип: str
По умолчанию: empty

Список альтернативных Proxy-серверов.
Формат: Proto:IP-address:Port через запятую, где Proto – tcp | udp | tls, IP-address – IPV4, Port – натуральное число до 65535.
Например tcp:192.168.220.135:5060, udp:187.12.124.55:33985

Поле: extaddrs
Режим: in
Тип: str
По умолчанию: empty

Дополнительные возможные адреса провайдера или маски адресов для идентификации учетной записи при получении запросов извне, через запятую.
В качестве масок могут использоваться значения в форматах /reg/REGEX, а также целевые значения со спец-символами ?, * для указания соответственно произвольной цифры и жадной комбинации от одной до трех цифр.
Например, /reg/^*.*.*.*$, 144.76.?0?.*
Применение масок влечет дополнительные затраты вычислительных мощностей.

Поле: serveridxs
Режим: in
Тип: array(int)
По умолчанию: empty

Список экземпляров роли esg в порядке убывания приоритета, которые ответственны за работу с учетной записью. Роли указываются с помощью значений RoleId из конфигурации ролей.
После того, как приоритетный сервер становится недоступен, то в течение 30 секунд работу с учетной записью начинает следующий по списку сервер. При восстановлении более приоритетного сервера возможна ситуация, когда учетная запись обслуживается (зарегистрирована) обоими серверами.
Если в списке находится лишь одно значение, то именно этот сервер отвечает за учетную запись, и при его недоступности учетная запись неактивна.
Если список пуст (по умолчанию), то работа с учетной записью определяется по правилам, установленным в настройках домена (settings.ext.default_provider_serveridxs), ожидается что там находится число RoleId или их список.
При отсутствии указанного ключа работу с учетной записью начинает сервер с самым низким значением RoleId на сайтах, где обслуживается домен.

Поле: reg
Режим: in
Тип: bool
По умолчанию: true

Режим работы с регистрацией (true) или без регистрации (false)

Поле: expires
Режим: in
Тип: int
По умолчанию: 3600

Период перерегистрации в секундах

Поле: pingmode
Режим: in
Тип: str
По умолчанию: "none"

Режим проверки доступности

Поле: pingsrv
Режим: in
Тип: str
По умолчанию: empty

Адрес внешнего оборудования для проверки доступности.
Если не указан, то проверка доступности происходит по тому же адресу, который выбран для отправки INVITE-запросов.

Поле: pingtimeout
Режим: in
Тип: int
По умолчанию: 10

Период проверки доступности, в секундах

Поле: localdomain
Режим: in
Тип: str
По умолчанию: empty

Значение поля domain в заголовке From при отправке запросов из системы к внешнему оборудованию.
Применяется только для учетных записей без регистрации. По умолчанию пустое значение, при котором используется домен идентичный To.

Поле: media
Режим: in
Тип: intbool
По умолчанию: 0

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

Поле: reinvite
Режим: in
Тип: int
По умолчанию: 1

Переключатель режима прозрачного проброса re-INVITE наружу. Может быть выключен только в случае, если включен режим media.
Возможные варианты:

  • 0 (none) - Проброс реинвайта выключен. При изменении медиа-сессии обработка производится на экземпляре bgmg, обслуживающем этот диалог под управлением esg. Режим может быть активирован только в случае, если включена опция media.

  • 1 (keep_from) - Проброс реинвайта в upstream включен, в каждом отправляемом запросе re-INVITE значение заголовка From сохраняется из первичной транзакции INVITE.

  • 2 (update_from) - Проброс реинвайта в upstream включен, в каждом отправляемом запросе re-INVITE значение заголовка From определяется заново на основании абонента в новом плече внутренней стороны.

Поле: refer_mode
Режим: in
Тип: str
По умолчанию: "terminate"

Переключатель режима обработки REFER на пограничном шлюзе, обслуживающем учетную запись провайдера.
Возможные варианты:

  • terminate - Запросы REFER приводят к инициации вызова микросервисом ESG в сторону того же номерного плана, откуда поступил запрос.

  • forward - Запросы REFER с соответствующей модификацией значений заголовков Refer-To, Referred-By перенаправляются дальше, в оппозитное плечо и другой номерной план.

Режим 'forward' применяется для тестовых кейсов эмуляции системой абонентов.
Он может быть включен только в случае, если режим reinvite не установлен в значение 'none'.
Если производится Refer с подменой, то режим 'forward' применяется только если подменяемый вызов также проходит через этот экземпляр esg и ту же учетную запись провайдера. В противном случае обработка этого конкретного запроса Refer происходит в режиме 'terminate'.

Поле: translit
Режим: in
Тип: intbool
По умолчанию: 0

Выключатель транслитерации отображаемого имени при отправке запросов и ответов наружу

Поле: lic
Режим: in
Тип: object
По умолчанию: empty

Набор лицензий переданных из домена. Среди параметров ожидается максимальное количество одновременных звонков с использованием учетной записи, например {"siptrunks":5}.

Поле: trunksout
Режим: in
Тип: int
По умолчанию: -1

Максимальное количество транков, используемых для исходящих звонков.
-1 – не ограничено, то есть ограничено лишь лицензией.
В любом другом случае исходящий звонок из системы к внешнему оборудованию отклоняется правилом маршрутизации, если количество активных транков по этой учетной записи не меньше указанного в поле числа.

Поле: opts
Режим: in
Тип: object
Составное поле

Поле: opts.title
Режим: in
Тип: str
По умолчанию: empty

Произвольный заголовок

Поле: opts.comment
Режим: in
Тип: str
По умолчанию: empty

Произвольный комментарий

Поле: opts.extusernames
Режим: in
Тип: str
По умолчанию: empty

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

Поле: opts.deservice_response
Режим: in
Тип: bool
По умолчанию: true

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

Если учетная запись с регистрацией, то экземпляры микросервиса esg, переключенные в режим мягкого вывода из эксплуатации, прекращают регистрацию.
В соответствии с установленным перечнем допущенных к обслуживанию экземпляров esg (параметр serveridxs) регистрация передается активному экземпляру (или нескольким, параметр 'instance_count').
Система стремится поддерживать указанное количество регистраций, преимущественно с экземпляров esg, исполняемых на активных серверах.
Если ни одного активного экземпляра нет среди разрешенных для обслуживания, то регистрации будут поддерживаться на серверах выводимых из эксплуатации.

Если учетная запись без регистрации, то экземпляры микросервиса esg, переключенные в режим мягкого вывода из эксплуатации, отклоняют первичные вызовы INVITE от провайдера с кодом ответа 'deservice_sipcode'.
В соответствии с установленным перечнем допущенных к обслуживанию экземпляров esg (параметр serveridxs), обслуживание по цепочке передается активному экземпляру (или нескольким, параметр 'instance_count').
Если ни одного активного экземпляра нет среди разрешенных для обслуживания, то режим мягкого вывода из обслуживания для этой учетной записи не применяется вплоть до появления хотя бы одного актвного микросервиса.

Поле: opts.deservice_sipcode
Режим: in
Тип: int
По умолчанию: 503

Код ответа, отправляемый микросервисом esg на первичные запросы INVITE от провайдера.
Отправляется, если сервер, исполняющий экземпляр esg, находится в режиме мягкого вывода из эксплуатации, а учетная запись провайдера без регистрации и с включенным параметром 'deservice_response'.
Возможные значения: 400-699.

Поле: opts.instance_count
Режим: in
Тип: int
По умолчанию: 1

Количество экземпляров микросервиса ESG, обслуживающих одновременно учетную запись.
Если при этом часть серверов находится в режиме мягкого вывода из эксплуатации, то поведение и распределение обслуживающих экземпляров соовтетствует описанию параметра 'deservice_response'.

Поле: opts.use_diversion
Режим: in
Тип: bool
По умолчанию: false

Выключатель применения Diversion при вызовах из upstream, переадресованных или смаршрутизированных обратно в upstream (RFC-5806).

Если вызов поступил не из upstream, или учетная запись имеет выключенный режим Diversion, то параметры INVITE-запроса формируются на общих основаниях от имени учетной записи системы в соответствии с правилами нормализации.

Когда вызов поступает от абонента A из upstream в рамках учетной записи c включенным режимом Diversion на номер B, то каждый запрос INVITE, отправляемый в upstream на номер C через любую учетную запись с включенным режимом Diversion, размещает в качестве From URI абонента A, и дополнительно размещает заголовок Diversion с URI номера B.

Поле: opts.use_billing
Режим: in
Тип: bool
По умолчанию: false

Выключатель применения биллинга к вызовам, производимым в любую из сторон через текущую учетную запись.
Если в диалоге в обоих плечах находятся внешние абоненты, то биллинг в соответствии с настройками учетных записей применяется к каждому плечу.
Параметры подключения биллинга размещаются в настройках мастер-домена (billing_options).

Поле: ext
Режим: inout
Тип: object
Составное поле

Позволяет расширять состав произвольными ключами и значениями

Поле: ext.ct
Режим: out
Тип: date
По умолчанию: generated

Время создания объекта

Поле: ext.lwt
Режим: out
Тип: date
По умолчанию: generated

Время последней модификации объекта

Режимы проверки доступности

Table 2. Режимы проверки доступности
Значение Описание

"none"

Отключить проверку доступности

"rn"

Отправлять пустой запрос CR LF, ожидая в ответ CR LF CR LF

"options"

Отправлять SIP-запрос OPTIONS, ожидая в ответ SIP-ответ 200 OK

"register"

Отправлять внеочередной SIP-запрос REGISTER, ожидая в ответ SIP-ответ 200 OK

"stun"

Отправлять STUN-запрос

См. также

API

  • Персонализация
  • Увеличить шрифт
  • Уменьшить шрифт