Paquete DBMS_CLOUD_NOTIFICATION

El paquete DBMS_CLOUD_NOTIFICATION permite enviar mensajes o la salida de una consulta SQL a un proveedor.

Los proveedores soportados con DBMS_CLOUD_NOTIFICATION son: correo electrónico, Microsoft Teams, notificaciones de OCI (ONS) y Slack.

Al utilizar el servicio OCI Notifications con el paquete DBMS_CLOUD_NOTIFICATION, solo está soportado el procedimiento DBMS_CLOUD_NOTIFICATION.SEND_MESSAGE (el procedimiento DBMS_CLOUD_NOTIFICATION.SEND_DATA no está soportado).

Requisitos

Oracle Public Cloud o multinube
Exadata Cloud at Customer

El administrador del conjunto debe haber configurado una conectividad saliente mediante un gateway de NAT, como se describe a continuación:

Para crear un Gateway de NAT en la red virtual en la nube (VCN) donde residen los recursos de la base de datos de IA autónoma, siga las instrucciones de Creación de un Gateway de NAT en la documentación de Oracle Cloud Infrastructure.
Después de crear el gateway de NAT, agregue una regla de ruta y una regla de seguridad de salida a cada subred (en la VCN), en la que residan las base de datos de IA autónoma, de modo que estos recursos puedan utilizar el gateway para obtener una clave pública de su instancia de de Azure AD:
1. Vaya a la página Detalles de subred de la subred.
2. En el separador Información de Subred, haga clic en el nombre de la Tabla de Direcciones de la subred para mostrar su página Detalles de Tabla de Direcciones.
3. En la tabla de Reglas de ruta existentes, compruebe si ya hay una regla con las siguientes características:
  - Destino: 0.0.0.0/0
  - Tipo de destino: gateway de NAT
  - Destino: nombre del gateway de NAT que acaba de crear en la VCN
  Si dicha regla no existe, haga clic en Agregar reglas de ruta y agregue una regla de ruta con estas características.
4. Vuelva a la página Detalles de subred de la subred.
5. En la tabla Listas de seguridad de la subred, haga clic en el nombre de la lista de seguridad de la subred para mostrar su página Detalles de lista de seguridad.
6. En el menú lateral, en Recursos, haga clic en Reglas de salida.
7. En la tabla de Reglas de salida existentes, compruebe si ya hay una regla con las siguientes características:
  - Tipo de destino: CIDR
  - Destino: 0.0.0.0/0
  - Protocolo IP: TCP
  - Rango de puertos de origen: 443
  - Rango de puertos de destino: todos
  Si dicha regla no existe, haga clic en Agregar Reglas de Salida y agregue una regla de salida con estas características.

La configuración del proxy HTTP en el entorno debe permitir que la base de datos acceda al proveedor de servicios en la nube.

El administrador del conjunto define esta configuración al crear la infraestructura de Exadata Cloud@Customer, como se describe en Uso de la consola para aprovisionar Exadata Database Service on Cloud@Customer.

Note:

La configuración de red, incluido el proxy HTTP, solo se puede editar hasta que la infraestructura de Exadata tenga el estado Necesita activación. Una vez activada, no puede editar esa configuración.

La configuración de un proxy HTTP para una infraestructura de Exadata ya aprovisionada necesita una solicitud de servicio (SR) en My Oracle Support. Consulte Creación de una solicitud de servicio en My Oracle Support para obtener más información.

Resumen de subprogramas DBMS_CLOUD_NOTIFICATION

En esta tabla se resumen los subprogramas incluidos en el paquete.

Subprograma	Descripción
Procedimiento SEND_DATA	Enviar la salida de la consulta SQL a un proveedor.
Procedimiento SEND_MESSAGE	Enviar un mensaje de texto a un proveedor.

Procedimiento SEND_DATA

El procedimiento SEND_DATA envía los resultados de la consulta especificada a un proveedor.

Sintaxis

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

Parámetros

parámetro	Descripción
`provider`	Especifica el proveedor. Los valores válidos son: '`email`', '`msteams`' y '`slack`' Este parámetro es obligatorio.
`credential_name`	Nombre del objeto de credencial para acceder al proveedor. Para el proveedor de correo electrónico, la credencial es el nombre de la credencial del remitente aprobado SMTP que contiene su nombre de usuario y contraseña. Para el proveedor de msteams, la credencial es el nombre de la credencial. Para el proveedor de Slack, el nombre de usuario de la credencial debe ser `"SLACK_TOKEN"` y `password` es el token de bot de Slack. Este parámetro es obligatorio.
`query`	Especifica la consulta SQL que se va a ejecutar. Los resultados se envían al profesional asistencial. Este parámetro es obligatorio.
`params`	Especifica parámetros específicos para `provider` en formato JSON. Para el tipo de proveedor `email`, los parámetros válidos son: `sender`. Especifica el ID de correo electrónico del remitente aprobado en un valor `String`. `smtp_host`. Especifica el nombre de host SMTP en un valor `String`. `subject`. Especifica el asunto del correo electrónico en un valor `String`. El tamaño máximo es de 100 caracteres. `recipient`. Especifica los ID de correo electrónico de los destinatarios en un valor `String`. Utilice una coma entre los ID de correo electrónico cuando haya varios destinatarios. `to_cc`. Especifica los ID de correo electrónico que reciben una copia del correo electrónico. Es un valor `String`. Use una coma entre los ID de correo electrónico cuando haya varios destinatarios CC. `to_bcc`. Esto especifica los ID de correo electrónico que reciben un BCC del correo electrónico. Es un valor `String`. Utilice una coma entre los ID de correo electrónico cuando haya varios destinatarios de BCC. `message`. Especifica el texto del mensaje en un valor `String`. `type`. Especifica el formato de salida en un valor `String` como CSV o JSON. `title`. Especifica el título de la asociación de la salida SQL en un valor `String`. El título solo debe contener letras, dígitos, guiones bajos, guiones o puntos como caracteres en su valor debido a que se utiliza para generar un nombre de archivo. Para el tipo de proveedor `msteams`, los parámetros válidos son: `tenant`. Especifica el ID de inquilino en formato `String`. `team`. Especifica el ID de equipo en formato `String`. `channel`. Especifica el ID de canal en formato `String`. `title`. Especifica el título del archivo en formato `String`. El tamaño máximo es de 50 caracteres. `type`. Especifica el formato de salida en un valor `String`. Los valores válidos son CSV o JSON. Para el tipo de proveedor `slack`, los parámetros válidos son: `channel`. Especifica el ID de canal en un valor `String`. El ID de canal es un ID único para un canal y es diferente del nombre del canal. En Slack, al ver los detalles del canal, puede encontrar el ID de canal en el separador "About". `type`. Especifica el formato de salida en un valor `String`. Los valores válidos son CSV o JSON. Este parámetro es obligatorio.

Notas de uso

Utilice el procedimiento DBMS_CLOUD.CREATE_CREDENTIAL(credential_name, username, password) para crear el objeto de credencial. Consulte Procedimiento CREATE_CREDENTIAL para obtener más información.

Para el proveedor email, el usuario necesita un punto final de conexión SMTP para que el servidor de Email Delivery obtenga smtp_host. El usuario también necesita un remitente aprobado SMTP y sus credenciales para autenticarse con el servidor de Email Delivery para obtener credential_name. Se debe configurar la conexión SMTP y se deben generar y aprobar las credenciales SMTP.
Para el proveedor msteams, el usuario necesita la aplicación Microsoft Teams y un bot configurado en ella. La aplicación debe publicarse en la organización e instalarse después de obtener la aprobación del administrador del centro de administración. El usuario también necesita acceso para los permisos Files.ReadWrite.All y ChannelSettings.Read.All para la API de Graph desde su portal de Azure. Para generar el token necesario, el usuario necesita bot_id en el nombre de usuario y bot_secret en la contraseña. El tamaño máximo de archivo admitido al utilizar DBMS_CLOUD_NOTIFICATION.SEND_DATA para Microsoft Teams es de 4 MB.
Para el proveedor slack, el valor username puede ser cualquier cadena válida y password es el token de bot de Slack.

Ejemplo

Envíe una salida SQL con el proveedor 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;
/

Envíe una salida SQL con el proveedor 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;
/

Envíe una salida SQL con el proveedor 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;
/

Procedimiento SEND_MESSAGE

El procedimiento envía un mensaje de texto a un profesional asistencial.

Sintaxis

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

Parámetros

parámetro	Descripción
`provider`	Especifica el proveedor. Los valores válidos son: '`email`', '`msteams`', '`slack`' y '`oci`'. Este parámetro es obligatorio.
`credential_name`	Nombre del objeto de credencial para acceder al proveedor. Para el proveedor de correo electrónico, la credencial es el nombre de la credencial del remitente aprobado SMTP que contiene su nombre de usuario y contraseña. Para el proveedor de msteams, la credencial debe contener la clave `bot_id` y `bot_secret` tanto en el nombre de usuario como en la contraseña. Para el proveedor de Slack, el nombre de usuario de la credencial debe ser `"SLACK_TOKEN"` y `password` es el token de bot de Slack. Para el proveedor `oci`, la credencial es una credencial válida basada en clave de firma de Oracle Cloud Infrastructure. Este parámetro es obligatorio.
`message`	Especifica el texto del mensaje. Este parámetro es obligatorio.
`params`	Especifica parámetros específicos para `provider` en formato JSON. Para el tipo de proveedor `email`, los parámetros válidos son: `sender`. Especifica el ID de correo electrónico del remitente aprobado en un valor `String`. `smtp_host`. Especifica el nombre de host SMTP en un valor `String`. `subject`. Especifica el asunto del correo electrónico en un valor `String`. El tamaño máximo es de 100 caracteres. `recipient`. Especifica los ID de correo electrónico de los destinatarios en un valor `String`. Utilice una coma entre los ID de correo electrónico cuando haya varios destinatarios. `to_cc`. Especifica los ID de correo electrónico que reciben una copia del correo electrónico. Use una coma entre los ID de correo electrónico cuando haya varios destinatarios CC. `to_bcc`. Esto especifica los ID de correo electrónico que reciben un BCC del correo electrónico. Utilice una coma entre los ID de correo electrónico cuando haya varios destinatarios de BCC. Para el tipo de proveedor `msteams`, el parámetro válido es: `channel`. Especifica el ID de canal en un valor `String`. Para el tipo de proveedor `slack`, el parámetro válido es: `channel`. Especifica el ID de canal en un valor `String`. Para el proveedor OCI Notifications con el tipo `oci`, los parámetros válidos son: `topic_ocid`: especifica `title`: especifica la línea de asunto del mensaje. Con el proveedor `oci`, hay diferentes puntos finales posibles para un mensaje, según las suscripciones. El parámetro `title` se trata de forma diferente para las distintas suscripciones: correo electrónico: `title` especifica la línea de asunto del mensaje. Slack: no se utiliza el valor `title`. Si se incluye, el valor se ignora. El ID de canal es un ID único para un canal y es diferente del nombre del canal. En Slack, al ver los detalles del canal, puede encontrar el ID de canal en el separador "About". Este parámetro es obligatorio.

Notas de uso

Utilice el procedimiento DBMS_CLOUD.CREATE_CREDENTIAL(credential_name, username, password) para crear el objeto de credencial. Consulte CREATE_CREDENTIAL Procedure para obtener más información.

Para el proveedor email, el usuario necesita un punto final de conexión SMTP para que el servidor de Email Delivery obtenga smtp_host. El usuario también necesita un remitente aprobado SMTP y sus credenciales para autenticarse con el servidor de Email Delivery para obtener credential_name. Se debe configurar la conexión SMTP y se deben generar y aprobar las credenciales SMTP.
Para el proveedor msteams, el usuario necesita la aplicación Microsoft Teams y un bot configurado en ella. La aplicación debe publicarse en la organización e instalarse después de obtener la aprobación del administrador del centro de administración. El usuario también necesita acceso para los permisos Files.ReadWrite.All y ChannelSettings.Read.All para la API de Graph desde su portal de Azure. Para generar el token necesario, el usuario necesita bot_id en el nombre de usuario y bot_secret en la contraseña.
Para el proveedor slack, el valor username puede ser cualquier cadena válida y password es el token de bot de Slack.
DBMS_CLOUD_NOTIFICATION soporta el proveedor de notificaciones de OCI. Consulte Visión general de Notifications para obtener más información sobre el proveedor de OCI Notifications.
- Para utilizar el proveedor de notificaciones de OCI, debe hacer lo siguiente:
  - Crear un tema. Consulte Creación de un tema para obtener más información sobre la creación de un tema.
  - Cree las suscripciones necesarias. Consulte Creación de una suscripción para obtener más información sobre la creación de una suscripción.
  - Después de crear las suscripciones, confirme las suscripciones. Los mensajes solo se publican en suscripciones confirmadas. Consulte Confirmación de una suscripción para obtener más información sobre la confirmación de suscripciones.
- La instancia de Autonomous AI Database, la credencial (si utiliza credenciales de usuario) y el tema de suscripción deben estar ubicados en la misma región.
- Tenga en cuenta las siguientes limitaciones:
  - Límite de tamaño de mensaje: el límite de tamaño de mensaje por solicitud es de 64 KB. Los mensajes que superen este tamaño no se pueden enviar ni procesar en una sola solicitud.
  - Límite de ratio de entrega de mensajes: hay diferentes límites de ratio de entrega de mensajes según el protocolo utilizado.
    - Protocolo email: el límite es de 10 mensajes por minuto por punto final.
    Esta restricción puede afectar la velocidad a la que se pueden transmitir y recibir los mensajes.
  - Límite de transacciones por minuto (TPM) por arrendamiento: hay un límite de TPM de 60 por tema para esta operación. Este límite representa el número máximo de mensajes por minuto que se pueden procesar o manejar para un tema determinado. Si se supera este límite, es posible que los mensajes no se procesen o procesen a un ritmo más lento.

Ejemplos

Envíe un mensaje de texto con el proveedor 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;
/

Envíe un mensaje de texto con el proveedor 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;
/

Envíe un mensaje de texto con el proveedor 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;
/

Envíe un mensaje de texto con OCI Notifications, escriba el proveedor 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 Información de Copyright

Oracle y/o sus filiales.