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

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

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

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

データベース・スケジューラでは、Autonomous 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 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権限またはEXECUTE ANY PROCEDUREシステム権限があること。

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

EMAIL_SERVERJOB_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;
/