DBMS_DATA_TOOLS_JOBS 套裝程式參照

本章提供您在 Data Studio 中搭配「工作」功能使用之套裝程式的相關資訊。「DBMS_DATA_TOOLS_JOBS 子程式摘要」主題也涵蓋 DBMS_DATA_TOOLS_JOBS 套裝程式中包含的程序。

主題：

DBMS_DATA_TOOLS_JOB 子程式摘要

DBMS_DATA_TOOLS_JOB 程序

DBMS_DATA_TOOLS_JOB 子程式摘要
DBMS_DATA_TOOLS_JOB 套裝程式提供排程函數和程序的集合，您可以搭配 Data Studio 工具套件中的「工作」功能使用。

父項主題：工作功能

DBMS_DATA_TOOLS_JOB 子程式摘要

DBMS_DATA_TOOLS_JOB 套裝程式提供與 Data Studio 工具套件中的「工作」功能搭配使用的排程函數和程序集合。

DBMS_DATA_TOOLS_JOB 套裝程式子程式

下表列出 DBMS_DATA_TOOLS_JOB 子程式並簡短說明它們。

表 22-2 DBMS_DATA_TOOLS_JOB 子程式的名稱與描述

子程式	描述
建立工作程序	此程序會建立新工作。
刪除工作程序	從排程器刪除工作。
重新命名工作程序	以想要的名稱重新命名工作。
更新工作程序	修改現有工作的屬性。
執行程序	無論您定義的排程為何，都會立即執行工作。
停止工作程序	停止執行中的工作。這會正常終止工作，必要時會強制停止工作。

安全性考量

請勿將機密資料 (例如加密密碼、持有者記號、密碼、私密金鑰、簽署的 URL 或其他證明資料) 直接放置在工作步驟 URL、要求主體或報告組態中。這些值可以與工作定義一起儲存，稍後再擷取。使用資料庫證明資料或指定的證明資料進行認證。

CREATE_JOB 程序

此程序會建立單一工作。如果您透過將啟用的屬性設為 TRUE 來建立工作，排程器就會根據工作的排程自動執行該工作。如果停用建立工作，則必須等到您使用「啟用工作」功能啟用工作後，才會執行該工作。

語法

dbms_data_tools_job.create_job(
                       job_name        in varchar2,
                       description     in varchar2,
                       steps           in clob,
                       owner           in varchar2 default null,
                       start_date      IN TIMESTAMP WITH TIME ZONE DEFAULT NULL,
                       repeat_interval IN VARCHAR2                 DEFAULT NULL,
                       end_date        IN TIMESTAMP WITH TIME ZONE DEFAULT NULL,
                       job_class       IN VARCHAR2                 DEFAULT NULL,
                       enabled         IN BOOLEAN                  DEFAULT FALSE,
                       reporting       in clob default null);

CREATE_JOB 程序參數

表格 22-3 CREATE_JOB 程序參數

Parameter - 參數	描述
工作名稱	要指定給工作的名稱。如果未指定 `job_name`，則會產生錯誤。
描述	這表示為職務設定的其他資訊。
步驟	這是指 Data Studio 工具執行由工作組成的各種工作。步驟為 JSON 陣列。每個陣列元素都是一個 JSON 物件。以下是適用於所有物件的 JSON 元素： `type` - 字串，宣告執行的步驟類型：data_load、smart_table、procedure、http。 `on_errors`- 字串 `stop`：如果發生錯誤，則會停止工作並發出錯誤。 `continue`：記錄錯誤，但處理會繼續下一個工作步驟。 `step_name` - 要顯示在日誌中的步驟描述性名稱每個物件類型都有一些額外的元素，視類型而定。 `data_load`: `data_load_name` - (必要) 要執行之先前建立的資料載入名稱 `smart_table`: `recipe_name` - (必要) 要執行之先前建立之智慧表格處方的名稱。 `url` - 要連線的 (必要) REST URL。 `method` - GET (預設)、POST、PUT、DELETE 或其他 HTTP 動詞 `procedure`： `procedure` - 要執行的程序名稱 (必要)。它可以是綱要合格的，也可以是裸機程序或套裝程式方法。 `arguments` - 要提供給程序的字串、數字或布林引數陣列。警示：對於 HTTP 步驟，請勿將機密資料放在 URL 或要求主體中。使用資料庫證明資料或指定的證明資料進行認證。
擁有者	它是建立工作的綱要。如果您在未指定綱要的情況下建立工作，擁有者將會是執行 `CREATE_JOB` 程序的使用者。
開始日期	此屬性指定此工作排定開始的第一個日期和時間。如果 `start_date` 和 `repeat_interval` 留為空值，則工作會排定在工作啟用後立即執行。對於使用行事曆表示式來指定重複間隔的重複工作，會使用 `start_date` 作為參照日期。第一次執行工作是目前日期與時間當天或之後之行事曆表示式的第一個相符項目。 Scheduler 無法保證工作會在確切的時間執行，因為系統可能會超載，因此資源無法使用。
重複間隔	此屬性指定視窗重複的頻率。它是使用 Scheduler 行事曆語法來表示的。如需詳細資訊，請參閱行事曆語法。 PL/SQL 表示式無法用來指定時段的重複間隔。系統會評估指定的表示式，以決定下次開啟視窗的時間。如果未指定 `repeat_interval`，則視窗只會在指定的開始日期開啟一次。
結束日期	此屬性指定工作到期且不再執行的日期與時間。 `end_date` 的值必須晚於 `start_date` 的值。如果 `end_date` 小於 `start_date`，則會產生錯誤。如果 `end_date` 與 `start_date` 相同，則不會執行工作，也不會產生任何錯誤。如果未指定 `end_date` 的值，除非您指定 `stop job`，否則工作會永久重複。
工作類別	與此工作關聯的類別。
啟用	此屬性指定是否啟用建立工作。可能的設定值為 `TRUE` 或 `FALSE`。依照預設，此屬性設為 `FALSE`，因此會將工作建立為停用。停用的工作表示已擷取與工作相關的描述資料，且該工作以資料庫物件形式存在。不過，「排程器」會忽略工作，而且工作協調器不會選擇該工作進行處理。若要讓工作協調者處理工作，必須啟用工作。您可以選取 `Enable Job` 圖示來啟用工作。
報告	此屬性透過工作功能中的報表按鈕指定工作執行詳細資訊。這是與 `dbms_live_feed` 報表引數類似的 JSON 物件。它可以有下列元素： `completed`：工作完成時要通知的目標。 `errors`：當某個工作步驟發生錯誤時要通知的目標。 `failed`：當工作在步驟相關資訊環境外發生嚴重錯誤時，要通知的目標。 `long`：工作執行時間長的通知目標。這四個元素中的每一個都可以指定 `slack` 元素中 `smtp` 元素或斜線通道的電子郵件地址陣列。`long` 元素可以有 `max_runtime_seconds` 元素，可決定工作在被視為執行太多 `long` 之前必須執行多久的時間。警示：請勿在報表組態中包含機密資料。

刪除工作程序

此程序會刪除工作。

語法

dbms_data_tools_job.delete_job(
                     job_name in varchar2, 
                     owner    in varchar2 default null);

DELETE_JOB 程序參數

表格 22-4 DELETE_JOB 程序參數

Parameter - 參數	描述
工作名稱	要指定給工作的名稱。如果未指定 `job_name`，則會產生錯誤。
擁有者	它是建立工作的綱要。如果您在未指定綱要的情況下建立工作，擁有者將會是執行 `CREATE_JOB` 程序的使用者。

RENAME_JOB 程序

此程序會重新命名工作。

語法

dbms_data_tools_job.rename_job(
                       old_job_name in varchar2,
                       new_job_name in varchar2,
                       owner        in varchar2 default null);

RENAME_JOB 程序參數

表格 22-5 RENAME_JOB 程序參數

Parameter - 參數	描述
舊工作名稱	現有工作的名稱。
新工作名稱	新職務的名稱。
擁有者	它是建立工作的綱要。

UPDATE_JOB 程序

此程序會更新任何現有的工作屬性。

語法

dbms_data_tools_job.update_job(
                       job_name        IN VARCHAR2,
                       owner           IN VARCHAR2 DEFAULT NULL,
                       description     IN VARCHAR2 DEFAULT NULL,
                       steps           IN clob DEFAULT NULL,
                       start_date      IN TIMESTAMP WITH TIME ZONE DEFAULT NULL,
                       repeat_interval IN VARCHAR2                 DEFAULT NULL,
                       end_date        IN TIMESTAMP WITH TIME ZONE DEFAULT NULL,
                       job_class       IN VARCHAR2                 DEFAULT NULL,
                       enabled         IN BOOLEAN                  DEFAULT NULL,
                       reporting       IN clob DEFAULT NULL);

UPDATE_JOB 程序參數

表格 22-6 UPDATE_JOB 程序參數

Parameter - 參數	描述
工作名稱	要更新之工作的名稱。
擁有者	它是要更新工作的綱要。
描述	要套用的更新描述。
步驟	要更新的新步驟。警示：對於 HTTP 步驟，請勿將機密資料放在 URL 或要求主體中。使用資料庫證明資料或指定的證明資料進行認證。
開始日期	新的起始日期。
重複間隔	更新的重複間隔。
結束日期	更新的結束日期。
工作類別	更新的工作類別。
啟用	可以啟用或停用此功能。
報告	更新的報表屬性。警示：請勿在報表組態中包含機密資料。

執行程序

此程序會立即執行工作。

如果工作已啟用，則 Scheduler 會自動執行。您不需要呼叫 RUN_JOB，即可根據工作的排程執行工作。使用 RUN_JOB 可在正常排程之外執行工作。

語法

dbms_data_tools_job.run(
                job_name            in varchar2,
                owner               in varchar2 default null,
                use_current_session in number   default null,
                options             in clob     default null);

RUN 程序參數

表格 22-7 RUN 程序參數

Parameter - 參數	描述
工作名稱	工作名稱或以逗號區隔的項目清單，其中每個項目都是現有工作的名稱，可選擇在綱要名稱和點區隔符號之前。如果您指定多重目的地工作，該工作會在所有目的地上執行。在此情況下，`use_current_session` 引數必須是 `FALSE`。
擁有者	它是執行工作的綱要。
使用目前的使用階段	這指定工作執行是否應發生在呼叫程序的來源階段作業中。將 `use_current_session` 設為 `TRUE` 時：您可以測試工作，並在命令行中查看任何可能的錯誤。 `RUN` 可與定期排定的工作執行平行執行。當 `use_current_session` 設定為 `FALSE` 時：您必須檢查工作日誌以尋找錯誤資訊。 `scheduler_jobs` 中的所有相關欄位都會更新。如果定期排定的工作正在執行中，`RUN` 就會失敗。
選項

STOP_JOB 程序

此程序會停止目前執行中的工作或工作類別中的所有工作。

停止工作之後，一次性工作的狀態會設為 STOPPED，而重複工作的狀態則會設為 SCHEDULED 或 COMPLETED (視是否排定下一個工作執行而定)。

語法

dbms_data_tools_job.stop_job(
                     job_name in varchar2,
                     owner    in varchar2 default null,
                     force    in boolean  default false);

STOP_JOB 程序參數

表格 22-8 STOP_JOB 程序參數

Parameter - 參數描述

工作名稱

Parameter - 參數	描述
工作名稱	要停止的工作名稱。它是現有工作的名稱，選擇性地在綱要名稱和點分隔符號之前。
擁有者	它是停止工作的綱要。
強制	如果 `force` 設為 `FALSE`，則「排程器」會嘗試使用中斷機制正常停止工作。此方法讓控制權回到從屬處理作業，這可以將工作佇列中的工作狀態更新為已停止。如果失敗，則會傳回錯誤。如果 `force` 設為 `TRUE`，則「排程器」會立即終止工作僕站。Oracle 建議，只有將 `force` 設為 `FALSE` 的 `STOP_JOB` 失敗之後，才使用強制設為 `TRUE` 的 `STOP_JOB`。若要使用 `force` 選項，必須要有 `MANAGE SCHEDULER` 系統權限。

要停止的工作名稱。它是現有工作的名稱，選擇性地在綱要名稱和點分隔符號之前。

擁有者

它是停止工作的綱要。

強制

如果 force 設為 FALSE，則「排程器」會嘗試使用中斷機制正常停止工作。此方法讓控制權回到從屬處理作業，這可以將工作佇列中的工作狀態更新為已停止。如果失敗，則會傳回錯誤。

如果 force 設為 TRUE，則「排程器」會立即終止工作僕站。Oracle 建議，只有將 force 設為 FALSE 的 STOP_JOB 失敗之後，才使用強制設為 TRUE 的 STOP_JOB。

若要使用 force 選項，必須要有 MANAGE SCHEDULER 系統權限。

父項主題：DBMS_DATA_TOOLS_JOBS 套裝程式參照