DBMS_CLOUD_NOTIFICATION 程序包

DBMS_CLOUD_NOTIFICATION 程序包允许您向提供程序发送消息或 SQL 查询的输出。

支持 DBMS_CLOUD_NOTIFICATION 的提供商包括：Email、Microsoft Teams、OCI Notifications (ONS) 和 Slack。

将 OCI Notifications 服务与 DBMS_CLOUD_NOTIFICATION 程序包结合使用时，仅支持 DBMS_CLOUD_NOTIFICATION.SEND_MESSAGE 过程（不支持 DBMS_CLOUD_NOTIFICATION.SEND_DATA 过程）。

Prerequisites

组管理员必须使用 NAT 网关配置出站连接，如下所述：

按照 Oracle Cloud Infrastructure 文档中的创建 NAT 网关中的说明，在自治 AI 数据库资源所在的虚拟云网络 (VCN) 中创建 NAT 网关。
创建 NAT 网关后，在自治 AI 数据库资源所在的 VCN 中添加路由规则和出站安全规则到每个子网，以便这些资源可以使用网关从 Azure AD 实例获取公钥：
1. 转到子网的 Subnet Details（子网详细信息）页面。
2. 在 Subnet Information（子网信息）选项卡中，单击子网的 Route Table（路由表）的名称以显示 Route Table Details（路由表详细信息）页面。
3. 在现有路由规则表中，检查是否已存在具有以下特征的规则：
  - 目标：0.0.0.0/0
  - 目标类型：NAT 网关
  - 目标：刚在 VCN 中创建的 NAT 网关的名称
  如果不存在此类规则，请单击添加路由规则并添加具有这些特征的路由规则。
4. 返回到子网的子网详细信息页面。
5. 在子网的安全列表表中，单击子网的安全列表的名称以显示其安全列表详细信息页。
6. 在侧边菜单的资源下，单击出站规则。
7. 在现有出站规则表中，检查是否已存在具有以下特征的规则：
  - 目标类型： CIDR
  - 目标：0.0.0.0/0
  - IP 协议： TCP
  - 源端口范围：443
  - 目标端口范围：全部
  如果不存在此类规则，请单击添加出站规则并添加具有这些特征的出站规则。

您的环境中的 HTTP 代理设置必须允许数据库访问云服务提供商。

这些设置由组管理员在创建 Exadata Cloud@Customer 基础结构时定义，如 Using the Console to Provision Exadata Database Service on Cloud@Customer 中所述。

注：只有在 Exadata 基础结构处于 Requires Activation 状态之前，才能编辑包括 HTTP 代理的网络配置。一旦激活，您就无法编辑这些设置。

为已预配的 Exadata 基础结构设置 HTTP 代理需要 My Oracle Support 中的服务请求 (SR)。有关详细信息，请参见在 My Oracle Support 中创建服务请求。

DBMS_CLOUD_NOTIFICATION 子程序概要

此表汇总了程序包中包含的子程序。

子程序	说明
SEND_DATA 过程	将 SQL 查询输出发送到提供程序。
SEND_MESSAGE 过程	将文本消息发送到提供商。

SEND_DATA 过程

SEND_DATA 过程将指定查询的结果发送到提供程序。

语法

DBMS_CLOUD_NOTIFICATION.SEND_DATA(
       provider           IN  VARCHAR2,
       credential_name    IN  VARCHAR2,
       query              IN  CLOB,
       params             IN  CLOB
 );

参数

Parameter (参数)	说明
`provider`	指定提供方。有效值为 '`email`'、'`msteams`' 和 '`slack`' 此参数是必需的。
`credential_name`	要访问提供程序的身份证明对象的名称。对于电子邮件提供程序，身份证明是 SMTP 批准发件人的身份证明的名称，其中包含其用户名和密码。对于 msteams 提供程序，凭证是凭证的名称。对于 Slack 提供程序，凭证的用户名必须为 `"SLACK_TOKEN"`，`password` 是 Slack 机器人令牌。此参数是必需的。
`query`	指定要运行的 SQL 查询。结果将发送到提供商。此参数是必需的。
`params`	以 JSON 格式指定 `provider` 的特定参数。对于提供程序类型 `email`，有效参数为： `sender`. 这以 `String` 值指定批准的发件人的电子邮件 ID。 `smtp_host`. 这将以 `String` 值指定 SMTP 主机名。 `subject`. 这以 `String` 值指定电子邮件的主题。最大大小为 100 个字符。 `recipient`. 这指定 `String` 值中收件人的电子邮件 ID。存在多个收件人时，在电子邮件 ID 之间使用逗号。 `to_cc`. 这将指定接收电子邮件抄送的电子邮件 ID。这是一个 `String` 值。存在多个抄送收件人时，在电子邮件 ID 之间使用逗号。 `to_bcc`. 这指定接收电子邮件密件抄送的电子邮件 ID。这是一个 `String` 值。存在多个密件抄送收件人时，在电子邮件 ID 之间使用逗号。 `message`. 这指定 `String` 值中的消息文本。 `type`. 这会将 `String` 值中的输出格式指定为 CSV 或 JSON。 `title`. 这指定 `String` 值中 SQL 输出的附件的标题。由于标题用于生成文件名，标题应仅包含字母、数字、下划线、连字符或点作为其值的字符。对于提供程序类型 `msteams`，有效参数为： `tenant`. 这将以 `String` 格式指定租户 ID。 `team`. 这以 `String` 格式指定团队 ID。 `channel`. 这以 `String` 格式指定通道 ID。 `title`. 这将以 `String` 格式指定文件的标题。最大大小为 50 个字符。 `type`. 这以 `String` 值指定输出格式。有效值为 CSV 或 JSON。对于提供程序类型 `slack`，有效参数为： `channel`. 这指定 `String` 值中的通道 ID。渠道 ID 是渠道的唯一 ID，与渠道名称不同。在 Slack 中，查看渠道详细信息时，可以在“关于”选项卡上找到渠道 ID。 `type`. 这以 `String` 值指定输出格式。有效值为 CSV 或 JSON。此参数是必需的。

使用说明

使用过程 DBMS_CLOUD.CREATE_CREDENTIAL(credential_name、username、password) 创建凭证对象。有关更多信息，请参见 CREATE_CREDENTIAL Procedure 。

对于 email 提供程序，用户需要电子邮件传送服务器的 SMTP 连接端点来获取 smtp_host。用户还需要 SMTP 批准的发件人及其凭证才能通过电子邮件传送服务器进行验证以获取 credential_name。必须配置 SMTP 连接，并且必须生成并批准 SMTP 凭证。
对于 msteams 提供程序，用户需要 Microsoft Teams 应用程序和其中配置的机器人。应用程序需要发布到组织，并在从管理中心获得管理员的批准后安装。用户还需要从其 Azure 门户访问 Graph API 的 Files.ReadWrite.All 和 ChannelSettings.Read.All 权限。要生成所需的令牌，用户需要在用户名中使用 bot_id，在密码中使用 bot_secret。为 Microsoft Teams 使用 DBMS_CLOUD_NOTIFICATION.SEND_DATA 时支持的最大文件大小为 4MB。
对于 slack 提供程序，username 值可以是任何有效字符串，password 是 Slack 机器人标记。

范例

使用 email 提供程序发送 SQL 输出：

BEGIN
    DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'EMAIL_CRED',
    username        => 'username',
    password        => 'password');
END;
/

BEGIN
   DBMS_CLOUD_NOTIFICATION.SEND_DATA(
        provider        => 'email',
        credential_name => 'EMAIL_CRED',
        query           => 'SELECT tablespace_name FROM dba_tablespaces',
        params          => json_object('recipient' value  'mark@oracle.com, suresh@oracle.com',
                                       'to_cc'  value 'nicole@oracle.com1, jordan@oracle.com',
                                       'to_bcc' value 'manisha@oracle.com',
                                       'subject' value 'Test subject',
                                       'type' value 'json',
                                       'title' value 'mytitle',
                                       'message' value 'This is the message',
                                       'smtp_host' value 'smtp.email.example.com',
                                       'sender'    value  'approver_sender@oracle.com' )
   );
   END;
/

使用 msteams 提供程序发送 SQL 输出：

BEGIN
    DBMS_CLOUD.CREATE_CREDENTIAL(credential_name => 'TEAMS_CRED',
        username        => '*bot_id*',
        password        => '*bot_secret*');
END;
/

BEGIN
     DBMS_CLOUD_NOTIFICATION.SEND_MESSAGE(provider => 'msteams',
        credential_name => 'TEAMS_CRED',
        query           => 'SELECT tablespace_name FROM dba_tablespaces',
        params          => json_object('tenant'value '5b743bc******c0286',
                                       'team'value '0ae401*********5d2bd',
                                       'channel'value '19%3a94be023*****%40thread.tacv2',
                                       'title'value 'today',
                                       'type'value 'csv'));
END;
/

使用 slack 提供程序发送 SQL 输出：

BEGIN
   DBMS_CLOUD.CREATE_CREDENTIAL(
     credential_name => 'SLACK_CRED',
     username        => 'SLACK_TOKEN',
     password        => 'password');
END;
/
BEGIN
  DBMS_CLOUD_NOTIFICATION.SEND_DATA(
      provider        => 'slack',
      credential_name => 'SLACK_CRED',
      query           => 'SELECT username, account_status, expiry_date FROM USER_USERS WHERE rownum < 5',
      params          => json_object('channel' value 'C0....08','type' value 'csv'));
END;
/

SEND_MESSAGE 过程

该过程将文本消息发送到提供程序。

语法

DBMS_CLOUD_NOTIFICATION.SEND_MESSAGE(
       provider           IN  VARCHAR2,
       credential_name    IN  VARCHAR2,
       message            IN  CLOB,
       params             IN  CLOB
 );

参数

Parameter (参数)	说明
`provider`	指定提供方。有效值包括：'`email`'、'`msteams`'、'`slack`' 和 '`oci`'。此参数是必需的。
`credential_name`	要访问提供程序的身份证明对象的名称。对于电子邮件提供程序，身份证明是 SMTP 批准发件人的身份证明的名称，其中包含其用户名和密码。对于 msteams 提供程序，身份证明必须在用户名和密码中包含 `bot_id` 和 `bot_secret` 密钥。对于 Slack 提供程序，凭证的用户名必须为 `"SLACK_TOKEN"`，`password` 是 Slack 机器人令牌。对于 `oci` 提供程序，身份证明是有效的 Oracle Cloud Infrastructure 签名基于密钥的身份证明。此参数是必需的。
`message`	指定消息文本。此参数是必需的。
`params`	以 JSON 格式指定 `provider` 的特定参数。对于提供程序类型 `email`，有效参数为： `sender`. 这以 `String` 值指定批准的发件人的电子邮件 ID。 `smtp_host`. 这将以 `String` 值指定 SMTP 主机名。 `subject`. 这以 `String` 值指定电子邮件的主题。最大大小为 100 个字符。 `recipient`. 这指定 `String` 值中收件人的电子邮件 ID。存在多个收件人时，在电子邮件 ID 之间使用逗号。 `to_cc`. 这将指定接收电子邮件抄送的电子邮件 ID。存在多个抄送收件人时，在电子邮件 ID 之间使用逗号。 `to_bcc`. 这指定接收电子邮件密件抄送的电子邮件 ID。存在多个密件抄送收件人时，在电子邮件 ID 之间使用逗号。对于提供程序类型 `msteams`，有效参数为： `channel`. 这指定 `String` 值中的通道 ID。对于提供程序类型 `slack`，有效参数为： `channel`. 这指定 `String` 值中的通道 ID。对于类型为 `oci` 的提供商 OCI Notifications，有效参数为： `topic_ocid`：指定 `title`：指定消息的主题行。使用 `oci` 提供程序时，消息可能有不同的端点，具体取决于订阅。对于不同的订阅，`title` 参数的处理方式不同：电子邮件：`title` 指定消息的主题行。 Slack：不使用 `title` 值。如果包含该值，则忽略该值。渠道 ID 是渠道的唯一 ID，与渠道名称不同。在 Slack 中，查看渠道详细信息时，可以在“关于”选项卡上找到渠道 ID。此参数是必需的。

使用说明

使用过程 DBMS_CLOUD.CREATE_CREDENTIAL(credential_name、username、password) 创建凭证对象。有关更多信息，请参见 CREATE_CREDENTIAL Procedure 。

对于 email 提供程序，用户需要电子邮件传送服务器的 SMTP 连接端点来获取 smtp_host。用户还需要 SMTP 批准的发件人及其凭证才能通过电子邮件传送服务器进行验证以获取 credential_name。必须配置 SMTP 连接，并且必须生成并批准 SMTP 凭证。
对于 msteams 提供程序，用户需要 Microsoft Teams 应用程序和其中配置的机器人。应用程序需要发布到组织，并在从管理中心获得管理员的批准后安装。用户还需要从其 Azure 门户访问 Graph API 的 Files.ReadWrite.All 和 ChannelSettings.Read.All 权限。要生成所需的令牌，用户需要在用户名中使用 bot_id，在口令中使用 bot_secret。
对于 slack 提供程序，username 值可以是任何有效字符串，password 是 Slack 机器人标记。
DBMS_CLOUD_NOTIFICATION 支持 OCI Notifications 提供商。有关 OCI 通知提供商的详细信息，请参阅通知概述。
- 要使用 OCI Notifications 提供程序，您必须执行以下操作：
  - 创建主题。有关创建主题的详细信息，请参阅创建主题
  - 创建必需的订阅。有关创建订阅的详细信息，请参阅创建订阅。
  - 创建订阅后，请确认订阅。消息仅发布到已确认的订阅。有关确认订阅的详细信息，请参见 Confirming a Subscription 。
- 自治 AI 数据库实例、身份证明（如果使用用户身份证明）和订阅主题必须都位于同一区域中。
- 请注意以下限制：
  - 消息大小限制：每个请求的消息大小限制为 64KB。不能在单个请求内发送或处理超过此大小的消息。
  - 消息传送速率限制：根据使用的协议，消息传送速率限制不同。
    - email 协议：限制为每个端点每分钟 10 条消息。
    此限制可能会影响消息的传输和接收速度。
  - 每分钟事务处理 (Transactions Per Minute，TPM) 限制：此操作的每个主题的 TPM 限制为 60。此限制表示可以针对给定主题处理或处理的最大每分钟消息数。超过此限制可能会导致消息未以较慢的速度进行处理或处理。

示例

向 email 提供程序发送一条短信：

BEGIN
    DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'EMAIL_CRED',
    username        => 'username',
    password        => 'password');
END;
/

BEGIN
   DBMS_CLOUD_NOTIFICATION.SEND_MESSAGE(
        provider        => 'email',
        credential_name => 'EMAIL_CRED',
        message         => 'Subject content',
        params          => json_object('recipient' value  'mark@oracle.com, suresh@oracle.com',
                                       'to_cc'  value 'nicole@oracle.com, jordan@oracle.com',
                                       'to_bcc' value 'manisha@oracle.com',
                                       'subject' value 'Test subject',
                                       'smtp_host' value 'smtp.email.example.com',
                                       'sender'    value  'approver_sender@oracle.com' )
   );
   END;
/

向 msteams 提供程序发送一条短信：

BEGIN
    DBMS_CLOUD.CREATE_CREDENTIAL(credential_name => 'TEAMS_CRED',
        username        => '*bot_id*',
        password        => '*bot_secret*');
END;
/

BEGIN
     DBMS_CLOUD_NOTIFICATION.SEND_MESSAGE(
        provider        => 'msteams',
        credential_name => 'TEAMS_CRED',
        message         => 'text from new teams api',
        params          => json_object('channel'value 'C0....08'),'region'value 'india');
END;
/

向 slack 提供程序发送一条短信：

BEGIN
   DBMS_CLOUD.CREATE_CREDENTIAL(
     credential_name => 'SLACK_CRED',
     username        => 'SLACK_TOKEN',
     password        => 'password');
END;
/
BEGIN
   DBMS_CLOUD_NOTIFICATION.SEND_MESSAGE(
      provider          => 'slack',
      credential_name   => 'SLACK_CRED',
      message           => 'Send text from Autonomous AI Database.',
      params            => json_object('channel' value 'C0....08'));
END;
/

向 OCI Notifications 发送一条短信，键入 oci Provider：

BEGIN
   DBMS_CLOUD_NOTIFICATION.SEND_MESSAGE(
      provider          => 'oci',
      credential_name  => 'OCI_CRED',
      message          => 'Text message for you.',
      params           => json_object('topic_ocid'  value 'oci********pa',
      'title'  value 'Title for message subject' ));
END;
/