DBMS_DATA_TOOLS_JOBS 程序包参考

本章提供有关在 Data Studio 中与作业功能一起使用的软件包的信息。DBMS_DATA_TOOLS_JOBS 子程序摘要主题还介绍了 DBMS_DATA_TOOLS_JOBS 程序包中包含的过程。

主题：

DBMS_DATA_TOOLS_JOB 子程序概要

• DBMS_DATA_TOOLS_JOB 过程

• DBMS_DATA_TOOLS_JOB 子程序摘要
  DBMS_DATA_TOOLS_JOB 程序包提供了用于 Data Studio 工具套件中作业功能的调度函数和过程的集合。

DBMS_DATA_TOOLS_JOB 子程序概要

DBMS_DATA_TOOLS_JOB 软件包提供与 Data Studio 工具套件中的作业功能一起使用的调度函数和过程的集合。

DBMS_DATA_TOOLS_JOB 程序包子程序

下表列出了 DBMS_DATA_TOOLS_JOB 子程序并简要介绍了这些子程序。

表 22-2 DBMS_DATA_TOOLS_JOB 子程序的姓名和说明

子程序	说明
创建作业过程	此过程将创建新作业。
删除作业过程	从调度程序中删除作业。
重命名作业过程	使用所需的名称重命名作业。
更新作业过程	修改现有作业的属性。
运行过程	无论您定义了什么计划，都立即运行作业。
停止作业过程	停止正在运行的作业。这样可以正常终止作业，如果需要，可以强制停止该作业。

安全注意事项

不要将敏感数据（如密钥、持有人令牌、密码、私钥、签名 URL 或其他凭证）直接放置在作业步骤 URL、请求主体或报告配置中。这些值可以随职务定义一起存储，然后检索。使用数据库身份证明或命名的身份证明进行验证。

CREATE_JOB 过程

此过程将创建一个作业。如果通过将已启用属性设置为 TRUE 来创建已启用的作业，则调度程序会根据其调度自动运行作业。如果禁用创建作业，则在您使用“启用作业”功能启用该作业之前，该作业不会运行。

语法

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

CREATE_JOB 过程参数

表 22-3 CREATE_JOB 过程参数

Parameter (参数)	说明
作业名称	要分配给作业的名称。如果未指定 job_name，则会生成错误。
说明	这是指为职务设置的其他信息。
步骤	这是指 Data Studio 工具所执行的包含作业的各种任务。 Steps 是一个 JSON 数组。每个数组元素都是 JSON 对象。以下是适用于所有对象的 JSON 元素： type - string，声明所执行的步骤的类型：data_load，smart_table，procedure，http。 on_errors- 字符串 stop：如果遇到错误，作业将停止并引发错误。 continue：将记录错误，但继续处理下一个作业步骤。 step_name- 要在日志中显示的步骤的说明性名称 每个对象类型都有一些其他元素，具体取决于类型。 data_load: data_load_name -（必需）要运行的以前创建的数据加载的名称 smart_table: recipe_name-（必需）要运行的以前创建的智能表配方的名称。 url -（必需的）要连接到的 REST URL。 method - GET（默认值）、POST、PUT、DELETE 或其他一些 HTTP 动词 procedure： procedure- 要执行的过程（必需）名称。它可以是模式限定，也可以是裸机过程或程序包方法。 arguments - 要提供给过程的字符串、数字或布尔参数数组。 注意： 对于 HTTP 步骤，请勿在 URL 或请求正文中放置敏感数据。使用数据库身份证明或命名的身份证明进行验证。
所有者	它是在其中创建作业的方案。如果在未指定方案的情况下创建作业，则所有者将是执行 CREATE_JOB 过程的用户。
开始日期	此属性指定计划开始此作业的第一个日期和时间。如果 start_date 和 repeat_interval 留空，则作业计划在启用作业后立即运行。 对于使用日历表达式指定重复间隔的重复作业，start_date 用作参考日期。作业第一次运行是当前日期和时间等于或迟于当前日期和时间的日历表达式的第一个匹配项。 调度程序无法保证作业在确切的时间执行，因为系统可能超载，因此资源不可用。
重复时间间隔	此属性指定窗口重复的频率。它使用调度程序日历语法来表示。有关详细信息，请参阅计算语法。 PL/SQL 表达式不能用于指定窗口的重复间隔。 通过对该表达式求值可以确定窗口下次打开的时间。如果未指定 repeat_interval，则该窗口在指定的开始日期仅打开一次。
结束日期	此属性指定作业过期且不再运行的日期和时间。 end_date 的值必须晚于 start_date 的值。如果 end_date 小于 start_date，则将生成错误。如果 end_date 与 start_date 相同，则不会执行作业，也不会生成错误。 如果未指定 end_date 的值，除非您指定 stop job，否则作业将永远重复。
作业类	与此作业关联的类。
是否启用?	此属性指定是否已启用创建作业。可能的设置是 TRUE 或 FALSE。默认情况下，此属性设置为 FALSE，因此，将作业创建为已禁用。禁用的作业表示已捕获有关作业的元数据，并且作业作为数据库对象存在。但是，调度程序会忽略作业，并且作业协调程序不会将其选取进行处理。要使作业协调程序处理作业，必须启用作业。可以通过选择 Enable Job 图标来启用作业。
报告	此属性通过“作业”功能中的“报表”按钮指定作业执行详细信息。 这是一个 JSON 对象，类似于 dbms_live_feed 的报告参数。它可以具有以下元素： completed：作业完成时要通知的目标。 errors：当某个作业步骤遇到错误时要通知的目标。 failed：当作业在步骤上下文之外出现致命错误时要通知的目标。 long：作业长时间运行时要通知的目标。 这四个元素中的每个元素都可以在 smtp 元素中指定电子邮件地址数组，或者在 slack 元素中指定松弛通道。long 元素可以具有 max_runtime_seconds 元素，用于确定作业在被视为运行过 long 之前必须运行多长时间。 注意： 请勿在报告配置中包括敏感数据。

DELETE_JOB 过程

此过程将删除作业。

语法

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

DELETE_JOB 过程参数

表 22-4 DELETE_JOB 过程参数

Parameter (参数)	说明
作业名称	要分配给作业的名称。如果未指定 job_name，则会生成错误。
所有者	它是在其中创建作业的方案。如果在未指定方案的情况下创建作业，则所有者将是执行 CREATE_JOB 过程的用户。

RENAME_JOB 过程

此过程将重命名作业。

语法

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

RENAME_JOB 过程参数

表 22-5 RENAME_JOB 过程参数

Parameter (参数)	说明
旧作业名	现有作业的名称。
新作业名	新作业名称。
所有者	它是在其中创建作业的方案。

UPDATE_JOB 过程

此过程将更新任何现有作业属性。

语法

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

UPDATE_JOB 过程参数

表 22-6 UPDATE_JOB 过程参数

Parameter (参数)	说明
作业名称	要更新的作业的名称。
所有者	它是在其中更新作业的方案。
说明	要应用的更新说明。
步骤	要更新的新步骤。 注意： 对于 HTTP 步骤，请勿在 URL 或请求正文中放置敏感数据。使用数据库身份证明或命名的身份证明进行验证。
开始日期	新起始日期。
重复时间间隔	更新的重复间隔。
结束日期	更新后的结束日期。
作业类	更新的作业类。
是否启用?	可以启用或禁用它。
报告	更新的报告属性。 注意： 请勿在报告配置中包括敏感数据。

运行过程

此过程会立即运行作业。

如果作业已启用，调度程序将自动运行该作业。无需调用 RUN_JOB 以根据作业调度运行作业。使用 RUN_JOB 可在其正常调度之外运行作业。

语法

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

RUN 过程参数

表 22-7 RUN 过程参数

Parameter (参数)	说明
作业名称	作业名称或以逗号分隔的条目列表，其中每个作业是现有作业的名称，前面可以选择带有方案名称和点分隔符。 如果指定一个多目标作业，该作业将在所有目标上运行。在这种情况下，use_current_session 参数必须为 FALSE。
所有者	它是在其中运行作业的方案。
使用当前会话	这指定作业运行是否应发生在调用该过程的同一会话中。 当 use_current_session 设置为 TRUE 时： 您可以测试作业，并在命令行中查看任何可能的错误。 RUN 可以与定期调度的作业运行并行运行。 将 use_current_session 设置为 FALSE 时： 您需要检查作业日志以查找错误信息。 将更新 scheduler_jobs 中的所有相关字段。 如果定期调度的作业正在运行，则 RUN 将失败。
选项

STOP_JOB 过程

此过程将停止当前正在运行的作业或作业类中的所有作业。

停止作业后，一次性作业的状态将设置为 STOPPED，而重复作业的状态将设置为 SCHEDULED 或 COMPLETED，具体取决于作业的下次运行是否已调度。

语法

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

STOP_JOB 过程参数

表 22-8 STOP_JOB 过程参数

Parameter (参数)	说明
作业名称	要停止的作业的名称。它是现有作业的名称，可以选择在前面加上方案名称和点分隔符。
所有者	它是要在其中停止作业的方案。
强制	如果 force 设置为 FALSE，调度程序将尝试使用中断机制正常停止作业。此方法将控制权返还给从属进程，该进程可以将作业队列中的作业状态更新为已停止。如果失败，将返回错误。 如果 force 设置为 TRUE，调度程序将立即终止作业从属服务器。Oracle 建议仅在将 force 设置为 FALSE 的 STOP_JOB 失败后才使用强制设置为 TRUE 的 STOP_JOB。 使用 force 选项需要 MANAGE SCHEDULER 系统特权。