Pacote DBMS_CLOUD_NOTIFICATION

O pacote DBMS_CLOUD_NOTIFICATION permite que você envie mensagens ou a saída de uma consulta SQL para um provedor.

Os provedores suportados com DBMS_CLOUD_NOTIFICATION são: E-mail, Microsoft Teams, OCI Notifications (ONS) e Slack.

Quando você usa o serviço OCI Notifications com o pacote DBMS_CLOUD_NOTIFICATION, só há suporte para o procedimento DBMS_CLOUD_NOTIFICATION.SEND_MESSAGE (o procedimento DBMS_CLOUD_NOTIFICATION.SEND_DATA não é suportado).

Uma conectividade de saída deve ter sido configurada usando um gateway NAT, pelo administrador da frota, conforme descrito abaixo:

Crie um gateway NAT na VCN (Virtual Cloud Network) em que seus recursos do Autonomous AI Database residem seguindo as instruções em Criar um Gateway NAT na Documentação do Oracle Cloud Infrastructure.
Após criar o gateway NAT, adicione uma regra da rota e uma regra da segurança da saída a cada sub-rede (na VCN) na qual os recursos do Autonomous AI Database residem para que esses recursos possam usar o gateway para obter a chave pública da sua instância doAzure AD
1. Vá para a página Detalhes de Sub-rede da sub-rede.
2. Na guia Informações da Sub-rede, clique no nome da Tabela da Rota da sub-redes para exibir sua página Detalhes da Tabela de Roteamento.
3. Na tabela de Regras de Rota existentes, verifique se já existe uma regra com as seguintes características:
  - Destino: 0.0.0.0/0
  - Target Type: Gateway NAT
  - Destino: O nome do gateway NAT que você acaba de criar na VCN
  Se essa regra não existir, clique em Adicionar Regras de Roteamento e adicione uma regra de roteamento com essas características.
4. Retorne à página Detalhes da Subrede da sub-rede.
5. Na tabela Listas de Segurança da sub‑rede, clique no nome da lista da sub‑rede para exibir sua página Detalhes da Lista de Segurança.
6. No menu lateral, em Recursos, clique em Regras de Saída.
7. Na tabela de Regras de Saída existentes, verifique se já existe uma regra com as seguintes características:
  - Tipo de Destino:CIDR
  - Destino:0.0.0.0/0
  - Protocolo IP:TCP
  - Faixa de Portas de Origem:443
  - Intervalo de Portas de Destino:Tudo
  Se essa regra não existir, clique em Adicionar Regras de Saída e adicione uma regra de saída com essas características.

As definições de Proxy HTTP em seu ambiente devem permitir que o banco de dados acesse o provedor de serviços em nuvem.

Essas definições são definidas pelo administrador da frota ao criar a infraestrutura do Exadata Cloud@Customer conforme descrito em Usando a Console para Provisionar o Exadata Database Service on Cloud@Customer.

Observação: A configuração de rede, incluindo o Proxy HTTP, só poderá ser editada até que o Exadata Infrastructure esteja no estado Exige Ativação. Uma vez ativado, você não pode editar essas configurações.

A configuração de um Proxy HTTP para uma Infraestrutura do Exadata já provisionada precisa de uma Solicitação de Serviço (SR) no My Oracle Support. Consulte Criar uma Solicitação de Serviço no My Oracle Support para obter detalhes.

Resumo dos Subprogramas DBMS_CLOUD_NOTIFICATION

Esta tabela resume os subprogramas incluídos no pacote.

Subprograma	Descrição
Procedimento SEND_DATA	Enviar saída de consulta SQL para um provedor.
Procedimento SEND_MESSAGE	Enviar uma mensagem de texto para um provedor.

Procedimento SEND_DATA

O procedimento SEND_DATA envia os resultados da consulta especificada para um provedor.

Sintaxe

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

Parâmetros

Parâmetro	Descrição
`provider`	Especifica o provedor. Os valores válidos são: '`email`', '`msteams`' e '`slack`' Este parâmetro é obrigatório.
`credential_name`	O nome do objeto de credencial para acessar o provedor. Para o provedor de e-mail, a credencial é o nome da credencial do remetente aprovado pelo SMTP que contém seu nome de usuário e senha. Para o provedor msteams, a credencial é o nome da credencial. Para o provedor do Slack, o nome de usuário da credencial deve ser `"SLACK_TOKEN"` e o `password` é o Token de Bot do Slack. Este parâmetro é obrigatório.
`query`	Especifica a consulta SQL a ser executada. Os resultados são enviados ao provedor. Este parâmetro é obrigatório.
`params`	Especifica parâmetros específicos para o `provider` no formato JSON. Para o tipo de provedor `email`, os parâmetros válidos são: `sender`. Especifica o ID do E-mail do remetente aprovado em um valor `String`. `smtp_host`. Especifica o nome do host SMTP em um valor `String`. `subject`. Especifica o assunto do e-mail em um valor `String`. O tamanho máximo é de 100 caracteres. `recipient`. Especifica os IDs de e-mail dos destinatários em um valor `String`. Use uma vírgula entre os IDs de e-mail quando houver vários destinatários. `to_cc`. Especifica os IDs de e-mail que estão recebendo um CC do e-mail. É um valor `String`. Use uma vírgula entre os IDs de e-mail quando houver vários destinatários CC. `to_bcc`. Especifica os IDs de e-mail que estão recebendo um Cco do e-mail. É um valor `String`. Use uma vírgula entre os IDs de e-mail quando houver vários destinatários com Cco. `message`. Especifica o texto da mensagem em um valor `String`. `type`. Especifica o formato de saída em um valor `String` como CSV ou JSON. `title`. Especifica o título do anexo da saída SQL em um valor `String`. O título deve conter apenas letras, dígitos, sublinhados, hifens ou pontos como caracteres em seu valor devido ao uso para gerar um nome de arquivo. Para o tipo de provedor `msteams`, os parâmetros válidos são: `tenant`. Especifica o ID do tenant em um formato `String`. `team`. Especifica o ID da equipe em um formato `String`. `channel`. Especifica o ID do canal em um formato `String`. `title`. Especifica o título do arquivo em um formato `String`. O tamanho máximo é 50 caracteres. `type`. Especifica o formato de saída em um valor `String`. Os valores válidos são CSV ou JSON. Para o tipo de provedor `slack`, os parâmetros válidos são: `channel`. Especifica o ID do Canal em um valor `String`. O ID do Canal é um ID exclusivo de um canal e é diferente do nome do canal. No Slack, quando você exibe os detalhes do canal, pode encontrar o ID do Canal na guia "Sobre". `type`. Especifica o formato de saída em um valor `String`. Os valores válidos são CSV ou JSON. Este parâmetro é obrigatório.

Observações sobre Uso

Use o procedimento DBMS_CLOUD.CREATE_CREDENTIAL(credential_name, username, password) para criar o objeto de credencial. Consulte Procedimento CREATE_CREDENTIAL para obter mais informações.

Para o provedor email, o usuário requer um ponto final de conexão SMTP para que o servidor do Email Delivery obtenha smtp_host. O usuário também requer um remetente aprovado pelo SMTP e suas credenciais para autenticação com o servidor do Email Delivery para obter o credential_name. A conexão SMTP deve ser configurada e as credenciais SMTP devem ser geradas e aprovadas.
Para o provedor msteams, o usuário requer o Aplicativo Microsoft Teams e um bot configurado nele. O aplicativo precisa ser publicado na organização e instalado após a aprovação do administrador do centro de administração. O usuário também precisa ter acesso à permissão Files.ReadWrite.All e ChannelSettings.Read.All para API de Gráfico no Portal do Azure. Para gerar o token necessário, o usuário requer bot_id no nome de usuário e bot_secret na senha. O tamanho máximo de arquivo suportado ao usar DBMS_CLOUD_NOTIFICATION.SEND_DATA para o Microsoft Teams é de 4 MB.
Para o provedor slack, o valor username pode ser qualquer string válida e o password é o token de bot do Slack.

Exemplo

Envie a saída SQL com o provedor email:

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

Envie a saída SQL com o provedor 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',
        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;
/

Envie a saída SQL com o provedor slack:

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

Procedimento SEND_MESSAGE

O procedimento envia uma mensagem de texto para um profissional de saúde.

Sintaxe

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

Parâmetros

Parâmetro	Descrição
`provider`	Especifica o provedor. Os valores válidos são: '`email`', '`msteams`', '`slack`' e '`oci`'. Este parâmetro é obrigatório.
`credential_name`	O nome do objeto de credencial para acessar o provedor. Para o provedor de e-mail, a credencial é o nome da credencial do remetente aprovado pelo SMTP que contém seu nome de usuário e senha. Para o provedor msteams, a credencial deve conter a chave `bot_id` e `bot_secret` no nome de usuário e na senha. Para o provedor do Slack, o nome de usuário da credencial deve ser `"SLACK_TOKEN"` e o `password` é o Token de Bot do Slack. Para o provedor `oci`, a credencial é uma credencial válida baseada em chave de assinatura do Oracle Cloud Infrastructure. Este parâmetro é obrigatório.
`message`	Especifica o texto da mensagem. Este parâmetro é obrigatório.
`params`	Especifica parâmetros específicos para o `provider` no formato JSON. Para o tipo de provedor `email`, os parâmetros válidos são: `sender`. Especifica o ID do E-mail do remetente aprovado em um valor `String`. `smtp_host`. Especifica o nome do host SMTP em um valor `String`. `subject`. Especifica o assunto do e-mail em um valor `String`. O tamanho máximo é 100 caracteres. `recipient`. Especifica os IDs de e-mail dos destinatários em um valor `String`. Use uma vírgula entre os IDs de e-mail quando houver vários destinatários. `to_cc`. Especifica os IDs de e-mail que estão recebendo um CC do e-mail. Use uma vírgula entre os IDs de e-mail quando houver vários destinatários CC. `to_bcc`. Especifica os IDs de e-mail que estão recebendo um Cco do e-mail. Use uma vírgula entre os IDs de e-mail quando houver vários destinatários com Cco. Para o tipo de provedor `msteams`, o parâmetro válido é: `channel`. Especifica o ID do Canal em um valor `String`. Para o tipo de provedor `slack`, o parâmetro válido é: `channel`. Especifica o ID do Canal em um valor `String`. Para o provedor OCI Notifications com o tipo `oci`, os parâmetros válidos são: `topic_ocid`: Especifica `title`: Especifica a linha de assunto da mensagem. Com o provedor `oci`, há diferentes pontos finais possíveis para uma mensagem, com base nas assinaturas. O parâmetro `title` é tratado de maneira diferente para diferentes assinaturas: email: O `title` especifica a linha de assunto da mensagem. Slack: O valor `title` não é usado. Se estiver incluído, o valor será ignorado. O ID do Canal é um ID exclusivo de um canal e é diferente do nome do canal. No Slack, quando você exibe os detalhes do canal, pode encontrar o ID do Canal na guia "Sobre". Este parâmetro é obrigatório.

Observações sobre Uso

Use o procedimento DBMS_CLOUD.CREATE_CREDENTIAL(credential_name, username, password) para criar o objeto de credencial. Consulte Procedimento CREATE_CREDENTIAL para obter mais informações.

Para o provedor email, o usuário requer um ponto final de conexão SMTP para que o servidor do Email Delivery obtenha smtp_host. O usuário também exige um remetente aprovado pelo SMTP e suas credenciais para autenticação com o servidor do Email Delivery para obter o credential_name. A conexão SMTP deve ser configurada e as credenciais SMTP devem ser geradas e aprovadas.
Para o provedor msteams, o usuário requer o Aplicativo Microsoft Teams e um bot configurado nele. O aplicativo precisa ser publicado na organização e instalado após a aprovação do administrador do centro de administração. O usuário também precisa ter acesso à permissão Files.ReadWrite.All e ChannelSettings.Read.All para API de Gráfico no Portal do Azure. Para gerar o token necessário, o usuário requer bot_id no nome de usuário e bot_secret na senha.
Para o provedor slack, o valor username pode ser qualquer string válida e o password é o token de bot do Slack.
O DBMS_CLOUD_NOTIFICATION suporta o provedor do OCI Notifications. Consulte Visão Geral do Serviço Notifications para obter detalhes sobre o provedor do OCI Notifications.
- Para usar o provedor do OCI Notifications, faça o seguinte:
  - Criar um tópico. Consulte Criando um Tópico para obter detalhes sobre como criar um tópico
  - Crie as assinaturas necessárias. Consulte Criando uma Assinatura para obter detalhes sobre a criação de uma assinatura.
  - Depois de criar as assinaturas, confirme-as. As mensagens só são publicadas em assinaturas confirmadas. Consulte Confirmando uma Assinatura para obter detalhes sobre a confirmação de assinaturas.
- A instância do Autonomous AI Database, a credencial (se você estiver usando credenciais do usuário) e o tópico de assinatura devem estar localizados na mesma região.
- Observe as seguintes limitações:
  - Limite de Tamanho da Mensagem: O limite de tamanho da mensagem por solicitação é de 64 KB. Mensagens que excedam este tamanho não podem ser enviadas ou processadas em uma única solicitação.
  - Limite de Taxa de Entrega de Mensagens: Existem diferentes limites de taxa de entrega de mensagens, dependendo do protocolo usado.
    - Protocolo email: o limite é de 10 mensagens por minuto por ponto final.
    Esta restrição pode afetar a velocidade com que as mensagens podem ser transmitidas e recebidas.
  - Limite de Transações por Minuto (TPM) por Tenancy: Há um limite de TPM de 60 por tópico para esta operação. Esse limite representa o número máximo de mensagens por minuto que podem ser processadas ou tratadas para um determinado tópico. Exceder esse limite pode resultar em mensagens não sendo processadas ou processadas em uma taxa mais lenta.

Exemplos

Envie uma mensagem de texto com o provedor 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;
/

Envie uma mensagem de texto com o provedor 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;
/

Envie uma mensagem de texto com o provedor 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;
/

Envie uma mensagem de texto com o OCI Notifications, digite o provedor oci:

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