Oracle Cloud Infrastructure-Dokumentation

Benutzerdefinierter Benachrichtigungs-Handler für Scheduler-Jobs

Database Scheduler bietet einen E-Mail-Benachrichtigungsmechanismus, mit dem Sie den Status von regelmäßig ausgeführten oder automatisierten Jobs verfolgen können. Darüber hinaus unterstützt der Database Scheduler auch die benutzerdefinierte Benachrichtigungs-Handler-Prozedur für PL/SQL Scheduler-Jobs.

Wenn Sie eine Prozedur für den Benachrichtigungs-Handler eines Scheduler-Jobs hinzufügen, können Sie geplante oder automatisierte Jobs überwachen, die in Autonomous Database ausgeführt werden.

Übergeordnetes Thema: Entwickeln

Benutzerdefinierte Benachrichtigungs-Handler für Scheduler-Jobs

Der Database Scheduler unterstützt die Prozedur für den Jobbenachrichtigungs-Handler, die benutzerdefinierten Code zum Aufrufen von HTTP- oder REST-Endpunkten verwenden kann, um die Überwachung von Scheduler-Jobs in einer Autonomous Database-Instanz zu verbessern.

Die Handler-Prozedur empfängt alle relevanten Informationen zum Job, wie den Namen des Job-Eigentümers, den Klassennamen, den Ereignistyp und den Zeitstempel im JSON-Format. Basierend auf den Informationen führt die Handler-Prozedur dann die erforderliche Aktion aus.

Weitere Informationen zu Oracle Scheduler finden Sie unter DBMS_SCHEDULER.

Die Konfiguration eines benutzerdefinierten Benachrichtigungs-Handlers für Scheduler-Jobs umfasst die folgenden Schritte:

Job Notification Handler-Prozedur erstellen

Enthält Schritte zum Erstellen eines Jobbenachrichtigungs-Handlers.

  1. Erstellen Sie ein Zugangsdatenobjekt.

    Weitere Informationen finden Sie unter Prozedur CREATE_CREDENTIAL.

    Weitere Informationen finden Sie unter Zugangsdaten für Scheduler-Jobs angeben.

  2. Jobbenachrichtigungs-Handler erstellen:

    Beispiel zum Erstellen einer Jobbenachrichtigungs-Handler-Prozedur zum Senden einer Nachricht an einen Slack-Kanal:

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

    In diesem Beispiel wird die Prozedur SEND_NOTIFICATION erstellt.

    Diese benutzerdefinierte Prozedur sendet die angegebenen Eingabedaten als Nachricht an den angegebenen Slack-Kanal.

    Weitere Informationen finden Sie unter Slack-Benachrichtigungen von Autonomous Database senden.

    Weitere Informationen finden Sie unter Prozedur SEND_MESSAGE.

    Beispiel für die Erstellung einer Job Notification Handler-Prozedur zum Einfügen der Nachricht in eine Tabelle:

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

    In diesem Beispiel werden die Tabelle JOB_STATUS und die Prozedur INSERT_JOB_STATUS erstellt, um die sitzungsspezifischen Werte in die Tabelle einzufügen.

    Sie müssen als ADMIN-Benutzer angemeldet sein oder über die Systemberechtigung CREATE ANY PROCEDURE verfügen, um eine Jobbenachrichtigungs-Handler-Prozedur zu erstellen.

    Hinweis

    Wenn Sie einen ungültigen Eigentümer oder Objektnamen als Jobbenachrichtigungs-Handler-Prozedur angeben, wird eine ORA-27405 zurückgegeben.

    Vorhandene DBMS_SCHEDULER-Prozeduren ADD_JOB_EMAIL_NOTIFICATION und REMOVE_JOB_EMAIL_NOTIFICATION werden erweitert, um die Jobbenachrichtigungs-Handler-Prozedur zu unterstützen.

    Weitere Informationen finden Sie unter Prozedur ADD_JOB_EMAIL_NOTIFICATION und Prozedur REMOVE_JOB_EMAIL_NOTIFICATION.

    Verwenden Sie die Dictionary View DBA_SCHEDULER_NOTIFICATIONS, um die Liste der Benachrichtigungen für einen Scheduler-Job abzufragen. Weitere Informationen finden Sie unter DBA_SCHEDULER_NOTIFICATIONS.

Benachrichtigungsprozedur für Job Handler registrieren

Verwenden Sie die Prozedur DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE, um den Attributwert JOB_NOTIFICATION_HANDLER festzulegen, um die Benachrichtigungsprozedur des Job Handlers zu registrieren.

Das Attribut JOB_NOTIFICATION_HANDLER gibt die Benachrichtigungsprozedur für den Job-Handler an, die Sie verwenden möchten.

Um das Benachrichtigungsverfahren für Job Handler zu registrieren, müssen Sie:

  • Sie müssen als ADMIN-Benutzer angemeldet sein oder über die Berechtigung MANAGE SCHEDULER verfügen.

  • Sie verfügen über die Berechtigung EXECUTE für die Handler-Prozedur oder die Systemberechtigung EXECUTE ANY PROCEDURE.

Das Attribut JOB_NOTIFICATION_HANDLER und das Attribut EMAIL_SERVER schließen sich gegenseitig aus. Der Parameter ATTRIBUTE der Prozedur SET_SCHEDULER_ATTRIBUTE kann jeweils den Wert JOB_NOTIFICATION_HANDLER oder EMAIL_SERVER aufweisen. Sie können E-Mail-Benachrichtigungen konfigurieren oder Ihren Benachrichtigungs-Handler für Ihre Scheduler-Jobs erstellen.

Wenn Sie versuchen, globale Attribute EMAIL_SERVER und JOB_NOTIFICATION_HANDLER festzulegen, wird ein ORA-27488-Fehler ausgelöst.

Führen Sie die Prozedur DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE aus, um die Benachrichtigungsprozedur des Job Handlers zu registrieren: 

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

In diesem Beispiel wird die Prozedur ADMIN.SEND_NOTIFICATION als Benachrichtigungsprozedur für den Job Handler für die Datenbank registriert.

Weitere Informationen finden Sie unter Prozedur SET_SCHEDULER_ATTRIBUTE.

Führen Sie diesen Befehl aus, um den Job Notification Handler zu prüfen:


SELECT value FROM dba_scheduler_global_attribute WHERE attribute_name='JOB_NOTIFICATION_HANDLER';

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

Weitere Informationen finden Sie unter DBA_SCHEDULER_GLOBAL_ATTRIBUTE.

Sie müssen die Berechtigung EXECUTE zuweisen, damit andere Benutzer den Jobbenachrichtigungs-Handler verwenden können. Beispiele: 

GRANT EXECUTE ON ADMIN.SEND_NOTIFICATION To DWUSER;

Der Fehler ORA-27476 ("\"%s\".\"%s\" does not exist") oder ORA-27486 ("insufficient privileges") wird ausgelöst, wenn Sie keine Berechtigung für die Benachrichtigungsprozedur des Job Handlers haben.

Job Handler-Benachrichtigungsprozedur auslösen

Sie müssen die Prozedur DBMS_SCHEDULER.ADD_JOB_EMAIL_NOTIFICATION aufrufen, um die benutzerdefinierte Jobbenachrichtigungs-Handler-Prozedur auszulösen.

Mit der überladenen Form von DBMS_SCHEDULER.ADD_JOB_EMAIL_NOTIFICATION können Sie die Jobbenachrichtigungs-Handler-Prozedur auslösen und eine Benachrichtigung senden. Diese Benachrichtigungen werden jedoch nicht in Form einer E-Mail gesendet, wenn Sie die Job Notification Handler-Prozedur registriert haben. Daher sind die Parameter SUBJECT und BODY optional. Der Parameter RECIPIENT ist weiterhin obligatorisch. Da diese überladene Prozedur keine E-Mail-Benachrichtigungen sendet, können Sie einen beliebigen Zeichenfolgenwert für den Parameter RECIPIENT angeben.
Beispiel: Die folgenden Schritte erstellen einen Scheduler-Job, fügen Benachrichtigungen für den Job hinzu, aktivieren den Job, prüfen die Benachrichtigungseinträge, zeigen die von der Jobbenachrichtigungs-Handler-Prozedur erhaltenen Daten an und entfernen Benachrichtigungen für den Job.
  1. Erstellen Sie einen Scheduler-Job im Schema 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;
/

    Dadurch wird ein Job DWUSER.MY_JOB mit den angegebenen Attributen erstellt.

    Weitere Informationen finden Sie unter Prozedur CREATE_JOB.

  2. Konfigurieren Sie den Job so, dass Benachrichtigungen bei angegebenen Ereignissen gesendet werden.
    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;
/

    Mit dieser Prozedur werden Benachrichtigungen für den Job DWUSER.MY_JOB hinzugefügt. Die Benachrichtigungen werden gesendet, wenn eines der angegebenen Jobstatusereignisse ausgelöst wird.

    Weitere Informationen finden Sie unter Prozedur ADD_JOB_EMAIL_NOTIFICATION.

  3. Aktivieren Sie den Scheduler-Job.
    EXEC DBMS_SCHEDULER.ENABLE('DWUSER.MY_JOB');

    Weitere Informationen finden Sie unter Prozedur ENABLE.

    Wenn Sie den Job DWUSER.MY_JOB aktivieren, wird die View USER_SCHEDULER_NOTIFICATIONS mit den Jobbenachrichtigungseinträgen aufgefüllt. Um zu prüfen, können Sie die View USER_SCHEDULER_NOTIFICATIONS abfragen. Beispiele:
    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%

    Weitere Informationen finden Sie unter Ansicht USER_SCHEDULER_NOTIFICATIONS.

    Wenn der Job DWUSER.MY_JOB ausgeführt wird und eines der angegebenen Jobstatusereignisse ausgelöst wird, wird die Jobbenachrichtigungs-Handler-Prozedur ausgelöst und erhält die angegebenen Informationen als Eingabe. Beispiel: Die Jobbenachrichtigungs-Handler-Prozedur ADMIN.SEND_NOTIFICATION erhält Folgendes: 

    {"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. Entfernen Sie die Job-Benachrichtigung. Beispiele:
    EXEC DBMS_SCHEDULER.REMOVE_JOB_EMAIL_NOTIFICATION('DWUSER.MY_JOB');

    Weitere Informationen finden Sie unter Prozedur REMOVE_JOB_EMAIL_NOTIFICATION.

Benachrichtigungsprozedur für Job Handler deaktivieren

Verwenden Sie DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE, um die Registrierung der Benachrichtigungsprozedur für den Job Handler aufzuheben.

Um die Registrierung der Benachrichtigungsprozedur für den Job Handler aufzuheben, müssen Sie als ADMIN-Benutzer angemeldet sein oder über die Berechtigung MANAGE SCHEDULER verfügen.

Beispiel zum Aufheben der Registrierung der Benachrichtigungsprozedur für den Job Handler:

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