Documentação do Oracle Cloud Infrastructure

Handler de Notificação Definido pelo Usuário para Jobs do Scheduler

O Database Scheduler fornece um mecanismo de notificação por e-mail para rastrear o status de jobs periodicamente em execução ou automatizados. Além disso, o Database Scheduler também suporta o procedimento do handler de notificação de job do PL/SQL Scheduler definido pelo usuário.

A adição de um procedimento de handler de notificação de job do scheduler permite monitorar jobs programados ou automatizados em execução no seu Autonomous Database.

Tópico principal: Desenvolver

Sobre o Handler de Notificação Definido pelo Usuário para Jobs do Scheduler

O Database Scheduler suporta o procedimento de handler de notificação de job que pode usar código personalizado para chamar pontos finais HTTP ou REST para melhor monitoramento de jobs do scheduler em uma instância do Autonomous Database.

O procedimento do handler recebe todas as informações pertinentes relacionadas ao job, como nome do proprietário do job, nome da classe, tipo de evento e timestamp no formato JSON. Com base nas informações, o procedimento do handler executa a ação necessária.

Consulte DBMS_SCHEDULER para obter mais informações sobre o Oracle Scheduler.

A configuração do handler de notificação definido pelo usuário para jobs do scheduler consiste nestas etapas:

Criar um Procedimento de Handler de Notificação de Tarefa

Fornece etapas para criar um handler de notificação de job.

  1. Crie um objeto de credencial.

    Consulte CREATE_CREDENTIAL Procedimento para obter mais informações.

    Consulte Especificando Credenciais de Job do Scheduler para obter mais informações.

  2. Criar um handler de notificação de Job:

    Exemplo para criar um procedimento de handler de notificação de job para enviar uma mensagem a um canal do 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;
/

    Este exemplo cria o procedimento SEND_NOTIFICATION.

    Este procedimento definido pelo usuário envia os dados de entrada fornecidos como uma mensagem para o canal do Slack especificado.

    Consulte Enviar Notificações do Slack pelo Autonomous Database para obter mais informações.

    Consulte SEND_MESSAGE Procedimento para obter mais informações.

    Exemplo para criar um procedimento de handler de notificação de job para inserir a mensagem em uma tabela:

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

    Este exemplo cria a tabela JOB_STATUS e o procedimento INSERT_JOB_STATUS para inserir os valores específicos da sessão na tabela.

    Você deve estar conectado como o usuário ADMIN ou ter o privilégio de sistema CREATE ANY PROCEDURE para criar um procedimento de handler de notificação de job.

    Observação

    Um ORA-27405 é retornado quando você especifica um proprietário ou nome de objeto inválido como procedimento do handler de notificação de job.

    Os procedimentos DBMS_SCHEDULER existentes ADD_JOB_EMAIL_NOTIFICATION e REMOVE_JOB_EMAIL_NOTIFICATION são aprimorados para suportar o procedimento do handler de notificação de job.

    Consulte Procedimento ADD_JOB_EMAIL_NOTIFICATION e Procedimento REMOVE_JOB_EMAIL_NOTIFICATION para obter mais informações.

    Use a view do dicionário DBA_SCHEDULER_NOTIFICATIONS para consultar a lista de notificações de um job do scheduler. Consulte DBA_SCHEDULER_NOTIFICATIONS para obter mais informações.

Registrar o Procedimento de Notificação do Processador de Tarefas

Use o procedimento DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE para definir o valor do atributo JOB_NOTIFICATION_HANDLER para registrar o procedimento de notificação do handler de job.

O atributo JOB_NOTIFICATION_HANDLER especifica o procedimento de notificação do handler de job que você deseja usar.

Para registrar o procedimento de notificação do processador de cargos, você deve:

  • Esteja conectado como o usuário ADMIN ou tenha o privilégio MANAGE SCHEDULER.

  • Tenha o privilégio EXECUTE no procedimento do handler ou no privilégio de sistema EXECUTE ANY PROCEDURE.

O atributo JOB_NOTIFICATION_HANDLER e o atributo EMAIL_SERVER são mutuamente exclusivos. O parâmetro ATTRIBUTE do procedimento SET_SCHEDULER_ATTRIBUTE pode ter o valor JOB_NOTIFICATION_HANDLER ou EMAIL_SERVER por vez. Você tem permissão para configurar notificações por e-mail ou criar seu handler de notificação para seus jobs do scheduler.

Um erro ORA-27488 é gerado quando você tenta definir os atributos globais EMAIL_SERVER e JOB_NOTIFICATION_HANDLER.

Execute o procedimento DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE para registrar o procedimento de notificação do handler de job: 

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

Este exemplo registra o procedimento ADMIN.SEND_NOTIFICATION como o procedimento de notificação do handler de job para seu banco de dados.

Consulte SET_SCHEDULER_ATTRIBUTE Procedimento para obter mais informações.

Execute este comando para verificar o handler de notificação de job:


SELECT value FROM dba_scheduler_global_attribute WHERE attribute_name='JOB_NOTIFICATION_HANDLER';

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

Consulte DBA_SCHEDULER_GLOBAL_ATTRIBUTE para obter mais informações.

Você deve designar o privilégio EXECUTE para permitir que outros usuários usem o handler de notificação de job. Por exemplo: 

GRANT EXECUTE ON ADMIN.SEND_NOTIFICATION To DWUSER;

O erro ORA-27476 ("\"%s\".\"%s\" does not exist") ou ORA-27486 ("insufficient privileges") será gerado se você não tiver privilégio no procedimento de notificação do handler de job.

Acionar o Procedimento de Notificação do Processador de Tarefas

Você deve chamar o procedimento DBMS_SCHEDULER.ADD_JOB_EMAIL_NOTIFICATION para acionar o procedimento do handler de notificação de job definido pelo usuário.

O formulário sobrecarregado do DBMS_SCHEDULER.ADD_JOB_EMAIL_NOTIFICATION permite acionar o procedimento do handler de notificação de job e enviar uma notificação. No entanto, essas notificações não são enviadas na forma de um e-mail quando você registrou o procedimento do handler de notificação de job. Portanto, os parâmetros SUBJECT e BODY são opcionais. O parâmetro RECIPIENT ainda é obrigatório. Como essa forma de procedimento sobrecarregada não está enviando notificações por e-mail, você pode fornecer qualquer valor de string para o parâmetro RECIPIENT.
Por exemplo, as etapas a seguir criam um job do scheduler, adicionam notificação ao job, ativam o job, verificam as entradas de notificação, mostram os dados recebidos pelo procedimento do handler de notificação do job e removem a notificação do job.
  1. Crie um job do scheduler no esquema 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;
/

    Isso cria um job DWUSER.MY_JOB com os atributos especificados.

    Consulte CREATE_JOB Procedimento para obter mais informações.

  2. Configure o job para enviar notificações em eventos especificados.
    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;
/

    Esse procedimento adiciona notificações para o job DWUSER.MY_JOB. As notificações são enviadas sempre que qualquer um dos eventos de estado do job especificado é gerado.

    Consulte ADD_JOB_EMAIL_NOTIFICATION Procedimento para obter mais informações.

  3. Ativar o job do programador.
    EXEC DBMS_SCHEDULER.ENABLE('DWUSER.MY_JOB');

    Consulte Procedimento Ativar para obter mais informações.

    Quando você ativa o job DWUSER.MY_JOB, a view USER_SCHEDULER_NOTIFICATIONS é preenchida com as entradas de notificação de job. Para verificar se você pode consultar a view USER_SCHEDULER_NOTIFICATIONS. Por exemplo:
    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%

    Consulte USER_SCHEDULER_NOTIFICATIONS View para obter mais informações.

    Quando o job DWUSER.MY_JOB é executado e qualquer um dos eventos de estado do job especificado é gerado, o procedimento do handler de notificação do job é acionado e recebe as informações especificadas como entrada. Por exemplo, o procedimento do handler de notificação de job ADMIN.SEND_NOTIFICATION recebe o seguinte: 

    {"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. Remova a notificação do job. Por exemplo:
    EXEC DBMS_SCHEDULER.REMOVE_JOB_EMAIL_NOTIFICATION('DWUSER.MY_JOB');

    Consulte REMOVE_JOB_EMAIL_NOTIFICATION Procedimento para obter mais informações.

Cancelar o Registro do Procedimento de Notificação do Processador de Tarefas

Use DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE para cancelar o registro do procedimento de notificação do handler de job.

Para cancelar o registro do procedimento de notificação do handler de job, você deve estar conectado como usuário ADMIN ou ter o privilégio MANAGE SCHEDULER.

Exemplo para cancelar o registro do procedimento de notificação do processador de cargos:

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