MySQL :: MySQL 8.4 参考手册 :: 8.4.6 审计消息组件

版本 8.4

9.0
8.0

8.0 日语

MySQL 8.4 参考手册 / ... / 审计消息组件

8.4.6 审计消息组件

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

audit_api_message_emit 组件与所有审计类型的插件配合使用。为了具体起见，示例使用第 8.4.5 节“MySQL 企业版审计” 中描述的 audit_log 插件。

安装或卸载审计消息组件

要使服务器可以使用该组件库文件，它必须位于 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 组件实现的 audit_api_message_emit_udf() 函数。

在使用审计消息函数之前，请根据安装或卸载审计消息组件中提供的说明安装审计消息组件。

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 过滤规则中引用此类事件，请使用具有 name 值为 message 的 class 元素。例如
```
{
  "filter": {
    "class": {
      "name": "message"
    }
  }
}
```
如果需要区分用户生成的事件和内部生成的事件，请将 subclass 值与 user 或 internal 进行比较。
不支持基于键值映射内容进行过滤。
有关编写过滤规则的信息，请参见第 8.4.5.7 节，“Audit Log Filtering”。