Paquete DBMS_CLOUD_NOTIFICATION

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

DBMS_CLOUD_NOTIFICATION Visión general
Describe el paquete DBMS_CLOUD_NOTIFICATION.
Resumen de los subprogramas DBMS_CLOUD_NOTIFICATION
En esta tabla se resumen los subprogramas incluidos en el paquete.

Tema principal: Referencia de paquete proporcionado por Autonomous Database

Visión general de DBMS_CLOUD_NOTIFICATION

Describe el paquete DBMS_CLOUD_NOTIFICATION.

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)

Tema principal: Paquete DBMS_CLOUD_NOTIFICATION

Resumen de los 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 profesional asistencial.

Procedimiento SEND_DATA
El procedimiento SEND_DATA envía los resultados de la consulta especificada a un proveedor.
Procedimiento SEND_MESSAGE
El procedimiento envía un mensaje de texto a un proveedor.

Tema principal: Paquete DBMS_CLOUD_NOTIFICATION

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`. Utilice una coma entre los ID de correo electrónico cuando haya varios destinatarios de CC. `to_bcc`. Especifica los ID de correo electrónico que reciben una copia oculta 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 "Acerca de". `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, tenga en cuenta lo siguiente:
- 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 por SMTP y sus credenciales para autenticarse con el servidor Email Delivery para obtener credential_name. Se debe configurar la conexión SMTP y se deben generar y aprobar las credenciales SMTP.
- El tamaño máximo de mensaje soportado al utilizar DBMS_CLOUD_NOTIFICATION.SEND_DATA con el proveedor email es de 32k bytes.
- Solo puede utilizar DBMS_CLOUD_NOTIFICATION para notificaciones de correo con Autonomous Database versión 19.21 y posteriores.
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 Graph API 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 soportado 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.

Ejemplos

Envíe la 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 la 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 la 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;
/

Tema principal: Resumen de los subprogramas DBMS_CLOUD_NOTIFICATION

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. Proveedor `email`: la credencial es el nombre de la credencial del remitente aprobado de SMTP que contiene su nombre de usuario y contraseña. Proveedor `msteams`: la credencial debe contener la clave `bot_id` y `bot_secret` tanto en `username` como en `password`. Proveedor `slack`: el `username` de la credencial debe ser `"SLACK_TOKEN"` y el `password` es el token de bot de Slack. Proveedor `oci`: la credencial es una credencial válida basada en clave de firma de Oracle Cloud Infrastructure o una credencial de principal de recurso. Este parámetro es obligatorio. Utilice el procedimiento `DBMS_CLOUD.CREATE_CREDENTIAL` para crear el objeto de credencial. Consulte CREATE_CREDENTIAL Procedure para obtener más información.
`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 están recibiendo un CC del correo electrónico. Utilice una coma entre los ID de correo electrónico cuando haya varios destinatarios CC. `to_bcc`: especifica los ID de correo electrónico que están recibiendo 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`. Este parámetro es obligatorio. 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 "Acerca de". 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.

Nota de uso para proveedor de correo electrónico

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 por SMTP y sus credenciales para autenticarse con el servidor Email Delivery para obtener credential_name. Se debe configurar la conexión SMTP y se deben generar y aprobar las credenciales SMTP.

Nota de uso para el proveedor de Msteams

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 Graph API 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.

Nota de uso para el proveedor de Slack

Para el proveedor slack, el valor username puede ser cualquier cadena válida y password es el token de bot de Slack.

Notas de uso de OCI Provider OCI Notifications

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

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

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

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


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

Tema principal: Resumen de los subprogramas DBMS_CLOUD_NOTIFICATION

Documentación de Oracle Cloud Infrastructure