8.4.6 The Audit Message Component — MySQL 8.4

8.4.6 Компонент сообщений аудита

Компонент audit_api_message_emit позволяет приложениям добавлять собственные события сообщений в журнал аудита, используя функцию audit_api_message_emit_udf().

Компонент audit_api_message_emit взаимодействует со всеми плагинами типа аудита. Для конкретности, примеры используют плагин audit_log, описанный в разделе 8.4.5, «MySQL Enterprise Audit».

Установка или удаление компонента сообщений аудита

Для использования компонентом сервером, библиотечный файл компонента должен находиться в каталоге плагинов MySQL (каталог, указанный системной переменной plugin_dir). При необходимости, конфигурируйте расположение каталога плагинов, установив значение plugin_dir при запуске сервера.

Для установки компонента audit_api_message_emit используйте это утверждение:

INSTALL COMPONENT "file://component_audit_api_message_emit";

Установка компонента выполняется один раз и не требует выполнения каждый раз при запуске сервера. INSTALL COMPONENT загружает компонент, а также регистрирует его в системной таблице mysql.component, чтобы он загружался при последующих запусках сервера.

Для удаления компонента audit_api_message_emit используйте это утверждение:

UNINSTALL COMPONENT "file://component_audit_api_message_emit";

UNINSTALL COMPONENT разгружает компонент и удаляет его из системной таблицы mysql.component, чтобы он не загружался при последующих запусках сервера.

Поскольку установка и удаление компонента audit_api_message_emit устанавливает и удаляет функцию audit_api_message_emit_udf(), которую реализует компонент, не нужно использовать CREATE FUNCTION или DROP FUNCTION для этого.

Функция сообщений аудита

В этом разделе описана функция audit_api_message_emit_udf(), реализованная компонентом audit_api_message_emit.

Перед использованием функции сообщений аудита установите компонент сообщений аудита в соответствии с инструкциями в разделе «Установка или удаление компонента сообщений аудита».

audit_api_message_emit_udf(component, producer, message[, key, value] ...)

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

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

Аргументы:
- component: Строка, указывающая имя компонента.
- producer: Строка, указывающая имя производителя.
- message: Строка, указывающая сообщение события.
- key, value: События могут включать 0 или более пар ключ-значение, определяющих произвольную предоставляемую приложением карту данных. Каждый аргумент key — это строка, определяющая имя для следующего аргумента value. Каждый аргумент value определяет значение для следующего аргумента key. Каждый value может быть строковым или числовым значением, или NULL.
Значение возврата:

Строка OK, чтобы указать успешное выполнение. Возникает ошибка, если функция завершается неудачно.

Пример:
```
mysql> SELECT audit_api_message_emit_udf('component_text',
                                         'producer_text',
                                         'message_text',
                                         'key1', 'value1',
                                         'key2', 123,
                                         'key3', NULL) AS 'Message';
+---------+
| Message |
+---------+
| OK      |
+---------+
```
Дополнительная информация:

Каждый плагин аудита, который получает событие, опубликованное функцией audit_api_message_emit_udf(), регистрирует событие в формате, специфичном для плагина. Например, плагин audit_log (см. раздел 8.4.5, «MySQL Enterprise Audit») регистрирует значения сообщений следующим образом, в зависимости от формата журнала, настроенного системной переменной audit_log_format:
- Формат JSON (audit_log_format=JSON):
```
{
  ...
  "class": "message",
  "event": "user",
  ...
  "message_data": {
    "component": "component_text",
    "producer": "producer_text",
    "message": "message_text",
    "map": {
      "key1": "value1",
      "key2": 123,
      "key3": null
    }
  }
}
```
- Формат XML нового стиля (audit_log_format=NEW):
```
<AUDIT_RECORD>
 ...
 <NAME>Message</NAME>
 ...
 <COMMAND_CLASS>user</COMMAND_CLASS>
 <COMPONENT>component_text</COMPONENT>
 <PRODUCER>producer_text</PRODUCER>
 <MESSAGE>message_text</MESSAGE>
 <MAP>
   <ELEMENT>
     <KEY>key1</KEY>
     <VALUE>value1</VALUE>
   </ELEMENT>
   <ELEMENT>
     <KEY>key2</KEY>
     <VALUE>123</VALUE>
   </ELEMENT>
   <ELEMENT>
     <KEY>key3</KEY>
     <VALUE/>
   </ELEMENT>
 </MAP>
</AUDIT_RECORD>
```
- Формат XML старого стиля (audit_log_format=OLD):
```
<AUDIT_RECORD
  ...
  NAME="Message"
  ...
  COMMAND_CLASS="user"
  COMPONENT="component_text"
  PRODUCER="producer_text"
  MESSAGE="message_text"/>
```
  Примечание
  
  События сообщений, записанные в формате XML старого стиля, не включают карту ключ-значение из-за ограничений представления, налагаемых этим форматом.
Сообщения, опубликованные функцией audit_api_message_emit_udf(), имеют класс события MYSQL_AUDIT_MESSAGE_CLASS и подкласс MYSQL_AUDIT_MESSAGE_USER. (Внутренне сгенерированные сообщения аудита имеют тот же класс и подкласс MYSQL_AUDIT_MESSAGE_INTERNAL; этот подкласс в настоящее время не используется.) Чтобы сослаться на такие события в правилах фильтрации audit_log, используйте элемент class со значением name message. Например:
```
{
  "filter": {
    "class": {
      "name": "message"
    }
  }
}
```
В случае необходимости различать сгенерированные пользователем и внутренне сгенерированные события сообщений, проверьте значение subclass на соответствие значению user или internal.

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

Сведения о написании правил фильтрации см. в разделе 8.4.5.7, «Фильтрация журнала аудита».