本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # Amazon RDS for Db2 使用者定義函數參考 下列使用者定義的函數適用於執行 Db2 引擎的 Amazon RDS 資料庫執行個體。 **Topics** + [rdsadmin.get\$1task\$1status](#db2-udf-get-task-status) + [rdsadmin.list\$1databases](#db2-udf-list-databases) + [rdsadmin.list\$1modifiable\$1db\$1params](#db2-udf-list-modi-db-params) ## rdsadmin.get\$1task\$1status 傳回任務的狀態。 ### 語法 ``` db2 "select task_id, task_type, database_name, lifecycle, varchar(bson_to_json(task_input_params), 500) as task_params, cast(task_output as varchar(500)) as task_output from table(rdsadmin.get_task_status(task_id,'database_name','task_type'))" ``` ### Parameters 下列是選用參數。如果您未提供任何參數，則使用者定義的函數會傳回所有資料庫之所有任務的狀態。Amazon RDS 會保留任務歷史記錄 35 天。 *task\$1id* 正在執行的任務之 ID。當您執行任務時，會傳回此 ID。預設：`0`。 *database\$1name* 正在執行任務的資料庫之名稱。 *task\$1type* 要查詢的任務之類型。有效值：`ADD_GROUPS`、`ADD_USER`、`ALTER_BUFFERPOOL`、`ALTER_TABLESPACE`、`CHANGE_PASSWORD`、`COMPLETE_ROLLFORWARD`、`CREATE_BUFFERPOOL`、`CREATE_DATABASE`、`CREATE_ROLE`、`CREATE_TABLESPACE`、`DROP_BUFFERPOOL`、`DROP_DATABASE`、`DROP_TABLESPACE`、`LIST_USERS`、`REMOVE_GROUPS`、`REMOVE_USER`、`RESTORE_DB`、`ROLLFORWARD_DB_LOG`、`ROLLFORWARD_STATUS`、`UPDATE_DB_PARAM`。 ### 使用須知 您可以使用 `rdsadmin.get_task_status` 使用者定義的函數，檢查 Amazon RDS for Db2 的下列任務狀態。此清單並不詳盡。 + 建立、變更或捨棄緩衝集區 + 建立、變更或捨棄資料表空間 + 建立或捨棄資料庫 + 從 Amazon S3 還原資料庫備份 + 從 Amazon S3 轉傳資料庫日誌 ### 範例 下列範例顯示呼叫 `rdsadmin.get_task_status` 時所傳回的資料欄。 ``` db2 "describe select * from table(rdsadmin.get_task_status())" ``` 下列範例列出所有任務的狀態。 ``` db2 "select task_id, task_type, database_name, lifecycle, varchar(bson_to_json(task_input_params), 500) as task_params, cast(task_output as varchar(500)) as task_output from table(rdsadmin.get_task_status(null,null,null))" ``` 下列範例列出特定任務的狀態。 ``` db2 "select task_id, task_type, database_name, varchar(bson_to_json(task_input_params), 500) as task_params from table(rdsadmin.get_task_status(1,null,null))" ``` 下列範例列出特定任務和資料庫的狀態。 ``` db2 "select task_id, task_type, database_name, varchar(bson_to_json(task_input_params), 500) as task_params from table(rdsadmin.get_task_status(2,'SAMPLE',null))" ``` 下列範例列出所有 `ADD_GROUPS` 任務的狀態。 ``` db2 "select task_id, task_type, database_name, varchar(bson_to_json(task_input_params), 500) as task_params from table(rdsadmin.get_task_status(null,null,'add_groups'))" ``` 下列範例列出特定資料庫所有任務的狀態。 ``` db2 "select task_id, task_type, database_name, varchar(bson_to_json(task_input_params), 500) as task_params from table(rdsadmin.get_task_status(null,'testdb', null))" ``` 下列範例會將 JSON 值輸出為資料欄。 ``` db2 "select varchar(r.task_type,25) as task_type, varchar(r.lifecycle,10) as lifecycle, r.created_at, u.* from table(rdsadmin.get_task_status(null,null,'restore_db')) as r, json_table(r.task_input_params, 'strict $' columns(s3_prefix varchar(500) null on empty, s3_bucket_name varchar(500) null on empty) error on error ) as U" ``` ### 回應 `rdsadmin.get_task_status` 使用者定義的函數會傳回下列資料欄： `TASK_ID` 任務的 ID。 `TASK_TYPE` 取決於輸入參數。 + `ADD_GROUPS` – 新增群組。 + `ADD_USER` – 新增使用者。 + `ALTER_BUFFERPOOL` – 修改緩衝集區。 + `ALTER_TABLESPACE` – 修改資料表空間。 + `CHANGE_PASSWORD `– 變更使用者的密碼。 + `COMPLETE_ROLLFORWARD` – 完成 `rdsadmin.rollforward_database` 任務並啟用資料庫。 + `CREATE_BUFFERPOOL` – 建立緩衝集區。 + `CREATE_DATABASE` – 建立資料庫。 + `CREATE_ROLE` – 為使用者建立 Db2 角色。 + `CREATE_TABLESPACE` – 建立資料表空間。 + `DROP_BUFFERPOOL` – 捨棄緩衝集區。 + `DROP_DATABASE` – 捨棄資料庫。 + `DROP_TABLESPACE` – 捨棄資料表空間。 + `LIST_USERS` – 列出所有使用者。 + `REMOVE_GROUPS` – 移除群組。 + `REMOVE_USER` – 移除使用者。 + `RESTORE_DB` – 還原完整資料庫。 + `ROLLFORWARD_DB_LOG` – 在資料庫日誌上執行 `rdsadmin.rollforward_database` 任務。 + `ROLLFORWARD_STATUS `– 傳回 `rdsadmin.rollforward_database` 任務的狀態。 + `UPDATE_DB_PARAM` – 更新資料參數。 `DATABASE_NAME` 與任務相關聯之資料庫的名稱。 `COMPLETED_WORK_BYTES` 任務還原的位元組數。 `DURATION_MINS` 完成任務所需的時間。 `LIFECYCLE` 任務的狀態。可能的狀態： + `CREATED` – 將任務提交至 Amazon RDS 後，Amazon RDS 會將狀態設定為 `CREATED`。 + `IN_PROGRESS` – 任務開始之後，Amazon RDS 會將狀態設定為 `IN_PROGRESS`。最多可能需要 5 分鐘，狀態才會從 `CREATED` 變成 `IN_PROGRESS`。 + `SUCCESS` – 任務完成之後，Amazon RDS 會將狀態設定為 `SUCCESS`。 + `ERROR` – 如果還原任務失敗，則 Amazon RDS 會將狀態設定為 `ERROR`。如需關於錯誤的詳細資訊，請參閱 `TASK_OUPUT`。 `CREATED_BY` 建立命令的 `authid`。 `CREATED_AT` 建立任務的日期和時間。 `LAST_UPDATED_AT` 任務最後更新的日期和時間。 `TASK_INPUT_PARAMS` 參數會根據任務類型而有所不同。所有輸入參數都會以 JSON 物件表示。例如，`RESTORE_DB` 任務的 JSON 金鑰如下： + `DBNAME` + `RESTORE_TIMESTAMP` + `S3_BUCKET_NAME` + `S3_PREFIX` `TASK_OUTPUT` 任務的其他資訊。如果在原生還原期間發生錯誤，此欄會包含錯誤的相關資訊。 ### 回應範例 下列回應範例顯示已成功建立名為 `TESTJP` 的資料庫。如需詳細資訊，請參閱 [rdsadmin.create\$1database](db2-sp-managing-databases.md#db2-sp-create-database) 預存程序。 ``` `1 SUCCESS CREATE_DATABASE RDSDB 2023-10-24-18.32.44.962689 2023-10-24-18.34.50.038523 1 TESTJP { "CODESET" : "IBM-437", "TERRITORY" : "JP", "COLLATION" : "SYSTEM", "AUTOCONFIGURE_CMD" : "", "PAGESIZE" : 4096 } 2023-10-24-18.33.30.079048 Task execution has started. 2023-10-24-18.34.50.038523 Task execution has completed successfully`. ``` 下列回應範例說明捨棄資料庫失敗的原因。如需詳細資訊，請參閱 [rdsadmin.drop\$1database](db2-sp-managing-databases.md#db2-sp-drop-database) 預存程序。 ``` 1 ERROR DROP_DATABASE RDSDB 2023-10-10-16.33.03.744122 2023-10-10-16.33.30.143797 - 2023-10-10-16.33.30.098857 Task execution has started. 2023-10-10-16.33.30.143797 Caught exception during executing task id 1, Aborting task. Reason Dropping database created via rds CreateDBInstance api is not allowed. Only database created using rdsadmin.create_database can be dropped ``` 下列回應範例顯示成功還原資料庫。如需詳細資訊，請參閱 [rdsadmin.restore\$1database](db2-sp-managing-databases.md#db2-sp-restore-database) 預存程序。 ``` 1 RESTORE_DB SAMPLE SUCCESS { "S3_BUCKET_NAME" : "amzn-s3-demo-bucket", "S3_PREFIX" : "SAMPLE.0.rdsdb3.DBPART000.20230413183211.001", "RESTORE_TIMESTAMP" : "20230413183211", "BACKUP_TYPE" : "offline" } 2023-11-06-18.31.03.115795 Task execution has started. 2023-11-06-18.31.04.300231 Preparing to download 2023-11-06-18.31.08.368827 Download complete. Starting Restore 2023-11-06-18.33.13.891356 Task Completed Successfully ``` ## rdsadmin.list\$1databases 傳回在 RDS for Db2 資料庫執行個體上執行的所有資料庫之清單。 ### 語法 ``` db2 "select * from table(rdsadmin.list_databases())" ``` ### 使用須知 此使用者定義的函數不會指定資料庫是處於啟用或停用狀態。 如果您在清單中看不到資料庫，請呼叫 [rdsadmin.get\$1task\$1status](#db2-udf-get-task-status) 使用者定義的函數，並尋找錯誤訊息。 ### 回應 `rdsadmin.list_databases` 使用者定義的函數會傳回下列資料欄： `DATABASE_NAME` 資料庫的名稱。 `CREATE_TIME` 建立資料庫的時間和日期。 `DATABASE_UNIQUE_ID` RDS 建立 GUID 以唯一識別 Db2 資料庫。 `ARCHIVE_LOG_RETENTION_HOUR` 保留封存日誌檔案的時數。 `ARCHIVE_LOG_COPY` 顯示資料庫的功能是 ENABLED 還是 DISABLED。 `ARCHIVE_LOG_LAST_UPLOAD_FILE ` 指出上次上傳至 S3 的封存日誌。 `ARCHIVE_LOG_LAST_UPLOAD_FILE_TIME` 指出封存日誌檔案的時間。 `ARCHIVE_LOG_COPY_STATUS` 顯示封存日誌副本的狀態。 上傳 ：表示封存日誌檔案正在上傳到 S3。 CONFIGURATION\$1ERROR：表示有組態問題需要您注意。 若要檢視詳細錯誤，請參閱 Db 執行個體的 RDS 事件訊息。您可以在檢視 [Amazon RDS 事件中檢視事件訊息。](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_ListEvents.html) ### 回應範例 下列回應範例顯示資料庫的清單以及建立資料庫的時間。`rdsadmin` 是 Amazon RDS 管理並一律顯示在輸出中的資料庫。 ``` DATABASE_NAME CREATE_TIME DATABASE_UNIQUE_ID ARCHIVE_LOG_RETENTION_HOURS ARCHIVE_LOG_COPY ARCHIVE_LOG_LAST_UPLOAD_FILE ARCHIVE_LOG_LAST_UPLOAD_FILE_TIME ARCHIVE_LOG_COPY_STATUS --------------- -------------------------- -------------------------------------------------- --------------------------- ---------------- ---------------------------- --------------------------------- ------------------------------ RDSADMIN 2026-01-06-02.03.42.569069 RDSADMIN 0 DISABLED - - - FOO 2026-01-06-02.13.42.885650 F0D81C7E-7213-4565-B376-4F33FCF420E3 0 ENABLED S0006536.LOG 2026-01-28-19.15.10.000000 UPLOADING CODEP 2026-01-14-19.42.42.508476 106EEF95-6E30-4FFF-85AE-B044352DF095 0 DISABLED - - - ... ``` ## rdsadmin.list\$1modifiable\$1db\$1params 傳回所有可修改資料庫組態參數的清單。 ### 語法 ``` db2 "select * from table(rdsadmin.list_modifiable_db_params())" ``` ### 使用須知 此使用者定義的函數會顯示可修改資料庫參數的所選清單。您可以使用預存程序 來更新這些參數[rdsadmin.update\$1db\$1param](db2-sp-managing-databases.md#db2-sp-update-db-param)。 此清單中未包含的任何資料庫參數都受到限制，無法修改。 ### 回應 `rdsadmin.list_modifiable_db_params` 使用者定義的函數會傳回下列資料欄： `PARAM_NAME` 可修改的參數名稱。 `DEFAULT_VALUE` 資料庫建立時的預設參數值。 `RESTART_REQUIRED` 如果需要資料庫資源回收，則不需要。 Y = 是，需要重新啟動資料庫。 N = 否，不需要重新啟動資料庫。 ### 回應範例 以下是預期輸出的範例 （截斷） 清單。 ``` PARAM_NAME DEFAULT_VALUE RESTART_REQUIRED ---------------------- ------------- ---------------- ACT_SORTMEM_LIMIT NONE N ARCHRETRYDELAY 20 N AUTHN_CACHE_DURATION 3 N AUTHN_CACHE_USERS 0 N AUTO_CG_STATS OFF N ... ```