Pacchetto DBMS_CLOUD_NOTIFICATION

Il pacchetto DBMS_CLOUD_NOTIFICATION consente di inviare messaggi o l'output di una query SQL a un provider.

I provider supportati con DBMS_CLOUD_NOTIFICATION sono: Email, Microsoft Teams, OCI Notifications (ONS) e Slack.

Quando si utilizza il servizio Notifiche OCI con il pacchetto DBMS_CLOUD_NOTIFICATION, è supportata solo la procedura DBMS_CLOUD_NOTIFICATION.SEND_MESSAGE (la procedura DBMS_CLOUD_NOTIFICATION.SEND_DATA non è supportata).

Prerequisiti

Una connettività in uscita deve essere stata configurata mediante un gateway NAT dall'amministratore della flotta, come descritto di seguito.
  • Creare un gateway NAT nella rete cloud virtuale (VCN) in cui risiedono le risorse del database AI autonomo seguendo le istruzioni riportate in Crea un gateway NAT nella documentazione di Oracle Cloud Infrastructure.
  • Dopo aver creato il gateway NAT, aggiungere una regola di instradamento e una regola di sicurezza in uscita a ogni subnet (nella VCN) in cui risiedono le risorse del database AI autonomo in modo che queste risorse possano utilizzare il gateway per ottenere una chiave pubblica dall'istanza di Azure AD:
    1. Andare alla pagina Dettagli subnet per la subnet.
    2. Nella scheda Informazioni subnet, fare clic sul nome della tabella di instradamento della subnet per visualizzare la relativa pagina Dettagli tabella di instradamento.
    3. Nella tabella delle regole di instradamento esistenti, verificare se esiste già una regola con le seguenti caratteristiche:
      • Data: 0.0.0.0/0
      • Tipo di destinazione: gateway NAT
      • Destinazione: il nome del gateway NAT appena creato nella VCN

      Se la regola non esiste, fare clic su Aggiungi regole di instradamento e aggiungere una regola di instradamento con queste caratteristiche.

    4. Tornare alla pagina Dettagli subnet per la subnet.
    5. Nella tabella Elenchi di sicurezza della subnet, fare clic sul nome della lista di sicurezza della subnet per visualizzare la relativa pagina Dettagli lista di sicurezza.
    6. Nel menu laterale, in Risorse, fare clic su Regole di uscita.
    7. Nella tabella delle regole di uscita esistenti, verificare se esiste già una regola con le seguenti caratteristiche:
      • Tipo di destinazione: CIDR
      • Data: 0.0.0.0/0
      • Protocollo IP: TCP
      • Intervallo porte di origine: 443
      • Intervallo di porte di destinazione: tutte

      Se una regola di questo tipo non esiste, fare clic su Aggiungi regole di uscita e aggiungere una regola di uscita con queste caratteristiche.

Le impostazioni del proxy HTTP nell'ambiente devono consentire al database di accedere al provider di servizi cloud.

Queste impostazioni vengono definite dall'amministratore della flotta durante la creazione dell'infrastruttura Exadata Cloud@Customer, come descritto in Uso della console per eseguire il provisioning di Exadata Database Service su Cloud@Customer.

Nota

La configurazione di rete, incluso il proxy HTTP, può essere modificata solo fino a quando lo stato dell'infrastruttura Exadata non è Richiede attivazione. Una volta attivato, non è possibile modificare tali impostazioni.

L'impostazione di un proxy HTTP per un'infrastruttura Exadata già fornita richiede una richiesta di servizio (SR) in My Oracle Support. Per informazioni dettagliate, vedere Create a Service Request in My Oracle Support.

Riepilogo dei sottoprogrammi DBMS_CLOUD_NOTIFICATION

Questa tabella contiene un riepilogo dei sottoprogrammi inclusi nel pacchetto.

Sottoprogramma Descrizione

SEND_DATA Procedura

Inviare l'output della query SQL a un provider.

SEND_MESSAGE Procedura

Invia un messaggio di testo a un provider.

SEND_DATA Procedura

La procedura SEND_DATA invia i risultati della query specificata a un provider.

Sintassi

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

Parametri

Parametro Descrizione

provider

Specifica il provider.

I valori validi sono: 'email', 'msteams' e 'slack'

Questo parametro è obbligatorio.

credential_name

Il nome dell'oggetto credenziale per accedere al provider.

Per il provider di posta elettronica, la credenziale è il nome della credenziale del mittente approvato SMTP che contiene il nome utente e la password.

Per il provider msteams, la credenziale è il nome della credenziale.

Per il provider Slack, il nome utente della credenziale deve essere "SLACK_TOKEN" e password è il token bot Slack.

Questo parametro è obbligatorio.

query

Specifica la query SQL da eseguire. I risultati vengono inviati al provider.

Questo parametro è obbligatorio.

params

Specifica parametri specifici per provider in formato JSON.

Per il tipo di provider email, i parametri validi sono:

  • sender. Specifica l'ID e-mail del mittente approvato in un valore String.
  • smtp_host. Specifica il nome host SMTP in un valore String.
  • subject. Specifica l'oggetto dell'e-mail in un valore String. La dimensione massima è di 100 caratteri.
  • recipient. Specifica gli ID e-mail dei destinatari in un valore String. Utilizzare una virgola tra gli ID e-mail quando sono presenti più destinatari.
  • to_cc. Specifica gli ID e-mail che ricevono un CC dell'e-mail. È un valore String. Utilizzare una virgola tra gli ID e-mail quando sono presenti più destinatari CC.
  • to_bcc. Specifica gli ID e-mail che ricevono un Ccn dell'e-mail. È un valore String. Utilizzare una virgola tra gli ID e-mail quando sono presenti più destinatari Ccn.
  • message. Specifica il testo del messaggio in un valore String.
  • type. Specifica il formato di output in un valore String come CSV o JSON.
  • title. Specifica il titolo dell'allegato dell'output SQL in un valore String. Il titolo deve contenere solo lettere, cifre, caratteri di sottolineatura, trattini o punti come caratteri nel relativo valore poiché viene utilizzato per generare un nome file.

Per il tipo di provider msteams, i parametri validi sono:

  • tenant. Specifica l'ID tenant in formato String.
  • team. Specifica l'ID team in formato String.
  • channel. Specifica l'ID canale in formato String.
  • title. Specifica il titolo del file in formato String. La dimensione massima è di 50 caratteri.
  • type. Specifica il formato di output in un valore String. I valori validi sono CSV o JSON.

Per il tipo di provider slack, i parametri validi sono:

  • channel. Specifica l'ID canale in un valore String. L'ID canale è un ID univoco per un canale ed è diverso dal nome del canale. In Slack, quando si visualizzano i dettagli del canale, è possibile trovare l'ID canale nella scheda "Informazioni".
  • type. Specifica il formato di output in un valore String. I valori validi sono CSV o JSON.

Questo parametro è obbligatorio.

Note sull'uso

Per creare l'oggetto credenziale, utilizzare la procedura DBMS_CLOUD.CREATE_CREDENTIAL(credential_name, username, password). Per ulteriori informazioni, vedere CREATE_CREDENTIAL Procedura.

  • Per il provider email, l'utente richiede un endpoint di connessione SMTP per il server di consegna tramite e-mail per ottenere smtp_host. L'utente richiede inoltre che un mittente approvato SMTP e le relative credenziali vengano autenticate con il server di consegna tramite e-mail per ottenere credential_name. È necessario configurare la connessione SMTP e generare e approvare le credenziali SMTP.
  • Per il provider msteams, l'utente richiede l'applicazione Microsoft Teams e un bot configurato al suo interno. L'applicazione deve essere pubblicata nell'organizzazione e installata dopo aver ottenuto l'approvazione dall'amministratore dal centro di amministrazione. L'utente richiede inoltre l'accesso per l'autorizzazione Files.ReadWrite.All e ChannelSettings.Read.All per l'API Graph dal proprio portale Azure. Per generare il token richiesto, l'utente richiede bot_id nel nome utente e bot_secret nella password. La dimensione massima supportata per i file che utilizzano DBMS_CLOUD_NOTIFICATION.SEND_DATA per Microsoft Teams è di 4 MB.
  • Per il provider slack, il valore username può essere qualsiasi stringa valida e password è il token bot Slack.

Esempio

Inviare l'output SQL con il provider 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;
/

Inviare l'output SQL con il provider 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;
/

Inviare l'output SQL con il provider 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;
/

SEND_MESSAGE Procedura

La procedura invia un messaggio di testo a un provider.

Sintassi

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

Parametri

Parametro Descrizione

provider

Specifica il provider.

I valori validi sono: 'email', 'msteams', 'slack' e 'oci'.

Questo parametro è obbligatorio.

credential_name

Il nome dell'oggetto credenziale per accedere al provider.

Per il provider di posta elettronica, la credenziale è il nome della credenziale del mittente approvato SMTP che contiene il nome utente e la password.

Per il provider msteams, la credenziale deve contenere sia il nome utente che la password bot_id e la chiave bot_secret.

Per il provider Slack, il nome utente della credenziale deve essere "SLACK_TOKEN" e password è il token bot Slack.

Per il provider oci, la credenziale è una credenziale valida basata sulla chiave di firma Oracle Cloud Infrastructure.

Questo parametro è obbligatorio.

message

Specifica il testo del messaggio

Questo parametro è obbligatorio.

params

Specifica parametri specifici per provider in formato JSON.

Per il tipo di provider email, i parametri validi sono:
  • sender. Specifica l'ID e-mail del mittente approvato in un valore String.
  • smtp_host. Specifica il nome host SMTP in un valore String.
  • subject. Specifica l'oggetto dell'e-mail in un valore String. La dimensione massima è di 100 caratteri.
  • recipient. Specifica gli ID e-mail dei destinatari in un valore String. Utilizzare una virgola tra gli ID e-mail quando sono presenti più destinatari.
  • to_cc. Specifica gli ID e-mail che ricevono un CC dell'e-mail. Utilizzare una virgola tra gli ID e-mail quando sono presenti più destinatari CC.
  • to_bcc. Specifica gli ID e-mail che ricevono un Ccn dell'e-mail. Utilizzare una virgola tra gli ID e-mail quando sono presenti più destinatari Ccn.
Per il tipo di provider msteams, il parametro valido è:
  • channel. Specifica l'ID canale in un valore String.
Per il tipo di provider slack, il parametro valido è:
  • channel. Specifica l'ID canale in un valore String.
Per il provider OCI Notifications con il tipo oci, i parametri validi sono:
  • topic_ocid: specifica
  • title: specifica la riga dell'oggetto del messaggio.
Con il provider oci, sono disponibili endpoint diversi per un messaggio, in base alle sottoscrizioni. Il parametro title viene trattato in modo diverso per le diverse sottoscrizioni:
  • email: title specifica la riga dell'oggetto del messaggio.
  • Slack: il valore title non viene utilizzato. Se è incluso, il valore viene ignorato.

L'ID canale è un ID univoco per un canale ed è diverso dal nome del canale. In Slack, quando si visualizzano i dettagli del canale, è possibile trovare l'ID canale nella scheda "Informazioni".

Questo parametro è obbligatorio.

Note sull'uso

Per creare l'oggetto credenziale, utilizzare la procedura DBMS_CLOUD.CREATE_CREDENTIAL(credential_name, username e password). Per ulteriori informazioni, vedere CREATE_CREDENTIAL Procedure.

  • Per il provider email, l'utente richiede un endpoint di connessione SMTP per il server di consegna tramite e-mail per ottenere smtp_host. L'utente richiede inoltre che un mittente approvato SMTP e le relative credenziali vengano autenticate con il server di consegna tramite e-mail per ottenere credential_name. È necessario configurare la connessione SMTP e generare e approvare le credenziali SMTP.
  • Per il provider msteams, l'utente richiede l'applicazione Microsoft Teams e un bot configurato al suo interno. L'applicazione deve essere pubblicata nell'organizzazione e installata dopo aver ottenuto l'approvazione dall'amministratore dal centro di amministrazione. L'utente richiede inoltre l'accesso per l'autorizzazione Files.ReadWrite.All e ChannelSettings.Read.All per l'API Graph dal proprio portale Azure. Per generare il token richiesto, l'utente richiede bot_id nel nome utente e bot_secret nella password.
  • Per il provider slack, il valore username può essere qualsiasi stringa valida e password è il token bot Slack.
  • DBMS_CLOUD_NOTIFICATION supporta il provider di notifiche OCI. Per informazioni dettagliate sul provider di notifiche OCI, consulta la panoramica delle notifiche.
    • Per utilizzare il provider di notifiche OCI, è necessario effettuare le operazioni riportate di seguito.
      • Creare un argomento. Per informazioni dettagliate sulla creazione di un argomento, vedere Creazione di un argomento
      • Creare le sottoscrizioni richieste. Per informazioni dettagliate sulla creazione di una sottoscrizione, vedere Creazione di una sottoscrizione.
      • Dopo aver creato le sottoscrizioni, confermare le sottoscrizioni. I messaggi vengono pubblicati solo per le sottoscrizioni confermate. Per informazioni dettagliate sulla conferma delle sottoscrizioni, vedere Conferma di una sottoscrizione.
    • L'istanza del database AI autonomo, la credenziale (se si utilizzano le credenziali utente) e l'argomento della sottoscrizione devono trovarsi tutti nella stessa area.
    • Vanno considerate le seguenti limitazioni:
      • Il limite di dimensione del messaggio per richiesta è di 64 KB. I messaggi che superano questa dimensione non possono essere inviati o elaborati all'interno di una singola richiesta.
      • Limite di frequenza di consegna dei messaggi: esistono limiti di frequenza di consegna dei messaggi diversi a seconda del protocollo utilizzato.
        • Protocollo email: il limite è di 10 messaggi al minuto per endpoint.

        Questa restrizione può influire sulla velocità con cui i messaggi possono essere trasmessi e ricevuti.

      • Limite transazioni al minuto (TPM) per tenancy: per questa operazione è previsto un limite TPM di 60 per argomento. Questo limite rappresenta il numero massimo di messaggi al minuto che possono essere elaborati o gestiti per un determinato argomento. Il superamento di questo limite può comportare la mancata elaborazione o l'elaborazione dei messaggi a una velocità inferiore.

Esempi

Inviare un messaggio di testo al provider 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;
/

Invia un messaggio di testo al provider 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;
/

Invia un messaggio di testo al provider 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;
/

Inviare un messaggio di testo con le notifiche OCI, digitare il provider 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;
/