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

MySQL 8.4 参考手册 · 中文镜像

正文为中文，英文原文默认隐藏。点击任意中文段落即可展开 / 收起对应英文原文。

译文由机器翻译生成，仅供理解参考；有疑问请以官方英文原文为准。

MySQL 8.4 参考手册 / 8 安全 / 8.4 安全组件和插件 / 8.4.6 审核消息组件

中文点击中文段落可显示 / 隐藏英文原文本页译文覆盖 100%

8.4.6 审计消息组件8.4.6 The Audit Message Component

audit_api_message_emit 组件使应用程序能够使用 audit_api_message_emit_udf() 函数将其自己的消息事件添加到审计日志中。The audit_api_message_emit component enables applications to add their own message events to the audit log, using the audit_api_message_emit_udf() function.

audit_api_message_emit 组件与所有审计类型的插件协作。为具体说明，示例使用 audit_log 插件，如第 8.4.5 节，“MySQL 企业审计” 中所述。The audit_api_message_emit component cooperates with all plugins of audit type. For concreteness, examples use the audit_log plugin described in Section 8.4.5, “MySQL Enterprise Audit”.

安装或卸载审计消息组件Installing or Uninstalling the Audit Message Component

为了服务器能够使用，该组件库文件必须位于 MySQL 插件目录中（该目录由plugin_dir系统变量指定）。如有必要，可在服务器启动时通过设置plugin_dir的值来配置插件目录位置。To be usable by the server, the component library file must be located in the MySQL plugin directory (the directory named by the plugin_dir system variable). If necessary, configure the plugin directory location by setting the value of plugin_dir at server startup.

要安装audit_api_message_emit组件，可使用以下语句：To install the audit_api_message_emit component, use this statement:

INSTALL COMPONENT "file://component_audit_api_message_emit";

组件安装是一次性操作，无需在每次服务器启动时执行。INSTALL COMPONENT 会加载组件，并将其注册到 mysql.component 系统表中，以便在后续服务器启动时加载该组件。Component installation is a one-time operation that need not be done per server startup. INSTALL COMPONENT loads the component, and also registers it in the mysql.component system table to cause it to be loaded during subsequent server startups.

要卸载 audit_api_message_emit 组件，请使用以下语句：To uninstall the audit_api_message_emit component, use this statement:

UNINSTALL COMPONENT "file://component_audit_api_message_emit";

UNINSTALL COMPONENT 会卸载组件，并将其从 mysql.component 系统表中注销，以便在后续服务器启动时不加载该组件。UNINSTALL COMPONENT unloads the component, and unregisters it from the mysql.component system table to cause it not to be loaded during subsequent server startups.

因为安装和卸载 audit_api_message_emit 组件会安装和卸载该组件实现的 audit_api_message_emit_udf() 函数，所以不需要使用 CREATE FUNCTION 或 DROP FUNCTION 来执行此操作。Because installing and uninstalling the audit_api_message_emit component installs and uninstalls the audit_api_message_emit_udf() function that the component implements, it is not necessary to use CREATE FUNCTION or DROP FUNCTION to do so.

审计消息函数Audit Message Function

本节介绍由 audit_api_message_emit 组件实现的 audit_api_message_emit_udf() 函数。This section describes the audit_api_message_emit_udf() function implemented by the audit_api_message_emit component.

在使用审计消息函数之前，请按照安装或卸载审计消息组件中提供的说明安装审计消息组件。Before using the audit message function, install the audit message component according to the instructions provided at Installing or Uninstalling the Audit Message Component.

audit_api_message_emit_udf(component, producer, message[, key, value] ...) audit_api_message_emit_udf(component, producer, message[, key, value] ...)
将消息事件添加到审计日志中。消息事件包括调用者选择的组件、生成者和消息字符串，以及可选的一组键值对。Adds a message event to the audit log. Message events include component, producer, and message strings of the caller's choosing, and optionally a set of key-value pairs.
此函数发布的事件会发送到所有启用的审计类型插件，每个插件会根据自己的规则处理该事件。如果没有启用审计类型的插件，发布事件将不会产生任何效果。An event posted by this function is sent to all enabled plugins of audit type, each of which handles the event according to its own rules. If no plugin of audit type is enabled, posting the event has no effect.
参数：Arguments:
- component: 一个字符串，指定组件名称。component: A string that specifies a component name.
- producer: 一个字符串，指定生产者名称。producer: A string that specifies a producer name.
- message: 一个字符串，指定事件消息。message: A string that specifies the event message.
- key, value: 事件可以包含 0 个或多个键值对，用于指定任意应用提供的数据映射。每个 key 参数是一个字符串，用于指定其紧随的 value 参数的名称。每个 value 参数指定其紧随的 key 参数的值。每个 value 可以是字符串或数值，或 NULL。key, value: Events may include 0 or more key-value pairs that specify an arbitrary application-provided data map. Each key argument is a string that specifies a name for its immediately following value argument. Each value argument specifies a value for its immediately following key argument. Each value can be a string or numeric value, or NULL.
返回值：Return value:
字符串 OK 表示成功。如果函数失败，则会发生错误。The string OK to indicate success. An error occurs if the function fails.
示例：Example:
```
mysql> SELECT audit_api_message_emit_udf('component_text',
                                         'producer_text',
                                         'message_text',
                                         'key1', 'value1',
                                         'key2', 123,
                                         'key3', NULL) AS 'Message';
+---------+
| Message |
+---------+
| OK      |
+---------+
```
附加信息：Additional information:
每个接收到由audit_api_message_emit_udf()发布的事件的审计插件都会以插件特定的格式记录该事件。例如，audit_log 插件（见第 8.4.5 节，“MySQL 企业审计”）会根据 audit_log_format 系统变量配置的日志格式记录消息值，如下所示：Each audit plugin that receives an event posted by audit_api_message_emit_udf() logs the event in plugin-specific format. For example, the audit_log plugin (see Section 8.4.5, “MySQL Enterprise Audit”) logs message values as follows, depending on the log format configured by the audit_log_format system variable:
- JSON 格式 (audit_log_format=JSON)：JSON format (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)：New-style XML format (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):Old-style XML format (audit_log_format=OLD):
```
<AUDIT_RECORD
  ...
  NAME="Message"
  ...
  COMMAND_CLASS="user"
  COMPONENT="component_text"
  PRODUCER="producer_text"
  MESSAGE="message_text"/>
```
  Note
  以旧式 XML 格式记录的消息事件由于该格式的表现限制，不包括键值映射。Message events logged in old-style XML format do not include the key-value map due to representational constraints imposed by this format.
由 audit_api_message_emit_udf() 发布的消息具有 MYSQL_AUDIT_MESSAGE_CLASS 的事件类和 MYSQL_AUDIT_MESSAGE_USER 的子类。（内部生成的审计消息具有相同的类和 MYSQL_AUDIT_MESSAGE_INTERNAL 子类；该子类目前未使用。）在 audit_log 过滤规则中引用此类事件时，使用 class 元素，其 name 值为 message。例如：Messages posted by audit_api_message_emit_udf() have an event class of MYSQL_AUDIT_MESSAGE_CLASS and a subclass of MYSQL_AUDIT_MESSAGE_USER. (Internally generated audit messages have the same class and a subclass of MYSQL_AUDIT_MESSAGE_INTERNAL; this subclass currently is unused.) To refer to such events in audit_log filtering rules, use a class element with a name value of message. For example:
```
{
  "filter": {
    "class": {
      "name": "message"
    }
  }
}
```
如果有必要区分用户生成的和内部生成的消息事件，请将 subclass 的值与 user 或 internal 进行测试。Should it be necessary to distinguish user-generated and internally generated message events, test the subclass value against user or internal.
不支持基于键值映射内容的过滤。Filtering based on the contents of the key-value map is not supported.
有关编写过滤规则的信息，请参阅第 8.4.5.7 节，“审计日志过滤”。For information about writing filtering rules, see Section 8.4.5.7, “Audit Log Filtering”.

首页上一级下一节