DBE_SCHEDULER
接口介绍
高级功能包DBE_SCHEDULER支持通过调度(schedule)和程序(program)更加灵活的创建定时任务。支持的所有接口请见表1。
DBE_SCHEDULER尚不支持节点间同步定时任务,若要创建多节点定时任务请使用DBE_TASK接口实现。
接口名称 |
描述 |
---|---|
创建定时任务。 |
|
删除定时任务。 |
|
删除单个定时任务。 |
|
设置对象属性。 |
|
运行定时任务。 |
|
后台运行定时任务。 |
|
前台运行定时任务。 |
|
停止定时任务。 |
|
停止单个定时任务。 |
|
生成定时任务名。 |
|
创建程序。 |
|
定义程序参数。 |
|
删除程序。 |
|
删除单个程序。 |
|
设置定时任务参数值。 |
|
创建调度。 |
|
删除调度。 |
|
删除单个调度。 |
|
创建定时任务类。 |
|
删除定时任务类。 |
|
删除单个定时任务类。 |
|
赋予用户特殊权限。 |
|
撤销用户特殊权限。 |
|
创建证书。 |
|
销毁证书。 |
|
启用对象。 |
|
启用单个对象。 |
|
停用对象。 |
|
停用单个对象。 |
|
分析Calendar格式字符串。 |
|
分析Calendar格式字符串。 |
- DBE_SCHEDULER.CREATE_JOB
DBE_SCHEDULER.CREATE_JOB函数原型可以分为4种:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61
-- 内联调度和程序的定时任务 DBE_SCHEDULER.CREATE_JOB( job_name TEXT, job_type TEXT, job_action TEXT, number_of_arguments INTEGER DEFAULT 0, start_date TIMESTAMP WITH TIME ZONE DEFAULT NULL, repeat_interval TEXT DEFAULT NULL, end_date TIMESTAMP WITH TIME ZONE DEFAULT NULL, job_class TEXT DEFAULT 'DEFAULT_JOB_CLASS', enabled BOOLEAN DEFAULT FALSE, auto_drop BOOLEAN DEFAULT TRUE, comments TEXT DEFAULT NULL, credential_name TEXT DEFAULT NULL, destination_name TEXT DEFAULT NULL ) -- 引用创建好的调度和程序的定时任务 DBE_SCHEDULER.CREATE_JOB( job_name TEXT, program_name TEXT, schedule_name TEXT, job_class TEXT DEFAULT 'DEFAULT_JOB_CLASS', enabled BOOLEAN DEFAULT FALSE, auto_drop BOOLEAN DEFAULT TRUE, comments TEXT DEFAULT NULL, job_style TEXT DEFAULT 'REGULAR', credential_name TEXT DEFAULT NULL, destination_name TEXT DEFAULT NULL ) -- 引用创建好的程序,内联调度的定时任务 DBE_SCHEDULER.CREATE_JOB( job_name text, program_name TEXT, start_date TIMESTAMP WITH TIME ZONE DEFAULT NULL, repeat_interval TEXT DEFAULT NULL, end_date TIMESTAMP WITH TIME ZONE DEFAULT NULL, job_class TEXT DEFAULT 'DEFAULT_JOB_CLASS', enabled BOOLEAN DEFAULT FALSE, auto_drop BOOLEAN DEFAULT TRUE, comments TEXT DEFAULT NULL, job_style TEXT DEFAULT 'REGULAR', credential_name TEXT DEFAULT NULL, destination_name TEXT DEFAULT NULL ) -- 引用创建好的调度,内联程序的定时任务 DBE_SCHEDULER.CREATE_JOB( job_name TEXT, schedule_name TEXT, job_type TEXT, job_action TEXT, number_of_arguments INTEGER DEFAULT 0, job_class TEXT DEFAULT 'DEFAULT_JOB_CLASS', enabled BOOLEAN DEFAULT FALSE, auto_drop BOOLEAN DEFAULT TRUE, comments TEXT DEFAULT NULL, credential_name TEXT DEFAULT NULL, destination_name TEXT DEFAULT NULL )
利用DBE_SCHEDULER创建的定时任务不会与DBE_TASK中的定时任务相冲突。
DBE_SCHEDULER创建的定时任务会生成对应的job_id,但是在使用过程中这个id并没有实际意义。
表2 DBE_SCHEDULER.CREATE_JOB接口参数说明 参数
类型
入参/出参
是否可以为空
描述
job_name
text
IN
否
定时任务名称。
job_type
text
IN
否
定时任务内联程序类型,可用类型为:- 'PLSQL_BLOCK':匿名存储过程快。
- 'STORED_PROCEDURE':保存的存储过程。
- 'EXTERNAL_SCRIPT':外部脚本。
job_action
text
IN
否
定时任务内联程序执行内容。
number_of_arguments
integer
IN
否
定时任务内联程序参数个数。
program_name
text
IN
否
定时任务引用程序名称。
start_date
timestamp with time zone
IN
是
定时任务内联调度起始时间。
repeat_interval
text
IN
是
定时任务内联调度任务周期。
end_date
timestamp with time zone
IN
是
定时任务内联调度失效时间。
schedule_name
text
IN
否
定时任务引用调度名称。
job_class
text
IN
否
定时任务类名。
enabled
boolean
IN
否
定时任务启用状态。
auto_drop
boolean
IN
否
定时任务自动删除。
comments
text
IN
是
备注。
job_style
text
IN
否
定时任务行为模式,仅支持‘REGULAR'。
credential_name
text
IN
是
定时任务证书名。
destination_name
text
IN
是
定时任务目标名。
示例:1 2 3
CALL DBE_SCHEDULER.create_job(job_name=>'job1', program_name=>'program1', schedule_name=>'schedule1'); CALL DBE_SCHEDULER.create_job(job_name=>'job1', job_type=>'STORED_PROCEDURE', job_action=>'select pg_sleep(1);'); CALL DBE_SCHEDULER.create_job('job1', 'program1', '2021-07-20', 'interval ''3 minute''', '2121-07-20', 'DEFAULT_JOB_CLASS', false, false,'test', 'style', NULL, NULL);
创建'EXTERNAL_SCRIPT'类型的定时任务需要管理员赋予相关的权限和证书,且需要数据库启动用户对该外部脚本有读取权限才可以正常生效。
- DBE_SCHEDULER.DROP_JOB
DBE_SCHEDULER.DROP_JOB函数原型为:
1 2 3 4 5 6
DBE_SCHEDULER.drop_job( job_name text, force boolean default false, defer boolean default false, commit_semantics text default 'STOP_ON_FIRST_ERROR' )
DBE_SCHEDULER.DROP_JOB可以指定一个、多个任务,或指定任务类进行定时任务删除。
表3 DBE_SCHEDULER.DROP_JOB接口参数说明 参数
类型
入参/出参
是否可以为空
描述
job_name
text
IN
否
定时任务或定时任务类名称,可以指定一个或多个,当指定多个定时任务时需要利用逗号隔开
force
boolean
IN
否
删除定时任务行为标记位
true:尝试先停止当前定时任务,再进行删除
false:如果定时任务正在运行会删除失败
defer
boolean
IN
否
删除定时任务行为标记位
true:允许定时任务完成后再进行删除
commit_semantics
text
IN
否
提交规则:
'STOP_ON_FIRST_ERROR':在第一个报错之前的删除操作会提交
'TRANSACTIONAL':事物级提交,报错前的删除操作会回滚
'ABSORB_ERRORS':尝试越过报错,将成功的删除操作提交
示例:1
CALL DBE_SCHEDULER.drop_job('job1', true, false, 'STOP_ON_FIRST_ERROR');
commit_semantic中的'TRANSACTIONAL'选项必须在force为false的情况下才会生效。
- DBE_SCHEDULER.DROP_SINGLE_JOB
DBE_SCHEDULER.DROP_SINGLE_JOB函数原型为:
1 2 3 4 5
DBE_SCHEDULER.drop_single_job( job_name text, force boolean default false, defer boolean default false )
- DBE_SCHEDULER.SET_ATTRIBUTE
DBE_SCHEDULER.SET_ATTRIBUTE函数4种原型为:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
DBE_SCHEDULER.set_attribute( name text, attribute text, value boolean ) DBE_SCHEDULER.set_attribute( name text, attribute text, value text ) DBE_SCHEDULER.set_attribute( name text, attribute text, value timestamp ) DBE_SCHEDULER.set_attribute( name text, attribute text, value timestamp with time zone ) DBE_SCHEDULER.set_attribute( name text, attribute text, value text, value2 text default NULL )
name在这里可以指定任何DBE_SCHEDULE内部的对象。
表4 DBE_SCHEDULER.SET_ATTRIBUTE接口参数说明 参数
类型
入参/出参
是否可以为空
描述
name
text
IN
否
对象名。
attribute
text
IN
否
属性名。
value
boolean/date/timestamp/timestamp with time zone/text
IN
否
属性值,可选属性如下:- 定时任务相关:job_type, job_action, number_of_arguments, start_date, repeat_interval, end_date, job_class, enabled, auto_drop, comments, credential_name, destination_name, program_name, schedule_name, job_style。
- 程序相关:program_action, program_type, number_of_arguments, comments。
- 调度相关:start_date, repeat_interval, end_date, comments。
value2
text
IN
是
额外属性值。保留参数位,目前尚不支持拥有额外属性值的目标属性。
示例:1 2
CALL DBE_SCHEDULER.set_attribute('program1', 'number_of_arguments', 0); CALL DBE_SCHEDULER.set_attribute('program1', 'program_type', 'STORED_PROCEDURE');
不要使用DBE_SCHEDULER.SET_ATTRIBUTE来将参数置空。
对象名不能通过DBE_SCHEDULER.SET_ATTRIBUTE来更改。
内联对象不能通过DBE_SCHEDULER.SET_ATTRIBUTE来更改。
- DBE_SCHEDULER.RUN_JOB
DBE_SCHEDULER.RUN_JOB函数原型为:
1 2 3 4
DBE_SCHEDULER.run_job( job_name text, use_current_session boolean default true )
DBE_SCHEDULER.RUN_JOB主要用于立即运行定时作业,独立于定时任务本身的调度,甚至可以同时运行。
表5 DBE_SCHEDULER.RUN_JOB接口参数说明 参数
类型
入参/出参
是否可以为空
描述
job_name
text
IN
否
定时任务名称,可以指定一个或多个,当指定多个定时任务时需要利用逗号隔开。
use_current_session
boolean
IN
否
运行定时任务标志位:- true:使用当前会话运行,主要用于查看定时任务是否可以正常运行。
- false:后台拉起定时任务,运行结果会打印到日志中。
示例:1
CALL DBE_SCHEDULER.run_job('job1', false);
use_current_session目前只作用于job_type为'EXTERNAL_SCRIPT'的定时任务上。
- DBE_SCHEDULER.RUN_BACKEND_JOB
DBE_SCHEDULER.RUN_BACKEND_JOB函数原型为:
1 2 3
DBE_SCHEDULER.run_backend_job( job_name text )
- DBE_SCHEDULER.RUN_FOREGROUND_JOB
仅支持运行external 类型任务。
返回值:text。
DBE_SCHEDULER.RUN_FOREGROUND_JOB函数原型为:
1 2 3
DBE_SCHEDULER.run_foreground_job( job_name text )return text
- DBE_SCHEDULER.STOP_JOB
DBE_SCHEDULER.STOP_JOB函数原型为:
1 2 3 4 5
DBE_SCHEDULER.stop_job( job_name text, force boolean default false, commit_semantics text default 'STOP_ON_FIRST_ERROR' )
表6 DBE_SCHEDULER.STOP_JOB接口参数说明 参数
类型
入参/出参
是否可以为空
描述
job_name
text
IN
否
定时任务或定时任务类名称,可以指定一个或多个,当指定多个定时任务时需要利用逗号隔开。
force
boolean
IN
否
删除定时任务行为标记位:- true:调度器会发送终止信号立即结束任务线程。
- false:调度器会尝试利用打断信号终止定时任务线程。
commit_semantics
text
IN
否
提交规则:- 'STOP_ON_FIRST_ERROR':在第一个报错之前的打断操作会提交。
- 'ABSORB_ERRORS':尝试越过报错,将成功的打断操作提交。
- DBE_SCHEDULER.STOP_SINGLE_JOB
DBE_SCHEDULER.STOP_SINGLE_JOB函数原型为:
1 2 3 4
DBE_SCHEDULER.stop_single_job( job_name text, force boolean default false )
- DBE_SCHEDULER.GENERATE_JOB_NAME
DBE_SCHEDULER.GENERATE_JOB_NAME函数原型为:
1 2 3
DBE_SCHEDULER.generate_job_name( prefix text default 'JOB$_' )return text
表7 DBE_SCHEDULER.GENERATE_JOB_NAME接口参数说明 参数
类型
入参/出参
是否可以为空
描述
prefix
text
IN
否
生成名称的前缀,默认为'JOB$_',反复执行生成的定时任务名为:
job$_1, job$_2, job$_3 ...
首次执行DBE_SCHEDULER.GENERATE_JOB_NAME会在public下创建一个临时序列用于保存当前名称的序号。由于普通用户没有在public下create权限,因此如果普通用户为当前db下第一次调用该函数,会失败,需要授权该普通用户在public下的create权限,或者使用有该权限的用户调用该接口以创建临时序列。
- DBE_SCHEDULER.CREATE_PROGRAM
DBE_SCHEDULER.CREATE_PROGRAM函数原型为:
1 2 3 4 5 6 7 8
DBE_SCHEDULER.create_program( program_name text, program_type text, program_action text, number_of_arguments integer default 0, enabled boolean default false, comments text default NULL )
- DBE_SCHEDULER.DEFINE_PROGRAM_ARGUMENT
修正带默认值default_value字段的接口默认转换成小写行为,现字符大小写做出区分。
DBE_SCHEDULER.DEFINE_PROGRAM_ARGUMENT函数原型为:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
DBE_SCHEDULER.define_program_argument( program_name text, argument_position integer, argument_name text default NULL, argument_type text, out_argument boolean default false ) -- 带有默认值 -- DBE_SCHEDULER.define_program_argument( program_name text, argument_position integer, argument_name text default NULL, argument_type text, default_value text, out_argument boolean default false )
- DBE_SCHEDULER.DROP_PROGRAM
DBE_SCHEDULER.DROP_PROGRAM函数原型为:
1 2 3 4
DBE_SCHEDULER.drop_program( program_name text, force boolean default false )
- DBE_SCHEDULER.DROP_SINGLE_PROGRAM
DBE_SCHEDULER.DROP_SINGLE_PROGRAM函数原型为:
1 2 3 4
DBE_SCHEDULER.drop_single_program( program_name text, force boolean default false )
- DBE_SCHEDULER.SET_JOB_ARGUMENT_VALUE
设置定时任务参数值。argument_value字段支持赋空入参。
DBE_SCHEDULER.SET_JOB_ARGUMENT_VALUE函数原型为:
1 2 3 4 5 6 7 8 9 10 11
DBE_SCHEDULER.set_job_argument_value( job_name text, argument_position integer, argument_value text ) DBE_SCHEDULER.set_job_argument_value( job_name text, argument_name text, argument_value text )
- DBE_SCHEDULER.CREATE_SCHEDULE
DBE_SCHEDULER.CREATE_SCHEDULE函数原型为:
1 2 3 4 5 6 7
DBE_SCHEDULER.create_schedule( schedule_name text, start_date timestamp with time zone default NULL, repeat_interval text, end_date timestamp with time zone default NULL, comments text default NULL )
- DBE_SCHEDULER.DROP_SCHEDULE
DBE_SCHEDULER.DROP_SCHEDULE函数原型为:
1 2 3 4
DBE_SCHEDULER.drop_schedule( schedule_name text, force boolean default false )
- DBE_SCHEDULER.DROP_SINGLE_SCHEDULE
DBE_SCHEDULER.DROP_SINGLE_SCHEDULE函数原型为:
1 2 3 4
DBE_SCHEDULER.drop_single_schedule( schedule_name text, force boolean default false )
- DBE_SCHEDULER.CREATE_JOB_CLASS
DBE_SCHEDULER.CREATE_JOB_CLASS函数原型为:
1 2 3 4 5 6 7 8
DBE_SCHEDULER.create_job_class( job_class_name text, resource_consumer_group text default NULL, service text default NULL, logging_level integer default 0, log_history integer default NULL, comments text default NULL )
- DBE_SCHEDULER.DROP_JOB_CLASS
DBE_SCHEDULER.DROP_JOB_CLASS函数原型为:
1 2 3 4
DBE_SCHEDULER.drop_job_class( job_class_name text, force boolean default false )
- DBE_SCHEDULER.DROP_SINGLE_JOB_CLASS
DBE_SCHEDULER.DROP_SINGLE_JOB_CLASS函数原型为:
1 2 3 4
DBE_SCHEDULER.drop_single_job_class( job_class_name text, force boolean default false )
- DBE_SCHEDULER.GRANT_USER_AUTHORIZATION
为数据库用户提供定时任务权限。调用该函数的用户需要具有SYSADMIN权限。
DBE_SCHEDULER.GRANT_USER_AUTHORIZATION函数原型为:
1 2 3 4
DBE_SCHEDULER.grant_user_authorization( username text, privilege text )
- DBE_SCHEDULER.REVOKE_USER_AUTHORIZATION
撤销数据库用户的定时任务权限。调用该函数的用户需要具有SYSADMIN权限。
DBE_SCHEDULER.REVOKE_USER_AUTHORIZATION函数原型为:
1 2 3 4
DBE_SCHEDULER.revoke_user_authorization( username text, privilege text )
- DBE_SCHEDULER.CREATE_CREDENTIAL
创建授权证书。调用该函数的用户需要具有SYSADMIN权限。
DBE_SCHEDULER.CREATE_CREDENTIAL函数原型为:
1 2 3 4 5 6 7 8
DBE_SCHEDULER.create_credential( credential_name text, username text, password text default NULL, database_role text default NULL, windows_domain text default NULL, comments text default NULL )
DBE_SCHEDULER.CREATE_CREDENTIAL的password字段请传NULL或者'******',该参数仅做兼容性,不代表实际含义。禁止使用安装用户对应的os用户名创建证书。
- DBE_SCHEDULER.DROP_CREDENTIAL
销毁授权证书。调用该函数的用户需要具有SYSADMIN权限。
DBE_SCHEDULER.DROP_CREDENTIAL函数原型为:
1 2 3 4
DBE_SCHEDULER.drop_credential( credential_name text, force boolean default false )
- DBE_SCHEDULER.ENABLE
DBE_SCHEDULER.ENABLE函数原型为:
1 2 3 4
DBE_SCHEDULER.enable( name text, commit_semantics text default 'STOP_ON_FIRST_ERROR' )
- DBE_SCHEDULER.ENABLE_SINGLE
DBE_SCHEDULER.ENABLE_SINGLE函数原型为:
1 2 3
DBE_SCHEDULER.enable_single( name text )
- DBE_SCHEDULER.DISABLE
禁用多个对象,name为逗号分隔的字符串,每个逗号分隔的字符串为一个对象。
DBE_SCHEDULER.DISABLE函数原型为:
1 2 3 4 5
DBE_SCHEDULER.disable( name text, force boolean default false, commit_semantics text default 'STOP_ON_FIRST_ERROR' )
- DBE_SCHEDULER.DISABLE_SINGLE
DBE_SCHEDULER.DISABLE_SINGLE函数原型为:
1 2 3 4
DBE_SCHEDULER.disable_single( name text, force boolean default false )
- DBE_SCHEDULER.EVAL_CALENDAR_STRING
返回值类型:timestamp with time zone
DBE_SCHEDULER.EVAL_CALENDAR_STRING函数原型为:
1 2 3 4 5
DBE_SCHEDULER.evaluate_calendar_string( IN calendar_string text, IN start_date timestamp with time zone, IN return_date_after timestamp with time zone )return timestamp with time zone
- DBE_SCHEDULER.EVALUATE_CALENDAR_STRING
DBE_SCHEDULER.EVALUATE_CALENDAR_STRING函数原型为:
1 2 3 4 5 6
DBE_SCHEDULER.evaluate_calendar_string( IN calendar_string text, IN start_date timestamp with time zone, IN return_date_after timestamp with time zone, OUT next_run_date timestamp with time zone )return timestamp with time zone