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

版本 8.4

9.0
8.0

8.0 日文

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

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 篩選規則中參照此類事件，請使用 class 元素，其 name 值為 message。例如
```
{
  "filter": {
    "class": {
      "name": "message"
    }
  }
}
```
如有需要區分使用者產生和內部產生的訊息事件，請根據 user 或 internal 測試 subclass 值。
不支援根據鍵值對應的內容進行篩選。
有關編寫篩選規則的資訊，請參閱第 8.4.5.7 節「稽核日誌篩選」。