6.4.6 監査メッセージコンポーネント

MySQL 8.0.14 では、audit_api_message_emit コンポーネントを使用して、audit_api_message_emit_udf() ユーザー定義関数を使用して独自のメッセージイベントを監査ログに追加できます。

audit_api_message_emit コンポーネントは、監査タイプのすべてのプラグインと連携します。簡潔にするために、例ではセクション6.4.5「MySQL Enterprise Audit」で説明されている 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() ユーザー定義関数 (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 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 フィルタリングルールでこのようなイベントを参照するには、name 値が message の class 要素を使用します。例:
```
{
  "filter": {
    "class": {
      "name": "message"
    }
  }
}
```
ユーザー生成メッセージイベントと内部生成メッセージイベントを区別する必要がある場合は、user または internal に対して subclass 値をテストします。
キーと値のマップの内容に基づくフィルタリングはサポートされていません。
フィルタリングルールの作成の詳細は、セクション6.4.5.7「監査ログのフィルタリング」を参照してください。