По вашему запросу ничего не найдено :(
Убедитесь, что запрос написан правильно, или посмотрите другие
наши статьи:
Все, что вам нужно знать о Linux, можно найти в man. Это интерфейс, используемый для просмотра справочных руководств системы, отсюда и название: man - сокращение от manual. Например, можно выполнить поиск команды для выполнения задачи, даже если неизвестно, как она называется. Но как найти само руководство? В этой статье расскажем о некоторых скрытых возможностях этой команды.
Встроенное руководство Linux
Существует старая шутка: единственная команда, которую нужно знать в Linux это man – точка входа в руководство пользователя. Несмотря на то, что тут есть доля правды, но даже сама команда man может ввести в тупик вначале. Вернее, поиск информации с помощью этой команды.
Наверное, у всех был случай, когда знали, что вы хотите сделать, но не знали какая команда поможет выполнить поставленную задачу. Это похоже на то, как искать слово в словаре при том, не зная самого слова.
Итак, как же можно найти, то что нужно? С man можно легко обойти эту сложность.
Цифры - еще одна сложность перед новичками. Что они означают? Вы документации или в просторах Интернета часто можно увидеть такие ссылки, man (2) или man (5). Также можно встретить ссылки на команды, за которыми следуют цифры, такие как mount (2) и mount (8). Конечно, не может быть больше одной команды mount, верно? Как мы увидим, цифры важны и их понять относительно просто.
Проще говоря, вести поиск по man достаточно легко если один раз понять, как это работает. На самом деле, есть несколько способов поиска и навигации в man.
Как перейти к руководству
Чтобы запустить руководство по какой либо-команде достаточно в командной строке набрать команду man, а затем через пробел название команды, по которой нужно руководство. После этого система запустить руководство по команде – конечно, если найдет. Давайте посмотрим, что покажет команда man по man:
man man
Ниже показано руководство по команде man:
Как видно, это первая страница руководства man (1). Чтобы просмотреть другие страница выполните одно из следующих действий:
Чтобы прокрутить по одной строчке: используйте колесо мыши, стрелки вверх или вниз и клавишу Enter.
Для перехода на следующую страницу: Нажмите клавишу пробел, или же кнопки PgUp PgDown.
Для перехода в начало и конец руководства: Клавиши Home и End
Если нажать H (заглавная h), то можно перейти в раздел помощи, где можно найти альтернативные комбинации, которыми можно пользоваться для навигации. Чтобы выйти из руководства нажмите Q.
Структура руководства
В начале страницы можно увидеть Название (Name) и Описание (Synopsis). Есть определённые правила оформления страницы руководства. Есть руководства по командам, программам, функциям и т.д. Не во всех руководствах есть эти заголовки, так как некоторые из них применимы только к конкретным командам.
Ниже приведён список заголовков, которые можно встретить в руководстве.
Название (Name): название команды, по которой просматривается руководство
Синопсис (Synopsis): Краткое описание команды и синтаксиса
Конфигурация (Configuration): Детали настройки для устройства
Описание (Description): Описание основного назначения программы
Опции (Ключи): опции которые принимает команда
Выходной статус (Exit Status): Возможные значения, возвращаемые командой при завершении работы
Возвращаемое значение (Return Value): Если руководство запущено по какой-то библиотеке, то это указывает на значение, которое вернет библиотека функции, которая вызвала ее.
Ошибки (Errors): Список всех значение, которые может принимать errno в случае ошибки выполнения команды
Окружение (Environment): Список переменных окружения, которые относятся к команде или программе
Файлы (Files): Список файлов, которые использует команда или программа, например, конфигурационный файл
Атрибуты (Attributes): Список различных атрибутов команды
Версии (Versions): Список изменений в ядре Linux или библиотеке, которую использует команда
Соответствие (Conforming to): Описание любых стандартов, которым может соответствовать команда, например, POSIX.
Заметки (Notes): Дополнительные заметки
Баги (Bugs): Известные ошибки
Примеры (Examples): Один или несколько примеров использования команды
Авторы (Authors): Люди, которые разработали и поддерживают команду
Просмотрите также (See Also): Рекомендуемые материалы по команде
Разделы руководства
Прокрутив ниже на несколько страниц увидите список разделов в данном руководстве:
Это следующие разделы:
Основные команды (General commands): Команды, которые используются в командной строке
Системные вызовы (System calls): Функции ядра, которые может вызвать программа
Функции библиотек (Library functions): общий набор функций и возможностей, используемых программами
Форматы файлов и соглашения (File formats and conventions): Форматы файлов как passwd, cron table, tar архивы
Специальные файлы (Special files): обычно устройства, например, найденные в /dev, и их драйверы.
Игры (Games): Описание команд, например, fortuna, которая при запуске показывает цитаты из БД
Дополнительно (Miscellaneous): Описание таких вещей как inodes, параметры загрузку
Администрирование системы (System administration): Команды и демоны, зарезервированные для использования root-ом.
Распорядок ядра (Kernel Routines): Информация, касающаяся внутренних операций ядра. Сюда входят функциональные интерфейсы и переменные, которые могут быть использованы программистами, которые разрабатывает драйвера устройств.
Цифры в скобках рядом с командой указывают на раздел руководства. Например, man (1) означает первый раздел руководства, которая описывает работу команды man.
На скриншоте выше видна ссылка на man (7). Это значит, что подробную информацию о команде можно найти в другом разделе. Когда впервые открываем руководство по команде, оно показывает man (1). Если ввели команду man без указания раздела, команда будет искать переданные параметр во всех разделы по очереди и конечно же первым выведет первый раздел.
Если нужно найти информацию в конкретном разделе нужно передать команде номер этого раздела.
Например, чтобы открыть седьмой раздел руководства по команде man введем следующую команду:
man 7 man
Руководство откроется с седьмого раздела:
Эта страница руководства содержит инструкции по созданию руководства. Она описывает формат файлов и макросы, которые можно использовать для автоматизации части работы. man (1) же в начале руководства описывает как вообще использовать саму команду man.
Поиск записей в разделах
В основном, если нужно просто узнать, как пользоваться той или иной командой, не надо указывать номер раздела. man найдёт стандартную запись в первом разделе руководства, которая описывает как нужно пользоваться командой. Иногда же, в поиске нестандартной информации, нужно открыть конкретный раздел, содержащий запись по команде.
В Linux легко можно найти разделы, в которых встречается нужная записб. Каждое руководство обладает названием и кратким описанием. Ключ –f (whatis) ведёт поиск по заголовкам и возвращает все вхождения.
Например, введем следующую команду:
man -f man
Команда нашла два совпадения для команды man с разделами и кратким описанием. Однако будьте осторожны - некоторые записи имеют одинаковое название, но описывают разные команды и функции.
Например, введём следующую команду:
man -f printf
Как видно, для команды printf были найдены две записи: одна в первом разделе, и другая в третьем разделе. Однако это разные команды. Информация в разделе 1 описывает команду printf командной строки, которая форматирует данные при выводе в окно терминала. В третьем же разделе описывается семейство функций библиотеки printf в языке программирования C.
Также возможен поиск по кратким описаниям, а также заголовкам страниц. Для этого используется параметр -k (apropos). Это также будет искать соответствия искомому термину поиска внутри других, более длинных слов.
Вводим следующее:
man -k printf
Многие из этих команд описаны в одних и тех же информационных страницах, поскольку их основные функциональные возможности в основном одинаковы. Справочная страница для vprintf описывает функциональность 10 команд, перечисленных на рисунке выше.
Эту функцию можно использовать для поиска информации, для выполнения конкретной задачи, даже если не знаете имя команды, которую хотите использовать.
Допустим, нужно изменить пароль учетной записи пользователя. Мы можем искать любые команды, которые упоминают "user" в заголовках или описаниях страницы. Затем его можно пропустить через функцию grep для поиска записей, содержащих слово "password".
Для этого нужно ввести следующую команду:
man -k 'user ' | grep password
Так как слово user мы выделили одинарными кавычками и в конце поставили пробел, команда будет искать только слово “user”, а не “users”. Бегло просмотрев результат, можно заметить, что самая подходящая команда это passwd.
Так как правило использования указано в первом разделе руководства, не нужно указывать конкретный раздел:
man passwd
Допустим на нужна команда, которая выводит количество слове в текстовом файле. Набираем в командной строке, что-то подобное:
man –k word | grep count
Чтобы узнать все, что нужно знать о подсчете слов, введите следующую команду:
man wc
Говоря о wc, мы также можем в качестве значения передать параметру –k точку ., что означает любой символ. А затем передать вывод команде wc, которой передадим еще и параметр –l (lines), на выводе мы получим число страниц руководства.
Чтобы сделать все это введем команду:
man -k . | wc -l
Итого, у нас 6 706 страниц руководства, но не пусть вас не путает, если у вас это число отличается, так как объем руководства напрямую зависит от установленных в системе программ и предустановленных справочников.
Поиск по руководству
Также есть возможность вести поиск по самому руководству. Например, давайте рассмотрим руководство по команде history:
man history
Чтобы вести поиск в следующих страницах от текущей вводим символ прямой косой черты / и набираем искомое слово. Результат этих действий будет отображаться внизу командной строки. Чтобы начать поиск нажимаем Enter.
Система выведет и выделит первое совпадение по искомому слову:
Чтобы перейти к следующему результату нажмите n, а чтобы перейти к предыдущим результатам – N.
Включить или выключить подсветку найденного слова можно сочетанием клавиш Esc+U.
Если же дошли до конца руководства, но не нашли нужную информацию, то можно вести поиск в обратном направлении. Для этого нажимаем ? и набираем нужный текст:
Также можно перемещаться вперед и назад по найденным результатам.
Есть другой способ поиска по руководству. Он скрывает все строки, которые не содержат совпадения с искомым словом, поэтому лучше использовать номера строк с этим методом.
Если набрать –N и нажать Enter во время просмотра руководства, то радом со строками отобразятся номера строк.
Теперь нажимаем на &, набираем искомое слово и нажимаем Enter.
Теперь отобразятся только строки, в которых найдено искомая фраза:
Просмотре вывод можно найти наиболее интересные результаты. Мы видим, что строка 292 наиболее подходящая и хотим просмотреть данный раздел руководства.
Чтобы показать все снова держим нажатым & и нажимаем Enter.
Теперь набираем номер строки: 292, а затем букву «g», чтобы перейти к указанной строке.
Как только мы нажмем «g» нас перебросит на 292 строку (именно поэтому на скриншоте выше не показана буква «g»).
Чтобы убрать нумерацию строк достаточно набрать –n и нажать Enter.
Прочитайте волшебное руководство
На страницах руководства много полезной информации. Даже у команд, которые вы думаете, вы хорошо знаете, есть такие возможности, о которых вы никогда не слышали.
Вы также определенно найдете команды, о существовании которых вы не знали. С таким количеством различных способов поиска и отслеживания информации, потрясающе иметь под рукой такую команду.
REST API – один из самых распространенных типов доступных веб-сервисов, но проектировать их сложно. Они позволяют разным клиентам, включая браузер, настольные приложения, мобильные приложения и практически любое устройство с подключением к Интернету, взаимодействовать с сервером. Именно поэтому очень важно правильно проектировать REST API, чтобы в будущем не было проблем.
Создание API с нуля может оказать непосильной задачей из-за большого количества вещей, которые необходимо учесть – от базовой безопасности до использования правильных методов HTTP, реализации аутентификации, определения того, какие запросы и ответы среди многих других принимаются и возвращаются. В этой статье я очень постарался сжать материал в 15 пунктов с важными рекомендациями, которые позволят создать хороший API. Все рекомендации никак не зависят от языка, поэтому потенциально применимы к любой платформе или технологии.
1. Обязательно используйте имена существительные в названиях путях к конечным точкам
Вам всегда следует использовать имена существительные, которые обозначают объект, который вы извлекаете или которым вы манипулируете. В качестве имени пути всегда предпочтительнее использовать множественное число. Избегайте использования глаголов в названиях путях к конечным точкам, потому что наш метод HTTP-запроса уже является глаголом и по сути не добавляет никакой новой информации.
Действие должно быть произведено с помощью методов HTTP-запроса. Наиболее распространенными являются методы GET, POST, PATCH, PUT и DELETE.
GET извлекает ресурсы
POST отправляет новые данные на сервер
PUT/PATCH модифицируют уже существующие данные
DELETE удаляет данные
Глаголы сопоставляются с функциями CRUD (Create, read, update и delete).
Помня об этих принципах, мы должны создавать маршруты типа GET /books для получения списка книг, а не GET /get-books или GET /book. Аналогично, POST /books - для добавления новой книги, PUT /books/:id - для модификации полных данных книги с заданным идентификатором (id), а PATCH /books/:id обновляет частичные изменения в книге. И наконец, DELETE /books/:id предназначен для удаления существующей книги в заданным идентификатором.
2. JSON как основной формат отправки и получения данных
Несколько лет назад прием и ответы на запросы API выполнялись в основном в XML. Но сейчас «стандартным» форматом для отправки и получения данных API в большинстве приложений стал JSON. Поэтому наш второй пункт рекомендует убедиться, что конечные точки возвращают формат данных JSON в качестве ответа, а также при приеме информации через полезную нагрузку HTTP-сообщений.
Несмотря на то, что FormData хорошо подходит для отправки данных от клиента, особенно если нам нужно отправлять файлы, они не очень подходят для текста и чисел. Нам не нужны FormData для их передачи, так как в большинстве фреймворков можно передавать JSON непосредственно на стороне клиента. При получении данных от клиента нам необходимо убедиться, что клиент правильно интерпретирует данные JSON, и для этого при выполнении запроса в заголовке ответа Content-Type должен быть установлен на application/json.
Стоит еще раз упомянуть исключение, когда мы пытаемся отправлять и получать файлы между клиентом и сервером. В этом конкретном случае нам необходимо обрабатывать файл ответа и отправлять FormData с клиента на сервер.
3. Используйте коды состояний HTTP
Коды состояний HTTP всегда полезно использовать для того, чтобы указать на выполнение или невыполнение запроса. Не используйте слишком много кодов состояний и всегда используйте одни и те же коды для одних и тех же результатов в API. Вот некоторые примеры:
200 – общее выполнение
201 – успешное создание
400 – неверные запросы от клиента, такие как неверные параметры
401 – несанкционированные запросы
403 – отсутствие прав доступа к ресурсам
404 – отсутствуют ресурсы
429 – слишком много запросов
5хх – внутренние ошибки (их следует избегать насколько это возможно)
В зависимости от ситуаций их может быть и больше, но ограничение количества кодов состояний помогает клиенту использовать более предсказуемый API.
4. Возвращайте стандартизированные сообщения
Помимо использования кодов состояния HTTP, которые указывают на результат запроса, всегда используйте стандартизированные ответы для аналогичных конечных точек. Пользователи могут всегда рассчитывать на одинаковую структуру и действовать соответственно. Это также относится к статусу, указывающему на выполнение запроса, и сообщениях об ошибках. В случае выборки коллекций придерживайтесь определенного формата, независимо от того, включает ли тело ответа массив данных, подобный этому:
[
{
bookId: 1,
name: "The Republic"
},
{
bookId: 2,
name: "Animal Farm"
}
]
или вот такой комбинированный ответ:
{
"data": [
{
"bookId": 1,
"name": "The Republic"
},
{
"bookId": 2,
"name": "Animal Farm"
}
],
"totalDocs": 200,
"nextPageId": 3
}
Здесь рекомендация заключается в том, чтобы быть последовательным независимо от того, какой подход вы выберете для этого. Аналогичное поведение должно быть реализовано при извлечении объекта, а также при создании и модификации ресурсов, которым обычно рекомендуется возвращать последний экземпляр объекта.
// Ответ после успешного вызова POST /books
{
"bookId": 3,
"name": "Brave New World"
}
Хоть это и никак не навредит, но все же излишнем будет включать универсальное сообщение, например, «Книга успешно создана», так как это уже следует из кода состояния HTTP.
И последнее, но не менее важное: при наличии стандартного формата ответа коды ошибок также важны (и даже более важные). Это сообщение должно включать информацию, которую клиент может использовать для представления ошибок конечному пользователю, а соответственно, это должно быть не общее предупреждение, такое как «то-то пошло не так», которого следует избегать, насколько это возможно. Вот пример:
{
"code": "book/not_found",
"message": "A book with the ID 6 could not be found"
}
Опять же, нет необходимости включать код состояния в содержимое ответа, но полезно определить набор кодов ошибок, таких как book/not_found, чтобы пользователь мог сопоставить их с разными строками и создать свое собственное сообщение об ошибке для конечного пользователя. В частности, для сред разработки или промежуточных сред может показаться правильным также включить стек ошибок в ответ с целью помочь в отладке ошибок. Но не включайте те, что находятся в промышленной эксплуатации, так как это создаст угрозу безопасности, раскрывая незапланированную информацию.
5. Используйте разбиение на страницы, фильтрацию и сортировку при выборе коллекций записей
Как только будет создана конечная точка, которая возвращает список элементов, необходимо будет установить разбиение на страницы. Обычно коллекции со временем растут, поэтому важно всегда следить за тем, чтобы возвращалось ограниченное и контролируемое количество элементов. Справедливо будет позволить пользователям API выбирать, сколько объектов получить, но всегда полезно заранее определить число и установить для него максимум. Основная причина, почему нужно это сделать, заключается в том, что для возврата огромного массива данных потребуется очень много времени и большая пропускная способность.
Для реализации нумерации страниц есть два хорошо известных способа: skip/limit или keyset. Первый вариант обеспечивает более удобный для пользователя способ извлечения данных, но обычно он менее эффективен, так как базы данных сканируют множество документов для извлечения нужных записей. Мне больше нравится второй вариант. Разделения на страницы с помощью keyset получает идентификатор (id) в качестве ссылки для «вырезания» коллекции или таблицы с условием без сканирования записей.
Также API должны предоставлять фильтры и возможности сортировки, которые упрощают способы получения данных. Частью решения повышения производительности являются индексные базы данных, которые позволяют максимизировать производительность при помощи шаблонов доступа, которые применяются с фильтрами и параметрами сортировки.
При проектировании API эти свойства разбиения на страницы, фильтрации и сортировки определяются как параметры запроса в URL-адресе. Например, если вы хотим получить информацию о первых 10 книгах, принадлежащих к категории «роман», то наша конечная точка будет выглядеть вот так:
GET /books?limit=10&category=romance
6. PATCH вместо PUT
Маловероятно, что необходимо будет сразу полностью обновить всю запись, обычно есть конфиденциальные или полные записи, которые следует уберечь от манипуляций пользователя. Именно поэтому для выполнения частичных обновлений ресурса следует использовать PATCH, а вот PUT полностью меняет существующий ресурс. Они оба должны использовать тело запроса для передачи информации, подлежащей модификации. Разница лишь в том, что для PATCH это поля, а для запроса PUT – полный объект. Тем не менее, стоит отметить, что ничто не мешает нам использовать PUT для частичной модификации, нет никаких «ограничений на передачу по сети», которые бы это подтверждали. Это просто факт, которого стоит придерживаться.
7. Предоставьте более подробные ответы
Шаблоны доступа являются ключевыми при создании доступных ресурсов API и возвращаемых данных. Когда система растет, то и свойства записи также растут, но не всегда все эти свойства нужны клиентам для работы. Именно в таких ситуациях становится полезным предоставление возможности возвращать сокращенные или полные ответы для одной и той же конечной точки. Если пользователю нужны только некоторые поля, то упрощенный ответ помогает снизить расход трафика и потенциально сложность получения других вычисляемых полей.
Простой способ реализовать – предоставить дополнительный параметр запроса, чтобы включить или отключить предоставление более подробного ответа.
GET /books/:id
{
"bookId": 1,
"name": "The Republic"
}GET /books/:id?extended=true
{
"bookId": 1,
"name": "The Republic"
"tags": ["philosophy", "history", "Greece"],
"author": {
"id": 1,
"name": "Plato"
}
}
8. Обязанность конечной точки
Принцип единственной обязанности фокусируется на концепции удержания функции, метода или класса на одной обязанности, которую они выполняют хорошо. Мы можем сказать, что это наш API - хороший API, если он выполняет одну конкретную вещь и никогда не меняется. Это помогает пользователям лучше понять наш API и сделать его более предсказуемым, что облегчит общую интеграцию. Лучше всего расширить список доступных конечных точек, а не создавать очень сложные конечные точки, которые пытаются решить множество задач одновременно.
9. Предоставьте полную документацию по API
Пользователи вашего API должны понимать, как использовать доступные конечные точки и чего ожидать. Это возможно только при наличии хорошей и подробной документации. Обратите внимание на следующие аспекты, чтобы ваша документация была полной.
Доступные конечные точки с описанием их назначения
Права доступа, необходимые для выполнения конечной точки
Примеры вызовов и ответов
Сообщения о предполагаемых ошибках
Немаловажным является постоянное обновление документации после внесения изменений и дополнений в систему. Лучший способ для этого – сделать документацию по API неотъемлемой частью разработки. Двумя хорошо известными инструментами в данном вопросе являются Swagger и Postman – они доступны для большинства сред разработки API.
10. Используйте SSL для обеспечения безопасности и настройте CORS
Безопасность – еще одно очень важной свойство, которым должен обладать наш API. Настройка SSL путем установки действительного сертификата на сервер обеспечит безопасную связь с пользователями и предотвратит некоторые виды потенциальных атак.
CORS (Cross-origin resource sharing – Обмен ресурсами с запросом происхождения) – это функция безопасности браузера, которая ограничивает HTTP-запросы из различных источников, которые инициируются сценариями, запущенными в браузере. Если ресурсы вашего REST API получают непростые HTTP-запросы из разных источников, то вам нужно включить поддержку CORS для того, чтобы пользователи работали соответствующим образом.
Протокол CORS требует, чтобы браузер отправил предварительный запрос на сервер и дождался утверждения (или запрос учетных данных) с сервера перед отправкой фактического запроса. Запрос предварительной проверки отображается в API как HTTP-запрос, использующий метод OPTIONS (среди других заголовков). Значит, для поддержки CORS в ресурсе REST API необходимо реализовать метод OPTIONS, который будет отвечать на предварительный запрос, по крайней мере, со следующими заголовками ответа, предусмотренными стандартом Fetch:
Access-Control-Allow-Methods
Access-Control-Allow-Headers
Access-Control-Allow-Origin
Какие значения назначать этим ключам, зависит от того, настолько открытым и гибким должен быть наш API. Мы можем назначить определённые методы и известные источники или использовать специальные символы, чтобы иметь открытые ограничения CORS.
11. Управление версиями API
В процессе разработки конечные точки начинают меняться и перестраиваться. Но мы должны, насколько это возможно, избегать внезапного изменения конечных точек для пользователя. Рекомендуется рассматривать API как ресурс с обратной совместимость, в котором новые и обновленные конечные точки должны быть доступны, но не должны влиять на предыдущие стандарты.
Вот где управление версиями API приходит на помощь – когда клиенты должны иметь возможность выбирать, к какой версии подключаться. Есть несколько способов описать управление версиями API:
Добавление нового заголовка x-version=v2
Наличие параметра запроса ?apiVersion=2
Версия как часть URL: /v2/books/:id
12. Кэшируйте данные для повышения производительности
Чтобы повысить производительность нашего API, полезно следить за данными, которые редко меняются и к которым часто обращаются. Для таких данных мы можем рассмотреть возможность использования базы данных в памяти или кэш-памяти, которая избавит от доступа к основной базе данных. Главная проблема здесь заключается в том, что данные могут устареть, поэтому следует решить вопрос с внедрением последней версии.
Использование кэшированных данных будет полезным для пользователей для загрузки конфигураций и каталогов информации, которые не предназначены для постоянного изменения в течение долгого времени. При использовании кэширования не забудьте включить Cache-Control в заголовки. Это поможет пользователям эффективно использовать систему кэширования.
13. Используйте даты в формате UTC
Сложно представить системы, которые в какой-то момент перестает работать из-за дат. На уровне данных важно быть логичным в том, как даты отображаются на клиентских приложениях. ISO 8601 – это международный стандартный формат данных для даты и времени. Данные должны быть в формате Z или UTC, для которых пользователи могут могли бы выбрать часовой пояс в случае, если такая дата должны отображаться при любых условиях. Вот пример того, как должны выглядеть даты:
{
"createdAt": "2022-03-08T19:15:08Z"
}
14. Конечная точка проверки работоспособности
Может произойти ситуация, когда наш API перестанет работать, и для его запуска потребуется время. При таких обстоятельствах клиенты хотят знать, что службы недоступны, и быть в курсе ситуации. Для этого предоставьте конечную точку (например, GET /health), которая бы определяла работоспособность API. Эта конечная точка может вызываться и другими приложениями, такими как балансировщики нагрузки. Можно продвинуться еще дальне и сообщать о периодах технического обслуживания или работоспособности частей API.
15. Разрешите аутентификацию по ключу API
Аутентификация с помощью ключей API даст возможность сторонним приложениям легко создавать интеграцию с нашим API. Эти ключи API следует передавать с помощью пользовательского заголовка HTTP (например, Api-Key или X-Api-Key). Ключи должны иметь дату окончания срока действия, и должна быть возможность их отозвать с целью признания недействительными по соображениям безопасности.
Друг, расскажем про интерфейс телефонной статистики для IP - АТС Asterisk под названием Merion Metrics. Интерфейс показывает ключевые диаграммы и графики по звонкам, а также историю звонков в формате, который легко поймет менеджер. По факту, это детально проработанный и красивый CDR для Astetrisk.
Про Merion Metrics
Если быть кратким:
Полная статистика - только самая важная информация: дата, время, откуда и куда был совершен вызов, аудио - запись;
Бесплатный тест - протестируйте интерфейс полностью - это бесплатно;
Установка за 10 минут - поддержка активно помогает с установкой;
Кроссплатформенность - сделано на Java. Совместимо с любой Unix платформой;
Для супервизоров - устали от CDR в FreePBX? Или CDR Viewer? мы знаем это чувство;
Удобная выгрузка в PDF и CSV - экспортируйте звонки в PDF и пересылайте/распечатывайте их для коллег;
Заказать бесплатную демо - версию можно по ссылке ниже:
Попробовать Merion Metrics
Установка Merion Metrics
Важно! На момент этого шага у вас должен быть лицензионный ключ. Закажите у нас демо доступ по ссылке https://asterisk.merionet.ru/merionmetrics
Конечно же, для удобства у нас есть пошаговое видео.
Видео - инструкция по установке Merion Metrics
Установка текстом
Системные требования
Оперативная память: 256 MB минимум
Процессор: Pentium 2 266 МГц + минимум
Java Runtime Environment (JRE): версия 8+
Браузер: Internet Explorer 9+
Подготовка
Подключитесь к серверу IP - АТС Asterisk по SSH под root пользователем.
Создание директории интерфейса
Дайте команды в консоль сервера:
mkdir /home/merionstat
Загрузите дистрибутив интерфейса MerionMonitoring-*.*.*.jar в свежесозданную директорию /home/merionstat. Через WinSCP, например.
Важно: загруженный вами дистрибутив будет иметь версионность. В руководстве, мы обозначаем MerionMonitoring-*.*.*.jar со звездочками. У вас будет MerionMonitoring-1.1.9.jar, например.
Создание SQL пользователя
Перейдите по ссылке для генерации устойчивого к взломам пароля. Запишите его. Далее, дайте следующую последовательность команд в консоль сервера:
mysql
CREATE USER 'interface'@'localhost' IDENTIFIED BY 'ваш_пароль';
GRANT SELECT, CREATE, INSERT ON asteriskcdrdb.* TO 'interface'@'localhost' IDENTIFIED BY 'ваш_пароль';
Где ваш_пароль - сгенерированный инструментом по ссылке пароль. Например:
mysql
CREATE USER 'interface'@'localhost' IDENTIFIED BY '6nzB0sOWzz';
GRANT SELECT, CREATE, INSERT ON asteriskcdrdb.* TO 'interface'@'localhost' IDENTIFIED BY '6nzB0sOWzz';
Сохраните пароль отдельно.
Директория для записей разговоров
Чтобы интерфейс мог воспроизводить ссылки на записи разговоров, необходимо сделать следующее:
Сгенерировать зашифрованную последовательность (пароль) через онлайн инструмент генерации. Сохраните его;
Дайте команды в консоль:
mkdir /var/www/html/сгенерированный_пароль
chown asterisk:asterisk /var/www/html/сгенерированный_пароль
chmod 775 /var/www/html/сгенерированный_пароль
Например:
mkdir /var/www/html/5v9MpbtUA8
chown asterisk:asterisk /var/www/html/5v9MpbtUA8
chmod 775 /var/www/html/5v9MpbtUA8
Откройте файл /etc/fstab и добавьте туда
/var/spool/asterisk/monitor/ /var/www/html/сгенерированный_пароль/ none rbind 0 0
Например:
/var/spool/asterisk/monitor/ /var/www/html/5v9MpbtUA8/ none rbind 0 0
Сохраните изменения в файле fstab. После, дайте следующую команду в консоль:
mount -a
Старт
Запуск интерфейса
Дайте следующие команды в консоль сервера:
cd /home/merionstat
nohup java -jar MerionMonitoring-*.*.*.jar &
Сразу после выполнения команды нажмите Enter.
Настройка интерфейса
Первое подключение
После запуска .jar файла, откройте в web - браузере (рекомендуем Google Chrome) адрес http://IP_адрес:7070/#!/config и введите лицензионный ключ, который вам предоставил сотрудник технической поддержки:
Нажмите “Проверить лицензию”. В случае, если возникнут проблемы на этом этапе, обратитесь в техническую поддержку (helpdesk@merionet.ru).
Далее, необходимо пройти первичную авторизацию. На этом экране введите логин и пароль: admin/IEJu1uh32
На следующем шаге конфигурации необходимо настроить подключение к БД. Для этого, в случае настройки IP - АТС Asterisk, укажите:
База данных - mysql, mariadb, или та, в которой хранятся ваши данные;
Хост БД - ;
если БД на том же сервере, что и установка интерфейса - localhost;
если БД на внешнем сервере, что и установка интерфейса - IP_адрес_БД;
Порт БД - проставляется автоматически. Меняйте, только если ваш сервер БД слушает запросы на другом порту;
Строка для подключения к БД - оставьте без изменений;
Наименование таблицы - если Asterisk, как правило, cdr;
Схема - это название базы данных. Для Asterisk, как правило, asteriskcdrdb;
Пользователь - мы создавали его в разделе “Создание SQL пользователя”. Если вы копировали команды точь в точь, то это будет interface;
Пароль - пароль, который вы сгенерировали для SQL пользователя через онлайн инструмент;
Хост записей разговоров - конструкция вида http://IP_адрес/сгенерированный_пароль/, где сгенерированный пароль - зашифрованная, которую вы создали на этапе подготовки в разделе “Директория для записей разговоров”. Например, может выглядеть как http://192.168.1.7/5v9MpbtUA8/;
Тип станции - Asterisk;
По окончанию настроек, нажмите “Подключиться”. Если у вас не получилось, напишите в техническую поддержку (helpdesk@merionet.ru).
На следующем этапе необходимо сопоставить название поля в таблице с его действующим значением. Как правило, в случае IP - АТС Asterisk все поля выставлено по умолчанию.
Внизу страницы нажмите кнопку “Установить соответствия”. После этого, нажмите “Запустить приложение”. Интерфейс сделает редирект на стартовую страницу. По умолчанию, логин и пароль администратора - admin/admin
Известные проблемы
Приложение уже запущено
Если вы не можете открыть приложение по адресу http://IP_адрес:7070/#!/config, то проверьте, не запущено ли оно ранее. Для этого дайте следующую команду в консоль:
ps aux | grep Merion
Проанализируйте вывод. Если он содержит строку вида:
root 4919 0.1 13.1 2120384 801784 ? Sl Dec11 19:12 java -jar MerionMonitoring-*.*.*.jar
То необходимо сделать следующее: вторым слева числом (после root, выделено оранжевым цветом) является PID процесса. Его нужно принудительно завершить. Для этого, копируем ID процесс в команду:
kill -9 4919
Делаем снова проверку ps aux | grep Merion
Если вывод более не содержит строку, как показано ранее - значит можете заново попробовать запустить команды:
cd /home/merionstat
nohup java -jar MerionMonitoring-*.*.*.jar &
База данных на внешнем сервере
Если вы выполняете подключение к удаленной базе данных, необходимо внести дополнительную конфигурацию в настройки MySQL, которые выполнялись на этапе “Создание SQL пользователя”. Например, это может понадобиться, если сервер с IP - АТС Asterisk находится на одной платформе, а сервер, где устанавливается интерфейс - на другой.
В таком случае, на сервере, где установлена БД (сервер IP - АТС Asterisk, как правило) необходимо выполнить следующие команды:
mysql
GRANT SELECT, CREATE, INSERT ON asteriskcdrdb.* TO 'interface'@'IP_адрес_интерфейса' IDENTIFIED BY 'ваш_пароль';
Где:
ваш_пароль - сгенерированный инструментом по ссылке пароль;
IP_адрес_интерфейса - IP - адрес машины, на котором вы устанавливаете дистрибутив интерфейса статистики.
Например:
mysql
GRANT SELECT, CREATE, INSERT ON asteriskcdrdb.* TO 'interface'@'192.168.1.78' IDENTIFIED BY '6nzB0sOWzz';
Помимо прочего, удостоверьтесь, что между узлами открыты порты:
3306 - для MySQL и MariaDB;
5432 - для PostgreSQL.
Медленная загрузка данных
Если вы наблюдаете проблемы с выгрузкой данных (долгая загрузка) - это связано с большим объемом базы данных.
Мы рекомендуем запускать интерфейс (.jar файл) с дополнительными ключами. Согласно пункта “Запуск интерфейса”, выполните следующую команду:
cd /home/merionstat
nohup java -jar MerionMonitoring-*.*.*.jar -Xms128m -Xmx256m &
Где:
-Xms128m - количество оперативной памяти, выделяемое приложению на старте. 128 мегабайт в данном примере;
-Xmx256m - максимально доступное количество оперативной памяти для приложения. 256 мегабайт в данном примере.
Как обратиться в поддержку?
Если вы испытываете технические трудности с настройкой интерфейса - мы поможем. Нам понадобятся файлы из директории /home/merionstat в которую вы разместили дистрибутив MerionMonitoring-*.*.*.jar, согласно пункта “Создание директории интерфейса”.
В зависимости от этапа возникновения сложности, там могут быть следующие файлы (помимо файла с расширением .jar):
columns_mapping.cfg
configuration.properties
nohup.out
Присылайте нам эти файлы с описанием проблемы и указывайте лицензионный ключ.
Связаться с нами можно следующим образом:
Telegram бот - @merion_support_bot
Электронная почта - helpdesk@merionet.ru