Oracle Cloud Infrastructure-Dokumentation

Benutzerdefinierter Benachrichtigungs-Handler für Scheduler-Jobs

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

Durch das Hinzufügen einer Scheduler-Jobbenachrichtigungs-Handler-Prozedur können Sie geplante oder automatisierte Jobs überwachen, die in Autonomous Database ausgeführt werden.

Übergeordnetes Thema: Entwickeln

Benutzerdefinierter 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 das Monitoring von Scheduler-Jobs in einer Autonomous Database-Instanz zu verbessern.

Die Handler-Prozedur erhält alle relevanten Informationen zum Job, wie Name, Klassenname, Ereignistyp und Zeitstempel des Jobverantwortlichen 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 des benutzerdefinierten Benachrichtigungs-Handlers für Scheduler-Jobs umfasst folgende Schritte:

Prozedur "Job Notification Handler erstellen"

Bietet 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, um eine Nachricht an einen Slack-Kanal zu senden:

    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 sessionspezifischen 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 Prozedur für den Jobbenachrichtigungs-Handler zu erstellen.

    Hinweis

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

    Die vorhandenen DBMS_SCHEDULER-Prozeduren ADD_JOB_EMAIL_NOTIFICATION und REMOVE_JOB_EMAIL_NOTIFICATION werden erweitert, um die Prozedur für den Jobbenachrichtigungs-Handler 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.

Job Handler-Benachrichtigungsprozedur 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 Job Handler-Benachrichtigungsprozedur an, die Sie verwenden möchten.

Um die Job Handler-Benachrichtigungsprozedur zu registrieren, müssen Sie:

  • Melden Sie sich als ADMIN-Benutzer an, oder haben Sie die Berechtigung MANAGE SCHEDULER.

  • 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 entweder den Wert JOB_NOTIFICATION_HANDLER oder den Wert EMAIL_SERVER gleichzeitig enthalten. Sie können entweder 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 Job Handler-Benachrichtigungsprozedur für Ihre 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. Beispiel: 

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.

Prozedur für Job Handler-Benachrichtigungen auslösen

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

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

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

    Wenn der Job DWUSER.MY_JOB ausgeführt wird und eines der angegebenen Jobstatusereignisse ausgelöst wird, wird die Prozedur des Jobbenachrichtigungs-Handlers ausgelöst und erhält die angegebenen Informationen als Eingabe. Beispiel: Die Jobbenachrichtigungs-Handler-Prozedur ADMIN.SEND_NOTIFICATION empfängt 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 Jobbenachrichtigung. Beispiel:
    EXEC DBMS_SCHEDULER.REMOVE_JOB_EMAIL_NOTIFICATION('DWUSER.MY_JOB');

    Weitere Informationen finden Sie unter Prozedur REMOVE_JOB_EMAIL_NOTIFICATION.

Registrierung der Benachrichtigungsprozedur für Job-Handler aufheben

Verwenden Sie DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE, um die Registrierung der Job Handler-Benachrichtigungsprozedur aufzuheben.

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

Beispiel zum Aufheben der Registrierung der Job Handler-Benachrichtigungsprozedur:

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