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

Pré-requisitos

Oracle Public Cloud ou Multicloud
Exadata Cloud@Customer

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 (Rede Virtual na Nuvem) 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 da Sub-rede da sub-rede.
2. Na guia Informações da Sub-rede, clique no nome da Tabela de Rota da sub-rede para exibir sua respectiva página Detalhes da Tabela de Rota.
3. Na tabela de Regras de Roteamento existentes, verifique se já existe uma regra com as seguintes características:
  - Destino: 0.0.0.0/0
  - Tipo de Destino: Gateway NAT
  - Alvo: O nome do gateway NAT recém-criado na VCN
  Se essa regra não existir, clique em Adicionar Regras de Rota e adicione uma regra de roteamento com essas características.
4. Retorne à página Detalhes da Sub-rede da sub-rede.
5. Na tabela Listas de Segurança da sub-rede, clique no nome da lista de segurança da sub-rede para exibir a 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
  - Faixa de Portas de Destino: Todas
  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. Depois de ativado, você não poderá 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 de Subprogramas DBMS_CLOUD_NOTIFICATION

Esta tabela resume os subprogramas incluídos no pacote.

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

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`' Esse 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 de msteams, a credencial é o nome da credencial. Para o provedor do Slack, o nome de usuário da credencial deve ser `"SLACK_TOKEN"` e `password` é o Token de Bot do Slack. Esse parâmetro é obrigatório.
`query`	Especifica a consulta SQL a ser executada. Os resultados são enviados ao profissional de saúde. Esse parâmetro é obrigatório.
`params`	Especifica parâmetros específicos para `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`. Isso 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`. Isso especifica os IDs de e-mail dos destinatários em um valor `String`. Use uma vírgula entre IDs de e-mail quando houver vários destinatários. `to_cc`. Isso 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`. Isso 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 Cco. `message`. Isso especifica o texto da mensagem em um valor `String`. `type`. Isso 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 porque ele está sendo usado para gerar um nome de arquivo. Para o tipo de provedor `msteams`, os parâmetros válidos são: `tenant`. Isso especifica o ID do tenant em um formato `String`. `team`. Isso especifica o ID da equipe em um formato `String`. `channel`. Isso especifica o ID do canal em um formato `String`. `title`. Isso especifica o título do arquivo em um formato `String`. O tamanho máximo é de 50 caracteres. `type`. Isso 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`. Isso especifica o ID do Canal em um valor `String`. O ID do Canal é um ID exclusivo para um canal e é diferente do nome do canal. No Slack, ao exibir detalhes do canal, você pode encontrar o ID do Canal na guia "Sobre". `type`. Isso especifica o formato de saída em um valor `String`. Os valores válidos são CSV ou JSON. Esse parâmetro é obrigatório.

Observações sobre Uso

Use o procedimento DBMS_CLOUD.CREATE_CREDENTIAL(credential_name, username e 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 Email Delivery obtenha smtp_host. O usuário também requer um remetente aprovado pelo SMTP e suas credenciais para autenticação no servidor 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 obter a aprovação do administrador no centro de administração. O usuário também requer acesso à permissão Files.ReadWrite.All e ChannelSettings.Read.All para a API de Gráfico do 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 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`'. Esse 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 o `bot_id` e a chave `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 `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. Esse parâmetro é obrigatório.
`message`	Especifica o texto da mensagem. Esse parâmetro é obrigatório.
`params`	Especifica parâmetros específicos para `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`. Isso especifica o nome do host SMTP em um valor `String`. `subject`. Isso especifica o assunto do e-mail em um valor `String`. O tamanho máximo é de 100 caracteres. `recipient`. Isso especifica os IDs de e-mail dos destinatários em um valor `String`. Use uma vírgula entre IDs de e-mail quando houver vários destinatários. `to_cc`. Isso 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`. Isso 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 Cco. Para o tipo de provedor `msteams`, o parâmetro válido é: `channel`. Isso especifica o ID do Canal em um valor `String`. Para o tipo de provedor `slack`, o parâmetro válido é: `channel`. Isso 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 para um canal e é diferente do nome do canal. No Slack, ao exibir detalhes do canal, você pode encontrar o ID do Canal na guia "Sobre". Esse 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 CREATE_CREDENTIAL Procedures para obter mais informações.

Para o provedor email, o usuário requer um ponto final de conexão SMTP para que o servidor Email Delivery obtenha smtp_host. O usuário também requer um remetente aprovado pelo SMTP e suas credenciais para autenticação no servidor 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 obter a aprovação do administrador no centro de administração. O usuário também requer acesso à permissão Files.ReadWrite.All e ChannelSettings.Read.All para a API de Gráfico do 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 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 excedem 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;
/

Título e Informações de Copyright

Oracle e/ou suas empresas afiliadas.