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 em execução ou automatizados periodicamente. Além disso, o Scheduler de Banco de Dados também suporta o procedimento do handler de notificação de job do Scheduler PL/SQL definido pelo usuário.

A adição de um procedimento do handler de notificação de job do scheduler permite que você monitore 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 do handler de notificação de job que pode usar código personalizado para chamar pontos finais HTTP ou REST para monitoramento aprimorado de jobs do scheduler em uma instância do Autonomous Database.

O procedimento do handler recebe todas as informações pertinentes sobre o 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 manipulador 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 do Handler de Notificação de Cargo

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

  1. Crie um objeto de credencial.

    Consulte CREATE_CREDENTIAL Procedures para obter mais informações.

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

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

    Exemplo para criar um procedimento do 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 do Autonomous Database para obter mais informações.

    Consulte SEND_MESSAGE Procedures para obter mais informações.

    Exemplo de criação de um procedimento do processador de notificações de cargo 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 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

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

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

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

    Use a view de 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 Cargos

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 jobs, você deve:

  • Faça log-in como usuário ADMIN ou tenha o privilégio MANAGE SCHEDULER.

  • Tenha o privilégio EXECUTE no procedimento do handler ou o 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 de cada vez. Você tem permissão para configurar notificações por e-mail ou criar seu handler de notificação para suas tarefas 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 jobs: 

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 jobs do seu banco de dados.

Consulte SET_SCHEDULER_ATTRIBUTE Procedures 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égios no procedimento de notificação do handler de jobs.

Acionar Procedimento de Notificação do Processador de Jobs

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ê registra o procedimento do processador de notificações de cargo. Portanto, os parâmetros SUBJECT e BODY são opcionais. O parâmetro RECIPIENT ainda é obrigatório. Como esse formulário de procedimento sobrecarregado 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ções para o job, ativam o job, verificam as entradas de notificação, mostram os dados recebidos pelo procedimento do handler de notificação de 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 Procedures 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;
/

    Este 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 cargo especificado é gerado.

    Consulte ADD_JOB_EMAIL_NOTIFICATION Procedures para obter mais informações.

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

    Consulte CAPACITAR Procedimento 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 do job. Para verificar, 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 de 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 Procedures para obter mais informações.

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

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

Para cancelar o registro do procedimento de notificação do handler de jobs, 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 tarefas:

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