#### 6.4.5.8 编写审核日志过滤器定义

过滤器定义是[`JSON`](json.html)价值观。有关使用的信息[`JSON`](json.html)MySQL 中的数据，请参阅[第 11.5 节，“JSON 数据类型”](json.html).

过滤器定义具有这种形式，其中*`行动`*指示如何进行过滤：

```
{ "filter": actions }
```

以下讨论描述了过滤器定义中允许的构造。

-   [记录所有事件](audit-log-filter-definitions.html#audit-log-filtering-enabling-logging)

-   [记录特定事件类](audit-log-filter-definitions.html#audit-log-filtering-class-logging)

-   [记录特定事件子类](audit-log-filter-definitions.html#audit-log-filtering-subclass-logging)

-   [包容性和独占性日志记录](audit-log-filter-definitions.html#audit-log-filtering-inclusive-exclusive)

-   [测试事件字段值](audit-log-filter-definitions.html#audit-log-filtering-event-fields)

-   [阻止特定事件的执行](audit-log-filter-definitions.html#audit-log-filtering-blocking-events)

-   [逻辑运算符](audit-log-filter-definitions.html#audit-log-filtering-logical-operators)

-   [引用预定义变量](audit-log-filter-definitions.html#audit-log-filtering-predefined-variables)

-   [引用预定义函数](audit-log-filter-definitions.html#audit-log-filtering-predefined-functions)

-   [替换事件字段值](audit-log-filter-definitions.html#audit-log-filtering-field-replacement)

-   [更换用户过滤器](audit-log-filter-definitions.html#audit-log-filtering-filter-replacement)

##### 记录所有事件

要显式启用或禁用所有事件的日志记录，请使用`日志`过滤器中的项目：

```
{
  "filter": { "log": true }
}
```

这`日志`值可以是`真的`要么`错误的`.

前面的过滤器启用了所有事件的日志记录。它相当于：

```
{
  "filter": { }
}
```

日志记录行为取决于`日志`价值和是否`班级`要么`事件`项目被指定：

-   和`日志`指定时，使用其给定值。

-   没有`日志`指定，日志记录是`真的`如果不`班级`要么`事件`项目被指定，并且`错误的`否则（在这种情况下，`班级`要么`事件`可以包括他们自己的`日志`物品）。

##### 记录特定事件类

要记录特定类的事件，请使用`班级`过滤器中的项目，其`姓名`表示要记录的类的名称的字段：

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

这`姓名`值可以是`联系`,`一般的`， 要么`表访问`分别记录连接、一般或表访问事件。

前面的过滤器启用在`联系`班级。它等效于以下过滤器`日志`明确的项目：

```
{
  "filter": {
    "log": false,
    "class": { "log": true,
               "name": "connection" }
  }
}
```

要启用多个类的日志记录，请定义`班级`价值作为[`JSON`](json.html)命名类的数组元素：

```
{
  "filter": {
    "class": [
      { "name": "connection" },
      { "name": "general" },
      { "name": "table_access" }
    ]
  }
}
```

笔记

当给定项目的多个实例出现在过滤器定义中的同一级别时，项目值可以组合成数组值中该项目的单个实例。前面的定义可以这样写：

```
{
  "filter": {
    "class": [
      { "name": [ "connection", "general", "table_access" ] }
    ]
  }
}
```

##### 记录特定事件子类

要选择特定的事件子类，请使用`事件`包含一个项目`姓名`命名子类的项目。由一个选择的事件的默认操作`事件`项目是记录它们。例如，此过滤器启用命名事件子类的日志记录：

```
{
  "filter": {
    "class": [
      {
        "name": "connection",
        "event": [
          { "name": "connect" },
          { "name": "disconnect" }
        ]
      },
      { "name": "general" },
      {
        "name": "table_access",
        "event": [
          { "name": "insert" },
          { "name": "delete" },
          { "name": "update" }
        ]
      }
    ]
  }
}
```

这`事件`item 还可以包含显式`日志`指示是否记录合格事件的项目。这`事件`item 选择多个事件并明确指示它们的日志记录行为：

```
"event": [
  { "name": "read", "log": false },
  { "name": "insert", "log": true },
  { "name": "delete", "log": true },
  { "name": "update", "log": true }
]
```

这`事件`item 还可以指示是否阻止符合条件的事件，如果它包含`中止`物品。有关详细信息，请参阅[阻止特定事件的执行](audit-log-filter-definitions.html#audit-log-filtering-blocking-events).

[表 6.34，“事件类和子类组合”](audit-log-filter-definitions.html#audit-log-event-subclass-combinations)描述每个事件类允许的子类值。

[](<>)

**表 6.34 事件类和子类组合**

| 事件类 | 事件子类 | 描述 |
| --- | ---- | --- |
| `联系` | `连接` | 连接启动（成功或不成功） |
| `联系` | `更改用户` | 在会话期间使用不同的用户/密码重新认证用户 |
| `联系` | `断开` | 连接终止 |
| `一般的` | `状态` | 一般操作信息 |
| `信息` | `内部的` | 内部生成的消息 |
| `信息` | `用户` | 生成的消息[`audit_api_message_emit_udf()`](audit-api-message-emit.html#function_audit-api-message-emit-udf) |
| `表访问` | `读` | 表读取语句，例如[`选择`](select.html)要么[`插入...选择`](insert-select.html) |
| `表访问` | `删除` | 表删除语句，如[`删除`](delete.html)要么[`截断表`](truncate-table.html) |
| `表访问` | `插入` | 表插入语句，例如[`插入`](insert.html)要么[`代替`](replace.html) |
| `表访问` | `更新` | 表更新语句，例如[`更新`](update.html) |

[表 6.35，“每个事件类和子类组合的日志和中止特征”](audit-log-filter-definitions.html#audit-log-event-subclass-log-abort)描述每个事件子类是否可以记录或中止。

[](<>)

**表 6.35 每个事件类和子类组合的日志和中止特征**

| 事件类 | 事件子类 | 可以记录 | 可以中止 |
| --- | ---- | ---- | ---- |
| `联系` | `连接` | 是的 | 不 |
| `联系` | `更改用户` | 是的 | 不 |
| `联系` | `断开` | 是的 | 不 |
| `一般的` | `状态` | 是的 | 不 |
| `信息` | `内部的` | 是的 | 是的 |
| `信息` | `用户` | 是的 | 是的 |
| `表访问` | `读` | 是的 | 是的 |
| `表访问` | `删除` | 是的 | 是的 |
| `表访问` | `插入` | 是的 | 是的 |
| `表访问` | `更新` | 是的 | 是的 |

##### 包容性和独占性日志记录

过滤器可以定义为包含或排除模式：

-   包含模式仅记录明确指定的项目。

-   独占模式记录除明确指定的项目之外的所有内容。

    要执行包容性日志记录，请全局禁用日志记录并为特定类启用日志记录。此过滤器记录`连接`和`断开`中的事件`联系`类和事件`一般的`班级：


```
{
  "filter": {
    "log": false,
    "class": [
      {
        "name": "connection",
        "event": [
          { "name": "connect", "log": true },
          { "name": "disconnect", "log": true }
        ]
      },
      { "name": "general", "log": true }
    ]
  }
}
```

要执行独占日志记录，请全局启用日志记录并禁用特定类的日志记录。此过滤器记录除事件之外的所有内容`一般的`班级：

```
{
  "filter": {
    "log": true,
    "class":
      { "name": "general", "log": false }
  }
}
```

此过滤器记录`更改用户`中的事件`联系`班级，`信息`事件，和`表访问`事件，凭借*不是*记录其他所有内容：

```
{
  "filter": {
    "log": true,
    "class": [
      {
        "name": "connection",
        "event": [
          { "name": "connect", "log": false },
          { "name": "disconnect", "log": false }
        ]
      },
      { "name": "general", "log": false }
    ]
  }
}
```

##### 测试事件字段值

要启用基于特定事件字段值的日志记录，请指定`场地`内的项目`日志`指示字段名称及其预期值的项目：

```
{
  "filter": {
    "class": {
    "name": "general",
      "event": {
        "name": "status",
        "log": {
          "field": { "name": "general_command.str", "value": "Query" }
        }
      }
    }
  }
}
```

每个事件都包含特定于事件类的字段，可以从过滤器中访问这些字段以执行自定义过滤。

中的一个事件`联系`类指示会话期间何时发生与连接相关的活动，例如用户连接到服务器或从服务器断开连接。[表 6.36，“连接事件字段”](audit-log-filter-definitions.html#audit-log-connection-event-fields)表示允许的字段`联系`事件。

[](<>)

**表 6.36 连接事件字段**

| 字段名称 | 字段类型 | 描述 |
| ---- | ---- | --- |
| `状态` | 整数 | 活动状态：<br/><br/>0：好的<br/><br/>否则：失败 |
| `连接ID` | 无符号整数 | 连接 ID |
| `用户.str` | 细绳 | 身份验证期间指定的用户名 |
| `用户长度` | 无符号整数 | 用户名长度 |
| `priv_user.str` | 细绳 | 认证用户名（账户用户名） |
| `priv_user.length` | 无符号整数 | 认证用户名长度 |
| `external_user.str` | 细绳 | 外部用户名（第三方认证插件提供） |
| `external_user.length` | 无符号整数 | 外部用户名长度 |
| `proxy_user.str` | 细绳 | 代理用户名 |
| `proxy_user.length` | 无符号整数 | 代理用户名长度 |
| `主机.str` | 细绳 | 连接的用户主机 |
| `主机长度` | 无符号整数 | 连接用户主机长度 |
| `ip.str` | 细绳 | 已连接用户 IP 地址 |
| `ip.length` | 无符号整数 | 连接用户IP地址长度 |
| `数据库.str` | 细绳 | 连接时指定的数据库名称 |
| `数据库长度` | 无符号整数 | 数据库名称长度 |
| `连接类型` | 整数 | 连接类型：<br/><br/>0 或`“：：不明确的”`： 不明确的<br/><br/>1 或`"::tcp/ip"`: TCP/IP<br/><br/>2 或`“：：插座”`： 插座<br/><br/>3 或`"::named_pipe"`: 命名管道<br/><br/>4 或`“::ssl”`: TCP/IP 加密<br/><br/>5 或`"::shared_memory"`: 共享内存 |

这`"::*`xxx`*"`values 是可以给出的符号伪常数，而不是文字数值。它们必须作为字符串引用并且区分大小写。

中的一个事件`一般的`class 指示操作的状态代码及其详细信息。[表 6.37，“一般事件字段”](audit-log-filter-definitions.html#audit-log-general-event-fields)表示允许的字段`一般的`事件。

[](<>)

**表 6.37 常规事件字段**

| 字段名称 | 字段类型 | 描述 |
| ---- | ---- | --- |
| `general_error_code` | 整数 | 活动状态：<br/><br/>0：好的<br/><br/>否则：失败 |
| `general_thread_id` | 无符号整数 | 连接/线程 ID |
| `general_user.str` | 细绳 | 身份验证期间指定的用户名 |
| `general_user.length` | 无符号整数 | 用户名长度 |
| `general_command.str` | 细绳 | 命令名称 |
| `general_command.length` | 无符号整数 | 命令名长度 |
| `general_query.str` | 细绳 | SQL 语句文本 |
| `general_query.length` | 无符号整数 | SQL 语句文本长度 |
| `general_host.str` | 细绳 | 主机名 |
| `general_host.length` | 无符号整数 | 主机名长度 |
| `general_sql_command.str` | 细绳 | SQL 命令类型名称 |
| `general_sql_command.length` | 无符号整数 | SQL 命令类型名称长度 |
| `general_external_user.str` | 细绳 | 外部用户名（第三方认证插件提供） |
| `general_external_user.length` | 无符号整数 | 外部用户名长度 |
| `general_ip.str` | 细绳 | 已连接用户 IP 地址 |
| `general_ip.length` | 无符号整数 | 连接用户IP地址长度 |

`general_command.str`表示命令名：`询问`,`执行`,`放弃`， 要么`更改用户`.

一种`一般的`事件与`general_command.str`字段设置为`询问`要么`执行`包含`general_sql_command.str`设置为指定 SQL 命令类型的值：`alter_db`,`alter_db_upgrade`,`管理员命令`，等等。可用的`general_sql_command.str`values 可以被视为此语句显示的 Performance Schema 工具的最后一个组件：

```
mysql> SELECT NAME FROM performance_schema.setup_instruments
       WHERE NAME LIKE 'statement/sql/%' ORDER BY NAME;
+---------------------------------------+
| NAME                                  |
+---------------------------------------+
| statement/sql/alter_db                |
| statement/sql/alter_db_upgrade        |
| statement/sql/alter_event             |
| statement/sql/alter_function          |
| statement/sql/alter_instance          |
| statement/sql/alter_procedure         |
| statement/sql/alter_server            |
...
```

中的一个事件`表访问`类提供有关对表的特定访问类型的信息。[表 6.38，“表访问事件字段”](audit-log-filter-definitions.html#audit-log-table-access-event-fields)表示允许的字段`表访问`事件。

[](<>)

**表 6.38 表访问事件字段**

| 字段名称 | 字段类型 | 描述 |
| ---- | ---- | --- |
| `连接ID` | 无符号整数 | 事件连接 ID |
| `sql_command_id` | 整数 | SQL 命令 ID |
| `查询.str` | 细绳 | SQL 语句文本 |
| `查询长度` | 无符号整数 | SQL 语句文本长度 |
| `table_database.str` | 细绳 | 与事件关联的数据库名称 |
| `table_database.length` | 无符号整数 | 数据库名称长度 |
| `表名.str` | 细绳 | 与事件关联的表名 |
| `table_name.length` | 无符号整数 | 表名长度 |

以下列表显示了哪些语句产生了哪些表访问事件：

-   `读`事件：

    -   `选择`

    -   `插入...选择`（对于参考的表`选择`条款）

    -   `替换...选择`（对于参考的表`选择`条款）

    -   `更新...在哪里`（对于参考的表`在哪里`条款）

    -   `处理程序...阅读`

-   `删除`事件：

    -   `删除`

    -   `截断表`

-   `插入`事件：

    -   `插入`

    -   `插入...选择`（对于表中引用的`插入`条款）

    -   `代替`

    -   `替换...选择`（对于表中引用的`代替`条款

    -   `加载数据`

    -   `加载 XML`

-   `更新`事件：

    -   `更新`

    -   `更新...在哪里`（对于参考的表`更新`条款）

##### 阻止特定事件的执行

`事件`项目可以包括`中止`指示是否阻止限定事件执行的项目。`中止`允许编写阻止特定 SQL 语句执行的规则。

重要的

理论上，具有足够权限的用户可能会错误地创建一个`中止`审核日志过滤器中的项目，可防止他们自己和其他管理员访问系统。从 MySQL 8.0.28 开始，[`AUDIT_ABORT_EXEMPT`](privileges-provided.html#priv_audit-abort-exempt)特权可用于允许始终执行用户帐户的查询，即使`中止`item 会阻止他们。因此，具有此权限的帐户可用于在审核错误配置后重新获得对系统的访问权限。该查询仍会记录在审核日志中，但不会被拒绝，而是由于特权而被允许。

在 MySQL 8.0.28 或更高版本中创建的帐户[`SYSTEM_USER`](privileges-provided.html#priv_system-user)特权有[`AUDIT_ABORT_EXEMPT`](privileges-provided.html#priv_audit-abort-exempt)创建时自动分配的权限。这[`AUDIT_ABORT_EXEMPT`](privileges-provided.html#priv_audit-abort-exempt)权限也分配给现有帐户[`SYSTEM_USER`](privileges-provided.html#priv_system-user)使用 MySQL 8.0.28 或更高版本执行升级过程时的权限，如果现有帐户没有分配该权限。

这`中止`项目必须出现在`事件`物品。例如：

```
"event": {
  "name": qualifying event subclass names
  "abort": condition
}
```

对于由`姓名`项目`中止`动作是真还是假，取决于*`健康）状况`*评估。如果条件评估为真，则事件被阻止。否则，事件继续执行。

这*`健康）状况`*规范可以很简单`真的`要么`错误的`，或者它可能更复杂，以至于评估取决于事件特征。

此过滤器块[`插入`](insert.html),[`更新`](update.html)， 和[`删除`](delete.html)声明：

```
{
  "filter": {
    "class": {
      "name": "table_access",
      "event": {
        "name": [ "insert", "update", "delete" ],
        "abort": true
      }
    }
  }
}
```

这个更复杂的过滤器会阻止相同的语句，但只针对特定的表（`财务.bank_account`):

```
{
  "filter": {
    "class": {
      "name": "table_access",
      "event": {
        "name": [ "insert", "update", "delete" ],
        "abort": {
          "and": [
            { "field": { "name": "table_database.str", "value": "finances" } },
            { "field": { "name": "table_name.str", "value": "bank_account" } }
          ]
        }
      }
    }
  }
}
```

过滤器匹配和阻止的语句向客户端返回错误：

```
ERROR 1045 (28000): Statement was aborted by an audit log filter
```

并非所有事件都可以被阻止（请参阅[表 6.35，“每个事件类和子类组合的日志和中止特征”](audit-log-filter-definitions.html#audit-log-event-subclass-log-abort)）。对于无法阻止的事件，审核日志会将警告写入错误日志而不是阻止它。

对于尝试定义一个过滤器，其中`中止`项目出现在其他地方而不是`事件`项，发生错误。

##### 逻辑运算符

逻辑运算符 (`和`,`要么`,`不是`) 允许构造复杂的条件，从而能够编写更高级的过滤配置。下列`日志`仅项目日志`一般的`事件与`general_command`具有特定值和长度的字段：

```
{
  "filter": {
    "class": {
      "name": "general",
      "event": {
        "name": "status",
        "log": {
          "or": [
            {
              "and": [
                { "field": { "name": "general_command.str",    "value": "Query" } },
                { "field": { "name": "general_command.length", "value": 5 } }
              ]
            },
            {
              "and": [
                { "field": { "name": "general_command.str",    "value": "Execute" } },
                { "field": { "name": "general_command.length", "value": 7 } }
              ]
            }
          ]
        }
      }
    }
  }
}
```

##### 引用预定义变量

引用一个预定义的变量`日志`条件，使用`多变的`项，它需要`姓名`和`价值`项目并测试命名变量与给定值的相等性：

```
"variable": {
  "name": "variable_name",
  "value": comparison_value
}
```

这是真的，如果*`变量名`*有价值*`比较值`*，否则为假。

例子：

```
{
  "filter": {
    "class": {
      "name": "general",
      "event": {
        "name": "status",
        "log": {
          "variable": {
            "name": "audit_log_connection_policy_value",
            "value": "::none"
          }
        }
      }
    }
  }
}
```

每个预定义变量对应一个系统变量。通过编写一个测试预定义变量的过滤器，您可以通过设置相应的系统变量来修改过滤器操作，而无需重新定义过滤器。例如，通过编写一个过滤器来测试`audit_log_connection_policy_value`预定义变量，您可以通过更改的值来修改过滤器操作[`audit_log_connection_policy`](audit-log-reference.html#sysvar_audit_log_connection_policy)系统变量。

[](<>)

这`审计日志_*`xxx`*_政策`系统变量用于传统模式审计日志（请参阅[第 6.4.5.10 节，“传统模式审核日志过滤”](audit-log-legacy-filtering.html)）。使用基于规则的审计日志过滤，这些变量仍然可见（例如，使用[`显示变量`](show-variables.html))，但是除非您编写包含引用它们的构造的过滤器，否则对它们的更改无效。

以下列表描述了允许的预定义变量`多变的`项目：

-   `audit_log_connection_policy_value`

    这个变量对应的值[`audit_log_connection_policy`](audit-log-reference.html#sysvar_audit_log_connection_policy)系统变量。该值是一个无符号整数。[表 6.39，“审计\_日志\_联系\_政策\_价值观”](audit-log-filter-definitions.html#audit-log-connection-policy-value-values)显示允许的值和相应的[`audit_log_connection_policy`](audit-log-reference.html#sysvar_audit_log_connection_policy)价值观。

    [](<>)

    **表 6.39 审核\_日志\_联系\_政策\_价值观**

    | 价值 | 对应审计\_日志\_联系\_保单价值 |
    | --- | ------------------ |
    | `0`要么`“：：没有”` | `没有` |
    | `1`要么`“::错误”` | `错误` |
    | `2`要么`“：：全部”` | `全部` |

    这`"::*`xxx`*"`values 是可以给出的符号伪常数，而不是文字数值。它们必须作为字符串引用并且区分大小写。

-   `audit_log_policy_value`

    这个变量对应的值[`audit_log_policy`](audit-log-reference.html#sysvar_audit_log_policy)系统变量。该值是一个无符号整数。[表 6.40，“审计\_日志\_政策\_价值观”](audit-log-filter-definitions.html#audit-log-policy-value-values)显示允许的值和相应的[`audit_log_policy`](audit-log-reference.html#sysvar_audit_log_policy)价值观。

    [](<>)

    **表 6.40 审核\_日志\_政策\_价值观**

    | 价值 | 对应审计\_日志\_保单价值 |
    | --- | -------------- |
    | `0`要么`“：：没有”` | `没有` |
    | `1`要么`“::登录”` | `登录` |
    | `2`要么`“：：全部”` | `全部` |
    | `3`要么`“::查询”` | `查询` |

    这`"::*`xxx`*"`values 是可以给出的符号伪常数，而不是文字数值。它们必须作为字符串引用并且区分大小写。

-   `audit_log_statement_policy_value`

    这个变量对应的值[`audit_log_statement_policy`](audit-log-reference.html#sysvar_audit_log_statement_policy)系统变量。该值是一个无符号整数。[表 6.41，“审计\_日志\_陈述\_政策\_价值观”](audit-log-filter-definitions.html#audit-log-statement-policy-value-values)显示允许的值和相应的[`audit_log_statement_policy`](audit-log-reference.html#sysvar_audit_log_statement_policy)价值观。

    [](<>)

    **表 6.41 审核\_日志\_陈述\_政策\_价值观**

    | 价值 | 对应审计\_日志\_陈述\_保单价值 |
    | --- | ------------------ |
    | `0`要么`“：：没有”` | `没有` |
    | `1`要么`“::错误”` | `错误` |
    | `2`要么`“：：全部”` | `全部` |

    这`"::*`xxx`*"`values 是可以给出的符号伪常数，而不是文字数值。它们必须作为字符串引用并且区分大小写。

##### 引用预定义函数

引用一个预定义的函数`日志`条件，使用`功能`项，它需要`姓名`和`参数`分别指定函数名称及其参数的项目：

```
"function": {
  "name": "function_name",
  "args": arguments
}
```

这`姓名`item 应仅指定函数名称，不带括号或参数列表。

这`参数`项目必须满足以下条件：

-   如果函数不带参数，则不`参数`应给出项目。

-   如果函数确实接受参数，则`参数`item 是必需的，并且参数必须按照函数描述中列出的顺序给出。参数可以引用预定义的变量、事件字段或字符串或数字常量。

    如果参数的数量不正确或参数不是函数所需的正确数据类型，则会发生错误。

    例子：


```
{
  "filter": {
    "class": {
      "name": "general",
      "event": {
        "name": "status",
        "log": {
          "function": {
            "name": "find_in_include_list",
            "args": [ { "string": [ { "field": "user.str" },
                                    { "string": "@"},
                                    { "field": "host.str" } ] } ]
          }
        }
      }
    }
  }
}
```

前面的过滤器决定是否记录`一般的`班级`状态`事件取决于当前用户是否在[`audit_log_include_accounts`](audit-log-reference.html#sysvar_audit_log_include_accounts)系统变量。该用户是使用事件中的字段构建的。

以下列表描述了允许的预定义函数`功能`项目：

-   `audit_log_exclude_accounts_is_null()`

    检查是否[`audit_log_exclude_accounts`](audit-log-reference.html#sysvar_audit_log_exclude_accounts)系统变量是`空值`.在定义与旧审计日志实现相对应的过滤器时，此功能会很有帮助。

    论据：

    没有。

-   `audit_log_include_accounts_is_null()`

    检查是否[`audit_log_include_accounts`](audit-log-reference.html#sysvar_audit_log_include_accounts)系统变量是`空值`.在定义与旧审计日志实现相对应的过滤器时，此功能会很有帮助。

    论据：

    没有。

-   `debug_sleep(毫秒)`

    休眠给定的毫秒数。此功能在性能测量期间使用。

    `调试睡眠（）`仅可用于调试版本。

    论据：

    -   *`毫秒`*：一个无符号整数，指定休眠的毫秒数。

-   `find_in_exclude_list（帐户）`

    检查审计日志排除列表中是否存在帐户字符串（[`audit_log_exclude_accounts`](audit-log-reference.html#sysvar_audit_log_exclude_accounts)系统变量）。

    论据：

    -   *`帐户`*：指定用户帐户名称的字符串。

-   `find_in_include_list（帐户）`

    检查审计日志包含列表中是否存在帐户字符串（[`audit_log_include_accounts`](audit-log-reference.html#sysvar_audit_log_include_accounts)系统变量）。

    论据：

    -   *`帐户`*：指定用户帐户名称的字符串。

-   `查询摘要（[str]）`

    根据是否给出参数，此函数具有不同的行为：

    -   没有争论，`查询文摘`返回当前事件中语句文字文本对应的语句摘要值。

    -   带着论据，`查询文摘`返回一个布尔值，指示参数是否等于当前语句摘要。

        论据：

    -   *`字符串`*: 这个参数是可选的。如果给定，它指定要与当前事件中的语句的摘要进行比较的语句摘要。

        例子：

        这`功能`item 不包含任何参数，所以`查询文摘`以字符串形式返回当前语句摘要：

    ```
    "function": {
      "name": "query_digest"
    }
    ```

    这`功能`item 包含一个参数，所以`查询文摘`返回一个布尔值，指示参数是否等于当前语句摘要：

    ```
    "function": {
      "name": "query_digest",
      "args": "SELECT ?"
    }
    ```

    此功能是在 MySQL 8.0.26 中添加的。

-   `string_find（文本，s​​ubstr）`

    检查是否`子串`值包含在`文本`价值。此搜索区分大小写。

    论据：

    -   *`文本`*：要搜索的文本字符串。

    -   *`子串`*: 要搜索的子字符串*`文本`*.

##### 替换事件字段值

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

从 MySQL 8.0.26 开始，审计过滤器定义支持替换某些审计事件字段，以便记录的事件包含替换值而不是原始值。此功能使记录的审计记录能够包含语句摘要而不是文字语句，这对于语句可能会暴露敏感值的 MySQL 部署非常有用。

审计事件中的字段替换是这样工作的：

-   字段替换在审核过滤器定义中指定，因此必须启用审核日志过滤，如中所述[第 6.4.5.7 节，“审核日志过滤”](audit-log-filtering.html).

-   并非所有字段都可以替换。[表 6.42，“可能被替换的事件字段”](audit-log-filter-definitions.html#audit-log-replaceable-event-fields)显示哪些字段在哪些事件类中是可替换的。

    [](<>)

    **表 6.42 可能被替换的事件字段**

    | 事件类 | 字段名称 |
    | --- | ---- |
    | `一般的` | `general_query.str` |
    | `表访问` | `查询.str` |

-   更换是有条件的。过滤器定义中的每个替换规范都包含一个条件，可根据条件结果更改或保持可替换字段不变。

-   如果发生替换，则替换规范使用允许用于该目的的函数来指示替换值。

    作为[表 6.42，“可能被替换的事件字段”](audit-log-filter-definitions.html#audit-log-replaceable-event-fields)显示，目前唯一可替换的字段是那些包含语句文本的字段（发生在`一般的`和`表访问`类）。此外，唯一允许指定替换值的函数是`查询文摘`.这意味着唯一允许的替换操作是用相应的摘要替换语句文字文本。

    因为字段替换发生在早期审计阶段（在过滤期间），所以无论以后编写的日志格式如何（即审计日志插件生成 XML 还是 JSON 输出），都可以选择是写入语句文字文本还是摘要值。

    字段替换可以在不同级别的事件粒度上进行：

-   要对类中的所有事件执行字段替换，请在类级别过滤事件。

-   要在更细粒度的基础上执行替换，请包括其他事件选择项。例如，您可以仅对给定事件类的特定子类执行字段替换，或者仅对字段具有某些特征的事件执行字段替换。

    在过滤器定义中，通过包含`打印`item，语法如下：


```
"print": {
  "field": {
    "name": "field_name",
    "print": condition,
    "replace": replacement_value
  }
}
```

内`打印`项目，它的`场地`item 用这三个项目来表示替换是否以及如何发生：

-   `姓名`：替换（可能）发生的字段。*`字段名`*必须是其中之一[表 6.42，“可能被替换的事件字段”](audit-log-filter-definitions.html#audit-log-replaceable-event-fields).

-   `打印`: 决定是保留原始字段值还是替换它的条件：

    -   如果*`健康）状况`*评估为`真的`，场保持不变。

    -   如果*`健康）状况`*评估为`错误的`，替换发生，使用的值`代替`物品。

        要无条件地替换字段，请指定如下条件：

    ```
    "print": false
    ```

-   `代替`: 使用的替换值`打印`条件评估为`错误的`.指定*`替换值`*用一个`功能`物品。

    例如，此过滤器定义适用于`一般的`类，用它的摘要替换语句文字文本：


```
{
  "filter": {
    "class": {
      "name": "general",
      "print": {
        "field": {
          "name": "general_query.str",
          "print": false,
          "replace": {
            "function": {
              "name": "query_digest"
            }
          }
        }
      }
    }
  }
}
```

前面的过滤器使用这个`打印`项目无条件地替换包含在中的语句文字文本`general_query.str`通过其摘要值：

```
"print": {
  "field": {
    "name": "general_query.str",
    "print": false,
    "replace": {
      "function": {
        "name": "query_digest"
      }
    }
  }
}
```

`打印`项目可以编写不同的方式来实现不同的替换策略。这`代替`刚刚显示的项目使用此指定替换文本`功能`构造返回表示当前语句摘要的字符串：

```
"function": {
  "name": "query_digest"
}
```

这`查询文摘`函数也可以以另一种方式使用，作为返回布尔值的比较器，这使得它可以在`打印`健康）状况。为此，请提供一个指定比较语句摘要的参数：

```
"function": {
  "name": "query_digest",
  "args": "digest"
}
```

在这种情况下，`查询文摘`返回`真的`要么`错误的`取决于当前语句摘要是否与比较摘要相同。使用`查询文摘`这种方式使过滤器定义能够检测与特定摘要匹配的语句。以下构造中的条件仅适用于摘要等于`选择 ？`，因此仅对与摘要不匹配的语句进行替换：

```
"print": {
  "field": {
    "name": "general_query.str",
    "print": {
      "function": {
        "name": "query_digest",
        "args": "SELECT ?"
      }
    },
    "replace": {
      "function": {
        "name": "query_digest"
      }
    }
  }
}
```

要仅对匹配摘要的语句执行替换，请使用`不是`反转条件：

```
"print": {
  "field": {
    "name": "general_query.str",
    "print": {
      "not": {
        "function": {
          "name": "query_digest",
          "args": "SELECT ?"
        }
      }
    },
    "replace": {
      "function": {
        "name": "query_digest"
      }
    }
  }
}
```

假设您希望审计日志仅包含语句摘要而不包含文字语句。要实现这一点，您必须对包含语句文本的所有事件执行替换；也就是说，在`一般的`和`表访问`类。较早的过滤器定义显示了如何无条件地替换语句文本`一般的`事件。做同样的事情`表访问`事件，使用一个类似的过滤器，但将类从`一般的`到`表访问`以及来自的字段名称`general_query.str`到`查询.str`：

```
{
  "filter": {
    "class": {
      "name": "table_access",
      "print": {
        "field": {
          "name": "query.str",
          "print": false,
          "replace": {
            "function": {
              "name": "query_digest"
            }
          }
        }
      }
    }
  }
}
```

结合`一般的`和`表访问`filters 产生一个过滤器，它对所有包含语句文本的事件执行替换：

```
{
  "filter": {
    "class": [
      {
        "name": "general",
        "print": {
          "field": {
            "name": "general_query.str",
            "print": false,
            "replace": {
              "function": {
                "name": "query_digest"
              }
            }
          }
        }
      },
      {
        "name": "table_access",
        "print": {
          "field": {
            "name": "query.str",
            "print": false,
            "replace": {
              "function": {
                "name": "query_digest"
              }
            }
          }
        }
      }
    ]
  }
}
```

要仅对类中的某些事件执行替换，请将项目添加到过滤器中，以更具体地指示何时发生替换。以下过滤器适用于`表访问`类，但仅对`插入`和`更新`事件（离开`读`和`删除`事件不变）：

```
{
  "filter": {
    "class": {
      "name": "table_access",
      "event": {
        "name": [
          "insert",
          "update"
        ],
        "print": {
          "field": {
            "name": "query.str",
            "print": false,
            "replace": {
              "function": {
                "name": "query_digest"
              }
            }
          }
        }
      }
    }
  }
}
```

此过滤器执行替换`一般的`对应于列出的帐户管理语句的类事件（效果是在语句中隐藏凭证和数据值）：

```
{
  "filter": {
    "class": {
      "name": "general",
      "event": {
        "name": "status",
        "print": {
          "field": {
            "name": "general_query.str",
            "print": false,
            "replace": {
              "function": {
                "name": "query_digest"
              }
            }
          }
        },
        "log": {
          "or": [
            {
              "field": {
                "name": "general_sql_command.str",
                "value": "alter_user"
              }
            },
            {
              "field": {
                "name": "general_sql_command.str",
                "value": "alter_user_default_role"
              }
            },
            {
              "field": {
                "name": "general_sql_command.str",
                "value": "create_role"
              }
            },
            {
              "field": {
                "name": "general_sql_command.str",
                "value": "create_user"
              }
            }
          ]
        }
      }
    }
  }
}
```

有关可能的信息`general_sql_command.str`值，见[测试事件字段值](audit-log-filter-definitions.html#audit-log-filtering-event-fields).

##### 更换用户过滤器

在某些情况下，过滤器定义可以动态更改。为此，定义一个`筛选`在现有的配置`筛选`.例如：

```
{
  "filter": {
    "id": "main",
    "class": {
      "name": "table_access",
      "event": {
        "name": [ "update", "delete" ],
        "log": false,
        "filter": {
          "class": {
            "name": "general",
            "event" : { "name": "status",
                        "filter": { "ref": "main" } }
          },
          "activate": {
            "or": [
              { "field": { "name": "table_name.str", "value": "temp_1" } },
              { "field": { "name": "table_name.str", "value": "temp_2" } }
            ]
          }
        }
      }
    }
  }
}
```

一个新的过滤器被激活，当`启用`子过滤器中的项目评估为`真的`.使用`启用`在顶级`筛选`不允许。

新过滤器可以用原来的过滤器更换，方法是使用`参考`子过滤器内的项目以引用原始过滤器`id`.

显示的过滤器操作如下：

-   这`主要的`过滤器等待`表访问`事件，要么`更新`要么`删除`.

-   如果`更新`要么`删除` `表访问`事件发生在`temp_1`要么`temp_2`表中，过滤器被替换为内部过滤器（没有`id`，因为没有必要明确地引用它）。

-   如果发出命令结束的信号 (`一般的` / `状态`事件），一个条目被写入审计日志文件，过滤器被替换为`主要的`筛选。

    过滤器对于记录更新或删除任何内容的语句很有用`temp_1`要么`temp_2`表，例如这个：


```
UPDATE temp_1, temp_3 SET temp_1.a=21, temp_3.a=23;
```

该语句生成多个`表访问`事件，但审核日志文件仅包含`一般的`/`状态`条目。

笔记

任何`id`定义中使用的值仅针对该定义进行评估。它们与价值无关[`audit_log_filter_id`](audit-log-reference.html#sysvar_audit_log_filter_id)系统变量。
