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

Работа с API сервиса ecss-clerk (секретарь):


В приложении реализовано RestAPI.

Документацию по работе с API можно найти по адресу: http://<IP_HOST>:<CLERK_PORT>/swagger/index.html, где:

  • <IP_HOST> — адрес хоста;
  • <CLERK_PORT> — порт сервиса clerk (по умолчанию: 8000).

Получение токена доступа

Для работы с api необходимо создать токен доступа на сервисе keycloak и добавить его в заголовок запросов access_token. 
Для создания токена доступа создайте следующий скрипт, где вместо 'localhost:8085' укажите IP-адрес хоста с приложением и порт сервиса keycloak. Если меняли пароль администратора web-интерфейса admin, введите его вместо пароля по умолчанию — 'password':

$ sudo nano get_access_token.sh

#!/bin/bash

curl -d 'client_id=clerk-client' -d client_secret='Q4Cbf6NzPni9n4wprlgGuUPOyKIamWZ0' \
    -d 'username=admin' -d 'password=password' -d 'grant_type=password' \
    'http://localhost:8085/realms/clerk/protocol/openid-connect/token' | \
    jq

Таблица aliases

Описание: таблица предназначена для добавления сокращений или жесткой привязки совсем других слов к именам (firstname), фамилиям (secondname), отчествам (thirdname).
Связка alias => full_names должна быть уникальной, при попытке добавления дублирующейся записи будет возвращена ошибка.

Пример: на предприятии плохо распознается связка имени и фамилии «игорь николаев», результатом распознавания часто является «игорь николай». Для решения этой проблемы нужно добавить привязку к фамилии в таблицу вида «николай» -> «николаев».

Получить все псевдонимы (alias):

Path: /aliases
Request-type: GET

Пример:

Запрос:
curl -X 'GET' \
  'http://<IP_HOST>:<CLERK_PORT>/aliases' \
  -H 'accept: application/json' \
  -H 'access_token: <ACCESS_TOKEN>'

Ответ:
{
"Aliases": [
{
"alias": "ануся",
"full_names": {
"анна": {}
},
"tag": "firstname"
},
{
"alias": "вова",
"full_names": {
"владимир": {}
},
"tag": "firstname"
},
...
  • <IP_HOST> — адрес хоста;
  • <CLERK_PORT> — порт сервиса clerk (по умолчанию: 8000);
  • <ACCESS_TOKEN> — токен доступа.

Добавление псевдонима:

Path: /aliases
Request-type: POST
Content-type: application/json
Требуемые поля в json: alias, full_names, tag

Пример:

Запрос:
curl -X 'POST' \
  'http://<IP_HOST>:<CLERK_PORT>/aliases' \
  -H 'accept: application/json' \
  -H 'access_token: <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "aliases": [
    {
      "alias": "игорян",
      "full_names": {
        "игорь": {}
      },
      "tag": "firstname"
    }
  ]

Ответ:
{
  "Status": "ok"
}
  • <IP_HOST> — адрес хоста;
  • <CLERK_PORT> — порт сервиса clerk (по умолчанию: 8000);
  • <ACCESS_TOKEN> — токен доступа.

Удаление псевдонима:

Path: /aliases
Request-type: DELETE
Content-type: application/json
Требуемые поля в json: alias

Пример:

Запрос:
curl -X 'DELETE' \
  'http://<IP_HOST>:<CLERK_PORT>/aliases' \
  -H 'accept: application/json' \
  -H 'access_token: <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "alias": "игорян"
}'

Ответ:
{
  "Status": "ok"
}
  • <IP_HOST> — адрес хоста;
  • <CLERK_PORT> — порт сервиса clerk (по умолчанию: 8000);
  • <ACCESS_TOKEN> — токен доступа.

Таблица history

Описание: таблица предназначена для просмотра/удаления истории вызовов, а также просмотра всей статистики.

Получить историю вызовов:

Path: /history
Request-type: GET

Пример:

Запрос:
curl -X 'GET' \
  'http://<IP_HOST>:<CLERK_PORT>/history' \
  -H 'accept: application/json' \
  -H 'access_token: <ACCESS_TOKEN>'

Ответ:
{
  "History": [
    {
      "CallRef": "1460562852",
      "ReqSource": "ivr",
      "DetectionAttr": "fio",
      "Source": "100",
      "Number": "102",
      "Files": {
        "2023-10-05_08-01-33-21225_asr_100-999.wav": "терентьева полина"
      },
      "Status": "good",
      "Date": "2023-10-05T08:01:35.613Z",
      "ClerkNum": "999",
      "Additional": {
        "sample_rate": 48000,
        "source": "msr"
      }
    }
  ]
}
  • <IP_HOST> — адрес хоста;
  • <CLERK_PORT> — порт сервиса clerk (по умолчанию: 8000);
  • <ACCESS_TOKEN> — токен доступа.

Удалить вызов из истории:

Path: /history
Request-type: DELETE
Content-type: application/json
Требуемые поля в json: callRef (id вызова)

Пример:

Запрос:
curl -X 'DELETE' \
  'http://<IP_HOST>:<CLERK_PORT>/history' \
  -H 'accept: application/json' \
  -H 'access_token: <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "callRef": "1053020459"
}'

Ответ:
{
  "Status": "ok"
}
  • <IP_HOST> — адрес хоста;
  • <CLERK_PORT> — порт сервиса clerk (по умолчанию: 8000);
  • <ACCESS_TOKEN> — токен доступа.

Получить историю определенного вызова:

Path: /history/{call_ref} (id вызова)
Request-type: GET

Пример:

Запрос:
curl -X 'GET' \
  'http://<IP_HOST>:<CLERK_PORT>/history/1053020459' \
  -H 'accept: application/json' \
  -H 'access_token: <ACCESS_TOKEN>'

Ответ:
{
"CallRef": "1053020459",
"ReqSource": "ivr",
"DetectionAttr": "fio",
"Source": "100",
"Number": "110",
"Files": {
"2023-10-06_03-37-31-338988_asr_100-999.wav": "степанова мария"
},
"Status": "good",
"Date": "2023-10-06T03:37:32.975Z",
"ClerkNum": "999",
"Additional": {
"sample_rate": 48000,
"source": "msr"
}
}
  • <IP_HOST> — адрес хоста;
  • <CLERK_PORT> — порт сервиса clerk (по умолчанию: 8000);
  • <ACCESS_TOKEN> — токен доступа.

Получить статистику вызовов:

Path: /stats
Request-type: GET

Пример:

Запрос:
curl -X 'GET' \
  'http://<IP_HOST>:<CLERK_PORT>/stats' \
  -H 'accept: application/json' \
  -H 'access_token: <ACCESS_TOKEN>'

Ответ:
{
"Stats": [
{
"Source": "ivr",
"RequestCount": 2,
"Correct": 2,
"Failed": 0
}
]
}
  • <IP_HOST> — адрес хоста;
  • <CLERK_PORT> — порт сервиса clerk (по умолчанию: 8000);
  • <ACCESS_TOKEN> — токен доступа.

Таблица phonebook

Описание: таблица предназначена для получения информации по адресной книге.

Получить телефонную книгу:

Path: /pb
Request-type: GET

Пример:

Запрос:
curl -X 'GET' \
  'http://<IP_HOST>:<CLERK_PORT>/pb' \
  -H 'accept: application/json' \
  -H 'access_token: <ACCESS_TOKEN>'

Ответ:
{
  "Contacts": [
    {
      "UID": "02598495150212722288423330",
      "FirstName": "алиса",
      "SecondName": "вешнякова",
      "ThirdName": "",
      "Department": "",
      "Group": "",
      "SubGroup": "",
      "Number": "100",
      "Hash": 1065922175
    },
    {
      "UID": "004662883495622783462351",
      "FirstName": "александр",
      "SecondName": "акимов",
      "ThirdName": "",
      "Department": "",
      "Group": "",
      "SubGroup": "",
      "Number": "101",
      "Hash": 1973066537
    },
    {
      "UID": "76011072078104322",
      "FirstName": "полина",
      "SecondName": "терентьева",
      "ThirdName": "",
      "Department": "",
      "Group": "",
      "SubGroup": "",
      "Number": "102",
      "Hash": 3842283868
    }
...
  • <IP_HOST> — адрес хоста;
  • <CLERK_PORT> — порт сервиса clerk (по умолчанию: 8000);
  • <ACCESS_TOKEN> — токен доступа.

Получить телефонную книгу адаптируемую для приложения:

Path: /pb_compile
Request-type: GET

Пример:

Запрос:
curl -X 'GET' \
  'http://<IP_HOST>:<CLERK_PORT>/pb_compile' \
  -H 'accept: application/json'

Ответ:
{
  "Contacts": [
    {
      "UID": "02598495150212722288423330",
      "SecondName": "вешнякова",
      "ThirdName": "",
      "Department": "",
      "Group": "",
      "SubGroup": "",
      "Number": "100",
      "Hash": 1065922175,
      "FirstName": [
        "алиса",
        "аля"
      ]
    },
  {
      "UID": "004662883495622783462351",
      "SecondName": "акимов",
      "ThirdName": "",
      "Department": "",
      "Group": "",
      "SubGroup": "",
      "Number": "101",
      "Hash": 1973066537,
      "FirstName": [
        "александр",
        "саша",
        "санюра",
        "санюха",
        "алексаха",
        "сашура",
        "сашуля",
        "сашуня",
        "шура",
        "санюша",
        "сашута",
        "сашуха",
        "шуруня",
        "александрушка",
        "алексаша",
        "лексаша",
        "алексаня",
        "саня"
      ]
    },
  {
      "UID": "76011072078104322",
      "SecondName": "терентьева",
      "ThirdName": "",
      "Department": "",
      "Group": "",
      "SubGroup": "",
      "Number": "102",
      "Hash": 3842283868,
      "FirstName": [
        "полина",
        "аполлинария",
        "полинка",
        "полюся",
        "поляша",
        "поля",
        "лина",
        "полюша",
        "полюха",
        "полюня",
        "пелагея"
      ]
    }
...
  • <IP_HOST> — адрес хоста;
  • <CLERK_PORT> — порт сервиса clerk (по умолчанию: 8000).

Таблица search

Описание: таблица предназначена для проверки получения ответа от приложения по переданной строке.

Запрос на получение результата по переданной строке

Path: /search
Request-type: POST
Content-type: application/json
X-call-ref: (выдуманный id вызова)

Требуемые поля в json: text

Пример:

Запрос:
curl -X 'POST' \
  'http://<IP_HOST>:<CLERK_PORT>/search' \
  -H 'accept: application/json' \
  -H 'access_token: <ACCESS_TOKEN>' \
  -H 'x-call-ref: 100' \
  -H 'Content-Type: application/json' \
  -d '{
  "text": "терентьева полина"
}'

Ответ:
{
  "Num": "102",
  "Answer": ""
}
  • <IP_HOST> — адрес хоста;
  • <CLERK_PORT> — порт сервиса clerk (по умолчанию: 8000);
  • <ACCESS_TOKEN> — токен доступа. 

Таблица words

Описание: таблица предназначена для получения слов из словаря, добавления/удаления слов из словаря.

Получение слов из словаря

Path: /words
Request-type: GET

Пример:

Запрос:
curl -X 'GET' \
  'http://<IP_HOST>:<CLERK_PORT>/words' \
  -H 'accept: application/json' \
  -H 'access_token: <ACCESS_TOKEN>'

Ответ:
{
  "Words": [
    {
      "Word": "виташа",
      "Tag": "firstname"
    },
    {
      "Word": "авдей",
      "Tag": "firstname"
    },
    {
      "Word": "гермоген",
      "Tag": "firstname"
    },
    {
      "Word": "эльвира",
      "Tag": "firstname"
    },
    {
      "Word": "беня",
      "Tag": "firstname"
    },
    {
      "Word": "маринка",
      "Tag": "firstname"
    }
...
  • <IP_HOST> — адрес хоста;
  • <CLERK_PORT> — порт сервиса clerk (по умолчанию: 8000);
  • <ACCESS_TOKEN> — токен доступа.

Добавление слов в словарь

Path: /words
Request-type: POST
Content-type: application/json
Требуемые поля в json: words

Пример:

Запрос:
curl -X 'POST' \
  'http://<IP_HOST>:<CLERK_PORT>/words' \
  -H 'accept: application/json' \
  -H 'access_token: <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "words": [
    {
      "tag": "firstname",
      "word": "святослав"
    }
  ]
}'

Ответ:
{
  "Status": "ok"
}
  • <IP_HOST> — адрес хоста;
  • <CLERK_PORT> — порт сервиса clerk (по умолчанию: 8000);
  • <ACCESS_TOKEN> — токен доступа.

Удаление слова из словаря

Path: /words
Request-type: DELETE
Content-type: application/json
Требуемые поля в json: word

Пример:

Запрос:
curl -X 'DELETE' \
  'http://<IP_HOST>:<CLERK_PORT>/words' \
  -H 'accept: application/json' \
  -H 'access_token: <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "word": "святослав"
}'

Ответ:
{
  "Status": "ok"
}
  • <IP_HOST> — адрес хоста;
  • <CLERK_PORT> — порт сервиса clerk (по умолчанию: 8000);
  • <ACCESS_TOKEN> — токен доступа.

Работа с API сервиса ecss-tts (синтез речи):


В приложении реализовано RestAPI.

Документацию по работе с API можно найти по адресу: http://<IP_HOST>:<TTS_PORT>/docs где:

  • <IP_HOST> — адрес хоста;
  • <TTS_PORT> — порт сервиса clerk (по умолчанию: 7890).

Таблица default

Описание: основная таблица для работы с синтезом речи.

Получить параметры речи

Path: /
Request-type: GET
Требуемые поля в json: text и voice

Пример:

Запрос:
curl -X 'GET' \
  'http://<IP_HOST>:<TTS_PORT>/?text=<TEXT>&voice=<VOICE>'' \
  -H 'accept: audio/x-pcm'

Ответ:
 данные со следующими параметрами audio/x-pcm;bit=16;rate=22050
  • <IP_HOST> — адрес хоста;
  • <TTS_PORT> — порт сервиса clerk (по умолчанию: 7890);
  • <TEXT> — текст, который нужно озвучить, в кодировке UTF-8, для управления произношением следует использовать специальную разметку;
  • <VOICE> — голос на выбор, доступны: "irina", "natasha", "elena", "dmitrii", "pavel".

Элементы TTS-разметки

СпецсимволОписаниеПрименение
+корректировка ударенияСпецсимвол ставится перед ударным гласным звуком
  • Нет меток