MySQL :: MySQL 9.0 參考手冊 :: 8.4.6 稽核訊息元件

版本 9.0

8.4 目前
8.0

8.0 日文

MySQL 9.0 參考手冊 / ... / 稽核訊息元件

8.4.6 稽核訊息元件

audit_api_message_emit 元件可讓應用程式使用 audit_api_message_emit_udf() 函數，將自己的訊息事件新增至稽核記錄。

audit_api_message_emit 元件會與所有稽核類型外掛程式合作。為了具體說明，範例會使用第 8.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 元件實作的 audit_api_message_emit_udf() 函數。

在使用稽核訊息函數之前，請依照安裝或解除安裝稽核訊息元件中提供的指示，安裝稽核訊息元件。

audit_api_message_emit_udf(component, producer, message[, key, value] ...)
將訊息事件新增至稽核記錄。訊息事件包含呼叫者選擇的元件、產生器和訊息字串，以及選擇性的一組金鑰值組。
此函數張貼的事件會傳送至所有已啟用的稽核類型外掛程式，每個外掛程式都會根據自己的規則處理事件。如果未啟用稽核類型外掛程式，張貼事件不會有任何作用。
引數
- 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 外掛程式（請參閱第 8.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 值。
不支援基於鍵值映射內容的篩選。
如需撰寫篩選規則的相關資訊，請參閱第 8.4.5.7 節，「稽核記錄篩選」。