MySQL :: MySQL 8.3 Reference Manual :: 8.4.6 The Audit Message Component

Documentation Home

version 8.3

8.0 current

8.0 Japanese

MySQL 8.3 Reference Manual / ... / The Audit Message Component

8.4.6 审核消息组件

该 audit_api_message_emit 组件使应用程序能够将自己的消息事件添加到审核日志中，使用 audit_api_message_emit_udf() 函数。

该 audit_api_message_emit 组件与所有审核类型的插件合作。例如，使用 audit_log 插件，如第 8.4.5 节，“MySQL 企业审核” 所述。

安装或卸载审核消息组件

要使服务器可用，组件库文件必须位于 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(组件, 生产者, 消息[, 键, 值] ...)

将消息事件添加到审核日志中。消息事件包括组件、生产者和消息字符串，可以选择性地包括一组键值对。

由该函数发布的事件将被发送到所有启用的审核类型插件，每个插件根据自己的规则处理事件。如果没有启用审核类型插件，则发布事件无效。

参数：
- 组件：指定组件名称的字符串。
- 生产者：指定生产者名称的字符串。
- 消息：指定事件消息的字符串。
- 键, 值：事件可以包括 0 个或多个键值对，指定应用程序提供的数据映射。每个 键 参数都是一个字符串，指定其紧跟的 值 参数的名称。每个 值 参数指定其紧跟的 键 参数的值。每个 值 可以是字符串或数字值，或者 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"/>
```
  Note
  
  以旧式 XML 格式记录的消息事件不包括键值映射，因为该格式存在表示约束。
由 audit_api_message_emit_udf() 发送的消息具有事件类 MYSQL_AUDIT_MESSAGE_CLASS 和子类 MYSQL_AUDIT_MESSAGE_USER。（内部生成的审核消息具有相同的类和子类 MYSQL_AUDIT_MESSAGE_INTERNAL；当前该子类未使用。）要在 audit_log 筛选规则中引用这些事件，请使用 class 元素，名称值为 message。例如：
```
{
  "filter": {
    "class": {
      "name": "message"
    }
  }
}
```
如果需要区分用户生成和内部生成的消息事件，请测试 subclass 值是否为 user 或 internal。

基于键值映射内容的筛选不受支持。

有关编写筛选规则的信息，请参阅第 8.4.5.7 节，“审核日志筛选”。

PREV HOME UP NEXT