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

版本 9.0

8.4 当前
8.0

8.0 日语

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

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