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

Documentation Home

version 8.4

8.0 current

8.0 Japanese

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

8.4.6 审计消息组件

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

该audit_api_message_emit 组件与所有类型的插件合作。为了明确，示例使用第8.4.5节，“MySQL Enterprise Audit”中描述的audit_log插件。

服务器可以使用组件库文件，必须位于MySQL插件目录（由plugin_dir系统变量指定的目录）。如果必要，可以在服务器启动时设置plugin_dir值来配置插件目录位置。

要安装audit_api_message_emit 组件，使用以下语句：

INSTALL COMPONENT "file://component_audit_api_message_emit";

组件安装是一次性操作，不需要在每个服务器启动时执行。INSTALL COMPONENT 将加载组件，并将其注册到 mysql.component 系统表中，以便在后续服务器启动时自动加载。

卸载UNINSTALL COMPONENT 将卸载组件，并从 mysql.component 系统表中删除，以便在后续服务器启动时不自动加载。

UNINSTALL COMPONENT "file://component_audit_api_message_emit";

UNINSTALL COMPONENT 卸载组件，并从 mysql.component 系统表中删除，以便在后续服务器启动时不自动加载。

因为安装和卸载audit_api_message_emit_udf() 组件将安装和卸载该组件实现的 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"/>
```
  Note
  
  在老式XML格式中记录的事件消息不包括键值对，因为这个格式施加了表示限制。
由audit_api_message_emit_udf()发布的消息事件的event类别为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节，“审核日志过滤”。

PREV HOME UP NEXT