### 6.4.6 审计消息组件

从 MySQL 8.0.14 开始，`audit_api_message_emit`组件使应用程序能够将自己的消息事件添加到审计日志，使用[`audit_api_message_emit_udf()`](audit-api-message-emit.html#function_audit-api-message-emit-udf)功能。

这`audit_api_message_emit`组件与所有审计类型的插件合作。为了具体起见，示例使用`审计日志`插件中描述[第 6.4.5 节，“MySQL 企业审计”](audit-log.html).

-   [安装或卸载审计消息组件](audit-api-message-emit.html#audit-api-message-emit-install)

-   [审计消息功能](audit-api-message-emit.html#audit-api-message-emit-functions)

#### 安装或卸载审计消息组件

要被服务器使用，组件库文件必须位于 MySQL 插件目录（由[`插件目录`](server-system-variables.html#sysvar_plugin_dir)系统变量）。如有必要，通过设置值来配置插件目录位置[`插件目录`](server-system-variables.html#sysvar_plugin_dir)在服务器启动时。

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

```
INSTALL COMPONENT "file://component_audit_api_message_emit";
```

组件安装是一次性操作，不需要每次服务器启动都完成。[`安装组件`](install-component.html)加载组件，并将其注册到`mysql.component`系统表，使其在随后的服务器启动期间被加载。

要卸载`audit_api_message_emit`组件，请使用以下语句：

```
UNINSTALL COMPONENT "file://component_audit_api_message_emit";
```

[`卸载组件`](uninstall-component.html)卸载组件，并从`mysql.component`系统表，以使其在后续服务器启动期间不被加载。

因为安装和卸载`audit_api_message_emit`组件安装和卸载[`audit_api_message_emit_udf()`](audit-api-message-emit.html#function_audit-api-message-emit-udf)组件实现的功能，不需要使用`创建函数`要么`拖放功能`这样做。

#### 审计消息功能

本节介绍[`audit_api_message_emit_udf()`](audit-api-message-emit.html#function_audit-api-message-emit-udf)实现的功能`audit_api_message_emit`零件。

在使用审计消息功能之前，请根据提供的说明安装审计消息组件[安装或卸载审计消息组件](audit-api-message-emit.html#audit-api-message-emit-install).

-   [](<>) [`audit_api_message_emit_udf(*`零件`*, *`制片人`*, *`信息`*[, *`钥匙`*, *`价值`*] ...)`](audit-api-message-emit.html#function_audit-api-message-emit-udf)

    [](<>)[](<>)

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

    此函数发布的事件被发送到所有启用的审计类型插件，每个插件根据自己的规则处理事件。如果没有启用审计类型的插件，则发布事件无效。

    论据：

    -   *`零件`*：指定组件名称的字符串。

    -   *`制片人`*：指定生产者名称的字符串。

    -   *`信息`*：指定事件消息的字符串。

    -   *`钥匙`*,*`价值`*：事件可能包含 0 个或多个键值对，它们指定任意应用程序提供的数据映射。每个*`钥匙`*参数是一个字符串，它指定紧随其后的名称*`价值`*争论。每个*`价值`*参数为其紧随其后的指定一个值*`钥匙`*争论。每个*`价值`*可以是字符串或数值，或者`空值`.

        返回值：

        字符串`好的`表示成功。如果函数失败，则会发生错误。

        例子：

    ```
    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-api-message-emit.html#function_audit-api-message-emit-udf)以插件特定的格式记录事件。例如，`审计日志`插件（见[第 6.4.5 节，“MySQL 企业审计”](audit-log.html)) 记录消息值如下，具体取决于配置的日志格式[`审计日志格式`](audit-log-reference.html#sysvar_audit_log_format)系统变量：

    -   JSON 格式 ([`audit_log_format=JSON`](audit-log-reference.html#sysvar_audit_log_format)):

        ```
        {
          ...
          "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=新`](audit-log-reference.html#sysvar_audit_log_format)):

        ```
        <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-log-reference.html#sysvar_audit_log_format)):

        ```
        <AUDIT_RECORD
          ...
          NAME="Message"
          ...
          COMMAND_CLASS="user"
          COMPONENT="component_text"
          PRODUCER="producer_text"
          MESSAGE="message_text"/>
        ```

        笔记

        由于这种格式强加的表示约束，以旧式 XML 格式记录的消息事件不包括键值映射。

        发布的消息[`audit_api_message_emit_udf()`](audit-api-message-emit.html#function_audit-api-message-emit-udf)有一个事件类`MYSQL_AUDIT_MESSAGE_CLASS`和一个子类`MYSQL_AUDIT_MESSAGE_USER`.（内部生成的审计消息具有相同的类和一个子类`MYSQL_AUDIT_MESSAGE_INTERNAL`;此子类当前未使用。）引用此类事件`审计日志`过滤规则，使用`班级`带有 a 的元素`姓名`的价值`信息`.例如：

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

    如果有必要区分用户生成和内部生成的消息事件，请测试`子类`反对价值`用户`要么`内部的`.

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

    有关编写过滤规则的信息，请参阅[第 6.4.5.7 节，“审核日志过滤”](audit-log-filtering.html).
