从MySQL 8.0.14开始,该audit_api_message_emit 组件使应用程序可以使用audit_api_message_emit_udf() 用户定义的函数将其自己的消息事件添加到审核日志中 。

该audit_api_message_emit组件与所有审核类型的插件配合使用。具体而言,示例使用第6.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_udf() 由audit_api_message_emit组件实现的 用户定义功能(UDF) 。

在使用审核消息功能之前,请根据“ 安装或卸载审核消息组件”中提供的说明 安装审核消息组件。

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

将消息事件添加到审核日志。消息事件包括调用者选择的组件,生产者和消息字符串,以及可选的一组键值对。

该UDF发布的事件将发送到所有启用的审计类型的插件,每个插件均根据其自己的规则处理该事件。如果未启用审核类型的插件,则发布事件无效。

参数:

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插件(请参见 第6.4.5节“ MySQL企业审核”)记录消息值如下 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):

...
Message
...
user
component_text
producer_text
message_text
key1
value1
key2
123
key3
旧式XML格式(audit_log_format=OLD):
...
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元素 。例如:

namemessage
{
"filter": {
"class": {
"name": "message"
}
}
}

如果有必要区分用户生成的消息事件和内部生成的消息事件,请subclass针对user或测试 值 internal。

不支持基于键值映射的内容进行过滤。

有关编写过滤规则的信息,请参见 第6.4.5.6节“审核日志过滤”。