Oracle Cloud Infrastructureドキュメント

スケジューラ・ジョブのユーザー定義通知ハンドラ

データベース・スケジューラには、定期的に実行中または自動化されたジョブのステータスを追跡するための電子メール通知メカニズムが用意されています。これに加えて、データベース・スケジューラでは、ユーザー定義のPL/SQLスケジューラ・ジョブ通知ハンドラ・プロシージャもサポートされます。

スケジューラ・ジョブ通知ハンドラ・プロシージャを追加すると、Autonomous AI Databaseで実行されているスケジュール済または自動化されたジョブをモニターできます。

スケジューラ・ジョブのユーザー定義通知ハンドラについて

データベース・スケジューラでは、Autonomous AI Databaseインスタンスでのスケジューラ・ジョブのモニタリングを改善するために、カスタム・コードを使用してHTTPまたはRESTエンドポイントをコールできるジョブ通知ハンドラ・プロシージャがサポートされています。

ハンドラ・プロシージャは、ジョブ所有者の名前、クラス名、イベント・タイプ、JSON形式のタイムスタンプなど、ジョブに関するすべての関連情報を受信します。この情報に基づいて、ハンドラ・プロシージャは必要なアクションを実行します。

Oracle Schedulerの詳細は、DBMS_SCHEDULERを参照してください。

スケジューラ・ジョブのユーザー定義通知ハンドラは、次のステップで構成されます。

ジョブ通知ハンドラの作成プロシージャ

ジョブ通知ハンドラを作成するステップを提供します。

  1. 資格証明オブジェクトを作成します。

    詳細は、「CREATE_CREDENTIALプロシージャ」を参照してください。

    詳細は、スケジューラ・ジョブの資格証明の指定を参照してください。

  2. ジョブ通知ハンドラを作成します。

    Slackチャネルにメッセージを送信するジョブ通知ハンドラ・プロシージャを作成する例:

    CREATE OR REPLACE PROCEDURE ADMIN.SEND_NOTIFICATION(data_in CLOB) AS
BEGIN
  DBMS_CLOUD_NOTIFICATION.SEND_MESSAGE (
    provider          => 'slack',
    credential_name   => 'SLACK_CRED',
    message           => data_in,
    params            => JSON_OBJECT('channel' value 'adw-job-nfy');
end;
/

    この例では、SEND_NOTIFICATIONプロシージャを作成します。

    このユーザー定義プロシージャは、指定された入力データをメッセージとして指定したSlackチャネルに送信します。

    詳細は、Autonomous AI DatabaseからのSlack通知の送信を参照してください。

    詳細は、SEND_MESSAGEプロシージャを参照してください。

    メッセージを表に挿入するジョブ通知ハンドラ・プロシージャを作成する例:

    CREATE TABLE ADMIN.JOB_STATUS(jnfy_data CLOB);

CREATE OR REPLACE PROCEDURE ADMIN.INSERT_JOB_STATUS(data_in CLOB) AS
  l_sessuser VARCHAR2(128) := SYS_CONTEXT('userenv','session_user');

BEGIN
  INSERT INTO ADMIN.JOB_STATUS (jnfy_data) VALUES (data_in || TO_CLOB(' : Sent By Session User : ' || l_sessuser));
  COMMIT;
END;
/

    この例では、JOB_STATUS表およびINSERT_JOB_STATUSプロシージャを作成して、セッション固有の値を表に挿入します。

    ジョブ通知ハンドラ・プロシージャを作成するには、ADMINユーザーとしてログインするか、CREATE ANY PROCEDUREシステム権限を持っている必要があります。

    ノート

    ノート:ジョブ通知ハンドラ・プロシージャとして無効な所有者またはオブジェクト名を指定すると、ORA-27405が返されます。

    既存のDBMS_SCHEDULERプロシージャADD_JOB_EMAIL_NOTIFICATIONおよびREMOVE_JOB_EMAIL_NOTIFICATIONは、ジョブ通知ハンドラ・プロシージャをサポートするように拡張されています。

    詳細は、「ADD_JOB_EMAIL_NOTIFICATIONプロシージャ」および「REMOVE_JOB_EMAIL_NOTIFICATIONプロシージャ」を参照してください。

    DBA_SCHEDULER_NOTIFICATIONSディクショナリ・ビューを使用して、スケジューラ・ジョブの通知のリストを問い合せます。詳細は、DBA_SCHEDULER_NOTIFICATIONSを参照してください。

ジョブ・ハンドラ通知プロシージャの登録

DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTEプロシージャを使用して、JOB_NOTIFICATION_HANDLER属性値を設定してジョブ・ハンドラ通知プロシージャを登録します。

JOB_NOTIFICATION_HANDLER属性は、使用するジョブ・ハンドラ通知プロシージャを指定します。

ジョブ・ハンドラ通知プロシージャを登録するには、次の操作を行う必要があります。

  • ADMINユーザーとしてログインするか、MANAGE SCHEDULER権限を持ちます。

  • ハンドラ・プロシージャまたはEXECUTE ANY PROCEDUREシステム権限に対するEXECUTE権限が必要です。

JOB_NOTIFICATION_HANDLER属性とEMAIL_SERVER属性は相互に排他的です。SET_SCHEDULER_ATTRIBUTEプロシージャのATTRIBUTEパラメータには、一度にJOB_NOTIFICATION_HANDLERまたはEMAIL_SERVERのいずれかの値を指定できます。電子メール通知を構成することも、スケジューラ・ジョブの通知ハンドラを作成することもできます。

EMAIL_SERVERとJOB_NOTIFICATION_HANDLERの両方のグローバル属性を設定しようとすると、ORA-27488エラーが発生します。

DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTEプロシージャを実行して、ジョブ・ハンドラの通知プロシージャを登録します。

BEGIN
  DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE('job_notification_handler','ADMIN.SEND_NOTIFICATION');
END;
/

この例では、ADMIN.SEND_NOTIFICATIONプロシージャをデータベースのジョブ・ハンドラ通知プロシージャとして登録します。

詳細は、SET_SCHEDULER_ATTRIBUTEプロシージャを参照してください。

次のコマンドを実行して、ジョブ通知ハンドラを確認します。

SELECT value FROM dba_scheduler_global_attribute WHERE attribute_name='JOB_NOTIFICATION_HANDLER';

VALUE
---------------
"ADMIN"."SEND_NOTIFICATION"

詳細は、DBA_SCHEDULER_GLOBAL_ATTRIBUTEを参照してください。

他のユーザーがジョブ通知ハンドラを使用できるようにするには、EXECUTE権限を割り当てる必要があります。次に例を示します。

GRANT EXECUTE ON ADMIN.SEND_NOTIFICATION To DWUSER;

ジョブ・ハンドラの通知プロシージャに対する権限がない場合は、ORA-27476 (""%s"."%s" does not exist")またはORA-27486 ("insufficient privileges")エラーがスローされます。

ジョブ・ハンドラ通知プロシージャのトリガー

ユーザー定義ジョブ通知ハンドラ・プロシージャをトリガーするには、DBMS_SCHEDULER.ADD_JOB_EMAIL_NOTIFICATIONプロシージャをコールする必要があります。

オーバーロードされた形式のDBMS_SCHEDULER.ADD_JOB_EMAIL_NOTIFICATIONを使用すると、ジョブ通知ハンドラ・プロシージャをトリガーして通知を送信できます。ただし、ジョブ通知ハンドラ・プロシージャを登録した場合、これらの通知は電子メールの形式では送信されません。したがって、パラメータSUBJECTおよびBODYはオプションです。RECIPIENTパラメータは引き続き必須です。このオーバーロードされたプロシージャは電子メール通知を送信しないため、RECIPIENTパラメータに任意の文字列値を指定できます。

たとえば、次のステップでは、スケジューラ・ジョブの作成、ジョブの通知の追加、ジョブの有効化、通知エントリの検証、ジョブ通知ハンドラ・プロシージャによって受信されたデータの表示、ジョブの通知の削除を行います。

  1. DWUSERスキーマにスケジューラ・ジョブを作成します。 
    BEGIN
DBMS_SCHEDULER.CREATE_JOB(
  job_name   => 'DWUSER.MY_JOB',
  job_type   => 'PLSQL_BLOCK',
  job_action => 'BEGIN null; END;',
  enabled    => FALSE,
  auto_drop  => FALSE);
END;
/

    これにより、指定された属性を持つジョブDWUSER.MY_JOBが作成されます。

    詳細は、CREATE_JOBプロシージャを参照してください。

  2. 指定したイベントで通知を送信するジョブを構成します。

    BEGIN
  DBMS_SCHEDULER.ADD_JOB_EMAIL_NOTIFICATION(
    job_name   => 'DWUSER.MY_JOB',
    recipients => 'PLACEHOLDER_STRING',
    subject    => 'Job Notification-%job_owner%.%job_name%-%event_type%',
    body       => '%event_type% occurred at %event_timestamp%. %error_message%',
    events     => 'job_started, job_succeeded, job_completed');
END;
/

    このプロシージャは、DWUSER.MY_JOBジョブの通知を追加します。通知は、指定されたジョブ状態イベントが発生するたびに送信されます。

    詳細は、「ADD_JOB_EMAIL_NOTIFICATIONプロシージャ」を参照してください。

  3. スケジューラ・ジョブを有効にします。

    EXEC DBMS_SCHEDULER.ENABLE('DWUSER.MY_JOB');

    詳細は、ENABLEプロシージャを参照してください。

    DWUSER.MY_JOBジョブを有効にすると、USER_SCHEDULER_NOTIFICATIONSビューにジョブ通知エントリが移入されます。確認するには、USER_SCHEDULER_NOTIFICATIONSビューを問い合せます。次に例を示します。

    SELECT  job_name, recipient, event, subject, body
FROM user_scheduler_notifications
ORDER BY notification_owner, owner, job_name;

JOB_NAME    RECIPIENT            EVENT          SUBJECT         BODY

-------    ------------------   -------------  --------------- ---------------
MY_JOB     placeholder_string   JOB_STARTED    Job Notificatio %event_type% oc
                                               n-%job_owner%.% curred at %even
                                               job_name%-%even t_timestamp%. %
                                               t_type%         error_message%

MY_JOB     placeholder_string  JOB_SUCCEEDED    Job Notificatio %event_type% oc
                                                n-%job_owner%.% curred at %even
                                                job_name%-%even t_timestamp%. %
                                                t_type%         error_message%

MY_JOB    placeholder_string  JOB_COMPLETED    Job Notificatio %event_type% oc
                                               n-%job_owner%.% curred at %even
                                               job_name%-%even t_timestamp%. %
                                               t_type%         error_message%

    詳細は、USER_SCHEDULER_NOTIFICATIONSビューを参照してください。

    ジョブDWUSER.MY_JOBが実行され、指定されたジョブ状態イベントが発生すると、ジョブ通知ハンドラ・プロシージャがトリガーされ、指定された情報が入力として受信されます。たとえば、ADMIN.SEND_NOTIFICATIONジョブ通知ハンドラ・プロシージャは次のものを受け取ります。

    {"job_owner":"DWUSER","job_name":"MY_JOB","job_class_name":"DEFAULT_JOB_CLA
SS","event_type":"JOB_STARTED","event_timestamp":"12-JAN-23 08.13.46.193306
 PM UTC","error_code":0,"error_msg":null,"sender":null,"recipient":"data_lo
ad_pipeline","subject":"Job Notification-DWUSER.MY_JOB-JOB_STARTED","msg_te
xt":"JOB_STARTED occurred at 12-JAN-23 08.13.46.193306 PM UTC. ","comments"
:"User defined job notification handler"}

{"job_owner":"DWUSER","job_name":"MY_JOB","job_class_name":"DEFAULT_JOB_CLA
SS","event_type":"JOB_SUCCEEDED","event_timestamp":"12-JAN-23 08.13.46.2863
44 PM UTC","error_code":0,"error_msg":null,"sender":null,"recipient":"data_
load_pipeline","subject":"Job Notification-DWUSER.MY_JOB-JOB_SUCCEEDED","ms
g_text":"JOB_SUCCEEDED occurred at 12-JAN-23 08.13.46.286344 PM UTC. ","com
ments":"User defined job notification handler"}

  4. ジョブ通知を削除します。たとえば:

    EXEC DBMS_SCHEDULER.REMOVE_JOB_EMAIL_NOTIFICATION('DWUSER.MY_JOB');

    詳細は、REMOVE_JOB_EMAIL_NOTIFICATIONプロシージャを参照してください。

ジョブ・ハンドラ通知プロシージャの登録解除

DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTEを使用して、ジョブ・ハンドラの通知プロシージャを登録解除します。

ジョブ・ハンドラの通知プロシージャを登録解除するには、ADMINユーザーとしてログインしているか、MANAGE SCHEDULER権限を持っている必要があります。

ジョブ・ハンドラ通知プロシージャを登録解除する例:

BEGIN
  DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE ('job_notification_handler','');
END;
/