Referência do Pacote DBMS_DATA_TOOLS_JOBS

Este capítulo fornece informações sobre os pacotes que você usa com o recurso Jobs no Data Studio. O tópico Resumo de Subprogramas DBMS_DATA_TOOLS_JOBS também abrange os procedimentos incluídos no pacote DBMS_DATA_TOOLS_JOBS.

Tópicos:

Resumo dos Subprogramas DBMS_DATA_TOOLS_JOB

  • Resumo de Subprogramas DBMS_DATA_TOOLS_JOB
    O pacote DBMS_DATA_TOOLS_JOB fornece um conjunto de funções e procedimentos de programação que você usa com o recurso Jobs no conjunto de ferramentas do Data Studio.

Tópico principal: O Recurso Jobs

Resumo dos Subprogramas DBMS_DATA_TOOLS_JOB

O pacote DBMS_DATA_TOOLS_JOB fornece um conjunto de funções e procedimentos de programação que você usa com o recurso Jobs no conjunto de ferramentas do Data Studio.

Subprogramas do Pacote DBMS_DATA_TOOLS_JOB

A tabela a seguir lista os subprogramas DBMS_DATA_TOOLS_JOB e os descreve brevemente.

Tabela 22-2 Nomes e descrição de DBMS_DATA_TOOLS_JOB para os Subprogramas DBMS_DATA_TOOLS_JOB

Subprograma Descrição
Criar procedimento de tarefa Este procedimento cria um novo job.
Excluir procedimento de tarefa Exclui o job do programador.
Renomear procedimento de tarefa Renomeia o job com o nome desejado.
Atualizar procedimento de tarefa Modifica os atributos de um job existente.
Executar procedimento Executa um job imediatamente, independentemente da programação definida.
Interromper procedimento de tarefa Interrompe um job em execução. Isso encerra um trabalho graciosamente e, se necessário, interrompe-o à força.

Considerações sobre Segurança

Não coloque dados confidenciais, como segredos, tokens de portador, senhas, chaves privadas, URLs assinados ou outras credenciais, diretamente em URLs de etapa de job, corpos de solicitação ou configuração de relatório. Esses valores podem ser armazenados com a definição do job e recuperados posteriormente. Use credenciais de banco de dados ou credenciais nomeadas para autenticação.

Procedimento CREATE_JOB

Este procedimento cria um único job. Se você criar o job conforme ativado, definindo o atributo ativado como TRUE, o Scheduler executará automaticamente o job de acordo com sua programação. Se você criar o job desativado, o job não será executado até que você o ative com o recurso Ativar Job.

Sintaxe

dbms_data_tools_job.create_job(
                       job_name        in varchar2,
                       description     in varchar2,
                       steps           in clob,
                       owner           in varchar2 default null,
                       start_date      IN TIMESTAMP WITH TIME ZONE DEFAULT NULL,
                       repeat_interval IN VARCHAR2                 DEFAULT NULL,
                       end_date        IN TIMESTAMP WITH TIME ZONE DEFAULT NULL,
                       job_class       IN VARCHAR2                 DEFAULT NULL,
                       enabled         IN BOOLEAN                  DEFAULT FALSE,
                       reporting       in clob default null);

Parâmetros do Procedimento CREATE_JOB

Tabela 22-3 Parâmetros do Procedimento CREATE_JOB

Parâmetro Descrição
Nome do Job O nome a ser designado ao job. Se job_name não for especificado, um erro será gerado.
Descrição Refere-se a informações adicionais definidas para cargos.
Etapas Refere-se a várias tarefas que a ferramenta do Data Studio executa que compreendem um job.
Steps é um array JSON. Cada elemento de matriz é um objeto JSON. Aqui estão os elementos JSON que se aplicam a todos os objetos:
  • type - string, declara o tipo de etapa que é executada: data_load, smart_table, procedure, http.
  • on_errors- string
  • stop: Se for encontrado um erro, o job será interrompido e o erro será gerado.
  • continue: o erro é registrado, mas o processamento continua com a próxima etapa do job.
  • step_name - nome descritivo da etapa a ser exibida nos logs

Cada tipo de objeto tem alguns elementos adicionais, dependendo do tipo.

data_load:
  • data_load_name - (obrigatório) o nome de um carregamento de dados criado anteriormente a ser executado
smart_table:
  • recipe_name - (obrigatório) o nome de uma receita de tabela inteligente criada anteriormente a ser executada.
  • url - URL REST (obrigatório) ao qual estabelecer conexão.
  • method - GET (padrão), POST, PUT, DELETE ou algum outro verbo HTTP
procedure:

  • procedure - nome (obrigatório) do procedimento a ser executado. Opcionalmente, ele pode ser qualificado por esquema e pode ser um procedimento bare ou um método de pacote.

  • arguments - array de string, número ou argumentos boolianos a serem fornecidos para o procedimento.

Atenção:

Para etapas HTTP, não coloque dados confidenciais no URL ou no corpo da solicitação. Use credenciais de banco de dados ou credenciais nomeadas para autenticação.
Proprietário

É o esquema no qual o job é criado. Se você criar um job sem especificar um esquema, o proprietário será o usuário que está executando o procedimento CREATE_JOB.

Data Inicial

Este atributo especifica a primeira data e hora em que este job está programado para iniciar. Se start_date e repeat_interval forem deixados nulos, o job será programado para ser executado assim que o job for ativado.

Para jobs repetidos que usam uma expressão de calendário para especificar o intervalo de repetição, start_date é usado como uma data de referência. A primeira vez que o job é executado é a primeira correspondência da expressão de calendário que é igual ou posterior à data e hora atuais.

O Scheduler não pode garantir que um job seja executado em um horário exato porque o sistema pode estar sobrecarregado e, portanto, recursos indisponíveis.
Intervalo de Repetição

Este atributo especifica com que frequência a janela se repete. Ele é expresso usando a sintaxe de calendário do Scheduler. Consulte "Sintaxe de Calendário" para obter mais informações.

Uma expressão PL/SQL não pode ser usada para especificar o intervalo de repetição de uma janela.

A expressão especificada é avaliada para determinar a próxima vez que a janela for aberta. Se nenhum repeat_interval for especificado, a janela será aberta apenas uma vez na data inicial especificada.

Data de Término

Este atributo especifica a data e a hora após as quais o job expira e não é mais executado.

O valor de end_date deve ser posterior ao valor de start_date. Se end_date for menor que start_date, um erro será gerado. Se end_date for igual ao start_date, o job não será executado e nenhum erro será gerado.

Se nenhum valor para end_date for especificado, o job será repetido para sempre, a menos que você stop job.
Classe de Job A classe à qual este cargo está associado.
Habilitado Este atributo especifica se o job foi criado ativado ou não. As definições possíveis são TRUE ou FALSE. Por padrão, esse atributo é definido como FALSE e, portanto, o job é criado como desativado. Um job desativado significa que os metadados sobre o job foram capturados e o job existe como um objeto de banco de dados. No entanto, o Scheduler ignora o job e o coordenador do job não o escolhe para processamento. Para que o coordenador do job processe o job, o job deve ser ativado. Você pode ativar um job selecionando o ícone Enable Job.
Geração de Relatórios Este atributo especifica os detalhes da execução do job por meio do botão Relatório no recurso Jobs.
Este é um objeto JSON semelhante ao argumento de relatório para dbms_live_feed. Ela pode ter os seguintes elementos:

  • completed: Destinos a serem notificados quando um job é concluído.

  • errors: Destinos a serem notificados quando alguma etapa de um job encontrou erros.

  • failed: Destinos a serem notificados quando um job teve algum erro fatal fora do contexto de uma etapa.

  • long: Destinos a serem notificados quando um job foi executado por muito tempo.

Cada um desses quatro elementos pode especificar um array de endereço de e-mail no elemento smtp ou canais de folga no elemento slack. O elemento long pode ter um elemento max_runtime_seconds que determina quanto tempo um job deve ser executado antes de ser considerado como tendo sido executado muito long.

Atenção:

Não inclua dados confidenciais na configuração do relatório.

Procedimento DELETE_JOB

Este procedimento exclui um job.

Sintaxe

dbms_data_tools_job.delete_job(
                     job_name in varchar2, 
                     owner    in varchar2 default null);

Parâmetros do Procedimento DELETE_JOB

Tabela 22-4 Parâmetros do Procedimento DELETE_JOB

Parâmetro Descrição
Nome do Job O nome a ser designado ao job. Se job_name não for especificado, um erro será gerado.
Proprietário

É o esquema no qual o job é criado. Se você criar um job sem especificar um esquema, o proprietário será o usuário que está executando o procedimento CREATE_JOB.

Procedimento RENAME_JOB

Este procedimento renomeia um job.

Sintaxe

dbms_data_tools_job.rename_job(
                       old_job_name in varchar2,
                       new_job_name in varchar2,
                       owner        in varchar2 default null);

Parâmetros do Procedimento RENAME_JOB

Tabela 22-5 Parâmetros do Procedimento RENAME_JOB

Parâmetro Descrição
Nome do Job Antigo O nome do job existente.
Nome do Novo Job

Nome da nova tarefa.
Proprietário

É o esquema no qual o job é criado.

Procedimento UPDATE_JOB

Este procedimento atualiza qualquer um dos atributos de job existentes.

Sintaxe

dbms_data_tools_job.update_job(
                       job_name        IN VARCHAR2,
                       owner           IN VARCHAR2 DEFAULT NULL,
                       description     IN VARCHAR2 DEFAULT NULL,
                       steps           IN clob DEFAULT NULL,
                       start_date      IN TIMESTAMP WITH TIME ZONE DEFAULT NULL,
                       repeat_interval IN VARCHAR2                 DEFAULT NULL,
                       end_date        IN TIMESTAMP WITH TIME ZONE DEFAULT NULL,
                       job_class       IN VARCHAR2                 DEFAULT NULL,
                       enabled         IN BOOLEAN                  DEFAULT NULL,
                       reporting       IN clob DEFAULT NULL);

Parâmetros do Procedimento UPDATE_JOB

Tabela 22-6 Parâmetros do Procedimento UPDATE_JOB

Parâmetro Descrição
Nome do Job O nome do Job a ser atualizado.
Proprietário

É o esquema no qual o job deve ser atualizado.
Descrição A descrição atualizada a ser aplicada.
Etapas As novas etapas para atualizar.

Atenção:

Para etapas HTTP, não coloque dados confidenciais no URL ou no corpo da solicitação. Use credenciais de banco de dados ou credenciais nomeadas para autenticação.
Data Inicial A nova data inicial.
Intervalo de Repetição O intervalo de repetição atualizado.
Data de Término A data final atualizada.
Classe de Job A classe de cargo atualizada.
Habilitado Pode ser ativado ou desativado.
Geração de Relatórios O atributo de relatório atualizado.

Atenção:

Não inclua dados confidenciais na configuração do relatório.

Executar Procedimento

Este procedimento executa um job imediatamente.

Se um job estiver ativado, o Scheduler o executará automaticamente. Não é necessário chamar RUN_JOB para executar um job de acordo com sua programação. Use RUN_JOB para executar um job fora de sua programação normal.

Sintaxe

dbms_data_tools_job.run(
                job_name            in varchar2,
                owner               in varchar2 default null,
                use_current_session in number   default null,
                options             in clob     default null);

Parâmetros do Procedimento RUN

Tabela 22-7 Parâmetros do Procedimento RUN

Parâmetro Descrição
Nome do Job

Um nome de job ou uma lista de entradas separadas por vírgulas, em que cada um é o nome de um job existente, opcionalmente precedido por um nome de esquema e um separador de pontos.

Se você especificar um job de vários destinos, o job será executado em todos os destinos. Nesse caso, o argumento use_current_session deve ser FALSE.

Proprietário

É o esquema no qual o job é executado.
Usar Sessão Atual

Especifica se a execução do job deve ou não ocorrer na mesma sessão da qual o procedimento foi chamado.

Quando use_current_session é definido como TRUE:

  • Você pode testar um job e ver possíveis erros na linha de comando.

  • O RUN pode ser executado em paralelo com uma execução de job programada regularmente.

Quando use_current_session é definido como FALSE:
  • É necessário verificar o log do job para localizar informações de erro.
  • Todos os campos relevantes em scheduler_jobs são atualizados.
  • RUN falhará se um job programado regularmente estiver em execução.
Options  

Procedimento STOP_JOB

Este procedimento interrompe a execução atual de jobs ou de todos os jobs em uma classe de job.

Após a interrupção do job, o estado de um job ocasional é definido como STOPPED, enquanto o estado de um job repetido é definido como SCHEDULED ou COMPLETED, dependendo de a próxima execução do job estar programada.

Sintaxe

dbms_data_tools_job.stop_job(
                     job_name in varchar2,
                     owner    in varchar2 default null,
                     force    in boolean  default false);

Parâmetros do Procedimento STOP_JOB

Tabela 22-8 Parâmetros do Procedimento STOP_JOB

Parâmetro Descrição
Nome do Job

Nome de um job a ser interrompido. É o nome de um job existente, opcionalmente precedido por um nome de esquema e separador de pontos.
Proprietário

É o esquema no qual o job deve ser interrompido.
Imposta

Se force estiver definido como FALSE, o Scheduler tentará interromper normalmente o job usando um mecanismo de interrupção. Esse método retorna o controle ao processo subordinado, que pode atualizar o status do job na fila de jobs para interrompido. Se isso falhar, um erro será retornado.

Se force for definido como TRUE, o Scheduler encerrará imediatamente o subordinado do job. A Oracle recomenda que STOP_JOB com imposição definida como TRUE seja usado somente após uma falha em STOP_JOB com force definida como FALSE.

O uso da opção force requer o privilégio de sistema MANAGE SCHEDULER.

Tópico principal: Referência do Pacote DBMS_DATA_TOOLS_JOBS