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の名前とDBMS_DATA_TOOLS_JOBサブプログラムの説明

サブプログラム	説明
ジョブの作成プロシージャ	このプロシージャは、新規ジョブを作成します。
ジョブの削除プロシージャ	スケジューラからジョブを削除します。
ジョブ・プロシージャの名前変更	目的の名前でジョブの名前を変更します。
ジョブの更新手順	既存のジョブの属性を変更します。
プロシージャの実行	定義したスケジュールに関係なく、ジョブをただちに実行します。
ジョブの停止プロシージャ	実行中のジョブを停止します。これにより、ジョブが正常終了し、必要に応じて強制的に停止されます。

セキュリティーに関する考慮事項

シークレット、ベアラー・トークン、パスワード、秘密キー、署名付きURL、その他の資格証明などの機密データを、ジョブ・ステップURL、リクエスト本文またはレポート構成に直接配置しないでください。これらの値は、ジョブ定義とともに格納し、後で取得できます。認証には、データベース資格証明または名前付き資格証明を使用します。

CREATE_JOBプロシージャ

このプロシージャは、1つのジョブを作成します。ジョブを有効に設定して使用可能にすると、Schedulerによりスケジュールに従って自動的にジョブが実行されます。ジョブの作成時使用禁止に設定すると、ジョブ使用可能機能を使用してジョブを使用可能にするまで、ジョブは実行されません。

構文

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プロシージャのパラメータ

パラメータ	説明
ジョブ名	ジョブに割り当てる名前。`job_name`を指定しない場合、エラーが発生します。
説明	これは、ジョブに設定された追加情報を参照します。
ステップ	これは、Data Studioツールが実行する様々なタスクで、ジョブで構成されます。ステップはJSON配列です。各配列要素はJSONオブジェクトです。すべてのオブジェクトに適用されるJSON要素を次に示します: `type` - string。実行されるステップのタイプ(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`をNULLのままにした場合、ジョブは使用可能になるとただちに実行されるようにスケジュールされます。カレンダ式を使用して繰返し間隔を指定する繰返しジョブの場合は、`start_date`は参照日として使用されます。ジョブが実行される最初の日時は、現在の日時以降で最初にカレンダ式に一致した日時になります。 Schedulerでは、ジョブが正確な時間に実行されることを保証しません。これは、システムがオーバーロードしてリソースが使用できない場合があるためです。
繰返し間隔	この属性は、ウィンドウを繰り返す間隔を指定します。これは、Schedulerのカレンダ構文を使用して表されます。詳細は、「カレンダ構文」を参照してください。 PL/SQL式を使用して、ウィンドウの反復間隔を指定することはできません。指定した式は、ウィンドウの次回のオープンを決定するために評価されます。`repeat_interval`を指定しない場合、ウィンドウは指定した開始日に1回だけオープンされます。
終了日	この属性は、ジョブの期限が切れる日時(これ以降にジョブは実行されなくなります)を指定します。 `end_date`の値は、`start_date`の値よりも大きい必要があります。`end_date`が`start_date`より前である場合、エラーが生成されます。`end_date`が`start_date`と同じである場合、ジョブは実行されず、エラーは生成されません。 `end_date`に値を指定しない場合、`stop job`を指定しないかぎり、ジョブは永久に繰り返されます。
ジョブ・クラス	このジョブに関連付けるクラス。
使用可能	ジョブを使用可能で作成するかどうかを指定します。`TRUE`または`FALSE`を設定できます。デフォルトでは`FALSE`に設定されるため、ジョブは使用禁止で作成されます。使用禁止ジョブとは、ジョブに関するメタデータが取得され、ジョブはデータベース・オブジェクトとして存在することを意味しています。ただし、Schedulerはこのジョブを無視し、ジョブ・コーディネータは処理対象としてジョブを取得しません。ジョブ・コーディネータがジョブを処理できるようにするには、ジョブが使用可能である必要があります。ジョブを有効にするには、`Enable Job`アイコンを選択します。
レポート	この属性は、ジョブ機能の「レポート」ボタンを使用してジョブ実行の詳細を指定します。これは、`dbms_live_feed`のレポート引数に似たJSONオブジェクトです。次の要素を持つことができます。 `completed`: ジョブの完了時に通知するターゲット。 `errors`: ジョブの一部のステップでエラーが発生したときに通知するターゲット。 `failed`: ジョブにステップのコンテキスト外で致命的エラーが発生したときに通知するターゲット。 `long`: ジョブが長時間実行されたときに通知するターゲット。これらの4つの要素はそれぞれ、`smtp`要素にEメール・アドレスの配列を指定するか、`slack`要素にスラック・チャネルを指定できます。`long`要素には、`max_runtime_seconds`要素を指定できます。この要素によって、`long`が過剰に実行されたとみなされるまでにジョブを実行する必要がある期間が決まります。注意: レポート構成に機密データを含めないでください。

DELETE_JOBプロシージャ

このプロシージャは、ジョブを削除します。

構文

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

DELETE_JOBプロシージャのパラメータ

表22-4 DELETE_JOBプロシージャのパラメータ

パラメータ	説明
ジョブ名	ジョブに割り当てる名前。`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プロシージャのパラメータ

パラメータ	説明
古いジョブ名	既存のジョブの名前。
新規ジョブ名	新しいジョブの名前です。
所有者	これは、ジョブが作成されるスキーマです。

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プロシージャのパラメータ

パラメータ	説明
ジョブ名	更新するジョブの名前。
所有者	これは、ジョブが更新されるスキーマです。
説明	適用する更新済の説明。
ステップ	更新する新規ステップ。注意: 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プロシージャのパラメータ

パラメータ	説明
ジョブ名	ジョブ名またはエントリのカンマ区切りリスト(それぞれが既存のジョブ名であり、オプションでスキーマ名およびドット区切りを接頭辞として使用できます)。複数の接続先ジョブを指定すると、ジョブはすべての接続先で実行されます。この場合、`use_current_session`引数は`FALSE`である必要があります。
所有者	ジョブが実行されるスキーマです。
現在のセッションを使用	プロシージャを起動したセッションで、ジョブを実行するかどうかを指定します。 `use_current_session`を`TRUE`に設定した場合は、次のようになります。コマンドラインでジョブをテストして、起こりうるエラーを確認できます。 `RUN`は、通常のスケジュール・ジョブと並行して実行できます。 `use_current_session`を`FALSE`に設定した場合は、次のようになります。エラー情報を確認するため、ジョブ・ログをチェックする必要があります。 `scheduler_jobs`のすべての関連フィールドが更新されます。通常のスケジュール・ジョブを実行中に、`RUN`を実行すると失敗します。
オプション

STOP_JOBプロシージャ

このプロシージャは、現在実行中のジョブ、またはジョブ・クラス内のすべてのジョブを停止します。

ジョブの停止後、1回かぎりのジョブのSTATEはSTOPPEDに設定され、繰返しジョブのSTATEは、ジョブの次の実行がスケジュールされているかどうかによって、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プロシージャのパラメータ

パラメータ説明

ジョブ名

パラメータ	説明
ジョブ名	停止するジョブの名前。既存のジョブの名前で、オプションでスキーマ名およびドット区切りを接頭辞に付加されます。
所有者	ジョブを停止するスキーマです。
Force	`force`を`FALSE`に設定した場合、Schedulerは割込み機能を使用してジョブの停止を試みます。この方法では制御をスレーブ・プロセスに戻して、停止するジョブ・キュー内のジョブのステータスをこのプロセスで更新できます。更新に失敗した場合は、エラーが戻されます。 `force`を`TRUE`に設定した場合、Schedulerはただちにジョブ・スレーブを終了します。Oracleでは、`force`を`FALSE`に設定した`STOP_JOB`プロシージャに失敗した場合のみ、forceを`TRUE`に設定して`STOP_JOB`プロシージャを使用することをお薦めします。 `force`オプションを使用するには、`MANAGE SCHEDULER`システム権限が必要です。

停止するジョブの名前。既存のジョブの名前で、オプションでスキーマ名およびドット区切りを接頭辞に付加されます。

所有者

ジョブを停止するスキーマです。

Force

forceをFALSEに設定した場合、Schedulerは割込み機能を使用してジョブの停止を試みます。この方法では制御をスレーブ・プロセスに戻して、停止するジョブ・キュー内のジョブのステータスをこのプロセスで更新できます。更新に失敗した場合は、エラーが戻されます。

forceをTRUEに設定した場合、Schedulerはただちにジョブ・スレーブを終了します。Oracleでは、forceをFALSEに設定したSTOP_JOBプロシージャに失敗した場合のみ、forceをTRUEに設定してSTOP_JOBプロシージャを使用することをお薦めします。

forceオプションを使用するには、MANAGE SCHEDULERシステム権限が必要です。

親トピック: DBMS_DATA_TOOLS_JOBSパッケージ・リファレンス