Mensagens persistentes em DBMS_PIPE:

• Permite que você envie e recupere mensagens muito grandes.

• Suporta o envio de um grande número de mensagens de pipe.

• Ofereça suporte ao envio e recebimento de mensagens em um único banco de dados, em vários bancos de dados e em bancos de dados em diferentes regiões.

• Suporta vários pipes usando o mesmo URI de localização do Cloud Object Store.

Os pipes de mensagens persistentes podem ser criados em qualquer um dos tipos DBMS_PIPE suportados:

• Tubulação Implícita: Criada automaticamente quando uma mensagem é enviada com um nome de pipe desconhecido usando a função DBMS_PIPE.SEND_MESSAGE.
• Tubulação Explícita: Criada usando a função DBMS_PIPE.CREATE_PIPE com um nome de pipe especificado pelo usuário.
• Pipe Público: Acessível por qualquer usuário com a permissão EXECUTE no pacote DBMS_PIPE.
• Pipe Privado: Acessível por sessões com o mesmo usuário do criador do pipe.

Veja a seguir o workflow geral de DBMS_PIPE com mensagens persistentes:

Os aplicativos existentes que usam DBMS_PIPE podem continuar operando com alterações mínimas. Você pode configurar aplicativos existentes que usam DBMS_PIPE com um objeto de credencial e um URI de local usando um trigger de log-on ou usando alguma outra rotina de inicialização. Depois de definir a credencial DBMS_PIPE e o URI de local, nenhuma outra alteração será necessária para usar mensagens persistentes. Todo o uso subsequente do pipe armazena as mensagens no Armazenamento de Objetos na Nuvem em vez de na memória do banco de dados. Isso permite que você altere o método de armazenamento para mensagens do Cloud Object Storage na memória para persistente, com alterações mínimas.

Descreve as etapas para criar um pipe persistente com um nome de pipe especificado (Tubulação Explícita).

1. Armazene suas credenciais de armazenamento de objetos usando o procedimento DBMS_CLOUD.CREATE_CREDENTIAL. Por exemplo:

   BEGIN
     DBMS_CLOUD.CREATE_CREDENTIAL(
       credential_name => 'my_persistent_pipe_cred',
       username => 'adb_user@example.com',
       password => 'password'
     );
   END;
   /

   Esta operação armazena as credenciais no banco de dados em um formato criptografado. Você pode usar qualquer nome para o nome da credencial. Observe que essa etapa só é necessária uma vez, a menos que suas credenciais do armazenamento de objetos sejam alteradas. Depois de armazenar as credenciais, você poderá usar o mesmo nome de credencial para acessar o Cloud Object Store para enviar e receber mensagens com DBMS_PIPE.

   Para obter informações detalhadas sobre os parâmetros, consulte CREATE_CREDENTIAL Procedure. Para o Oracle Cloud Infrastructure Object Storage, é necessário que a credencial use autenticação nativa do Oracle Cloud Infrastructure.

   A criação de uma credencial para acessar o Oracle Cloud Infrastructure Object Store não será necessária se você ativar as credenciais do controlador de recursos. Para obter mais informações, consulte Usar o Controlador de Recursos para Acessar Recursos do Oracle Cloud Infrastructure.

   Observação
   
   Algumas ferramentas como SQL*Plus e SQL Developer usam o E comercial (&) como caractere especial. Se você tiver o caractere E comercial em sua senha, use o comando SET DEFINE OFF nessas ferramentas, conforme mostrado no exemplo, para desativar o caractere especial e fazer com que a credencial seja criada corretamente.
2. Crie um pipe explícito para enviar e recuperar mensagens. Por exemplo, crie um pipe chamado ORDER_PIPE.

   DECLARE
     r_status INTEGER;
   BEGIN
       r_status := DBMS_PIPE.CREATE_PIPE(pipename => 'ORDER_PIPE');
   END;
   /

   Consulte CREATE_PIPE Função para obter mais informações.

3. Verifique se o pipe foi criado.

   SELECT ownerid, name, type FROM v$db_pipes 
          WHERE name = 'ORDER_PIPE';

   OWNERID NAME       TYPE    
   ------- ---------- ------- 
        80 ORDER_PIPE PRIVATE 

4. Use procedimentos DBMS_PIPE para definir a credencial de acesso padrão e o URI de local para armazenar mensagens persistentes no Cloud Object Store.

   BEGIN
       DBMS_PIPE.SET_CREDENTIAL_NAME('my_persistent_pipe_cred');
       DBMS_PIPE.SET_LOCATION_URI('https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/'); 
   END;
   /

   Esses procedimentos definem o nome da credencial padrão e o URI de localização padrão para uso com procedimentos DBMS_PIPE.

   Se você usar o Oracle Cloud Infrastructure Object Storage para armazenar mensagens, poderá usar URIs Nativos do Oracle Cloud Infrastructure ou URIs Swift. No entanto, o URI do local e a credencial devem corresponder ao tipo da seguinte forma:

   • Se você usar um formato de URI nativo para acessar o Oracle Cloud Infrastructure Object Storage, deverá usar a autenticação de Chaves de Assinatura Nativas do Oracle Cloud Infrastructure no objeto de credencial.

   • Se você usar o formato de URI Swift para acessar o Oracle Cloud Infrastructure Object Storage, deverá usar uma autenticação de token de autenticação no objeto de credencial.

   Consulte Procedimento SET_CREDENTIAL_NAME e Procedimento SET_LOCATION_URI para obter mais informações.

5. Empacote e envie uma mensagem no pipe.

   DECLARE
     l_result INTEGER;
     l_date   DATE;
   BEGIN
       l_date := sysdate;
       DBMS_PIPE.PACK_MESSAGE(l_date);         -- date of order
       DBMS_PIPE.PACK_MESSAGE('C123');         -- order number
       DBMS_PIPE.PACK_MESSAGE(5);              -- number of items in order
       DBMS_PIPE.PACK_MESSAGE('Printers');     -- type of item in order
   
    
       l_result := DBMS_PIPE.SEND_MESSAGE(
                       pipename => 'ORDER_PIPE',
                       credential_name => DBMS_PIPE.GET_CREDENTIAL_NAME,
                       location_uri => DBMS_PIPE.GET_LOCATION_URI);
        
       IF l_result = 0 THEN
           DBMS_OUTPUT.put_line('DBMS_PIPE sent order successfully');
       END IF;
    
   END;
   /

   Consulte Procedimentos PACK_MESSAGE e Função SEND_MESSAGE para obter mais informações.

Descreve as etapas para recuperar uma mensagem persistente de um pipe explícito na mesma instância do Autonomous Database (a instância para a qual a mensagem foi enviada).

1. Verifique se o pipe foi criado.

   SELECT ownerid, name, type FROM v$db_pipes 
          WHERE name = 'ORDER_PIPE';
   

   OWNERID NAME       TYPE    
   ------- ---------- ------- 
        80 ORDER_PIPE PRIVATE 

   Quando você estiver na mesma instância do Autonomous Database e o pipe existir, não será necessário executar DBMS_PIPE.CREATE_PIPE antes de receber uma mensagem. Isso se aplica quando o pipe foi criado na mesma instância, conforme mostrado em Criar um Pipe Persistente Explícito e Enviar uma Mensagem.

2. Receba uma mensagem do pipe.

   DECLARE
       message1  DATE;
       message2  VARCHAR2(100);
       message3  INTEGER;
       message4  VARCHAR2(100);
       l_result  INTEGER;
   
   BEGIN
   
       DBMS_PIPE.SET_CREDENTIAL_NAME('my_persistent_pipe_cred');
       DBMS_PIPE.SET_LOCATION_URI('https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/'); 
       l_result := DBMS_PIPE.RECEIVE_MESSAGE (
                     pipename => 'ORDER_PIPE',
                     timeout  => DBMS_PIPE.MAXWAIT,
                     credential_name => DBMS_PIPE.GET_CREDENTIAL_NAME,
                     location_uri => DBMS_PIPE.GET_LOCATION_URI);
    
       IF l_result = 0 THEN
           DBMS_PIPE.unpack_message(message1);
           DBMS_PIPE.unpack_message(message2);
           DBMS_PIPE.unpack_message(message3);
           DBMS_PIPE.unpack_message(message4);
    
           DBMS_OUTPUT.put_line('Order Received Successfully On: ' || TO_CHAR(sysdate, 'dd-mm-yyyy hh24:mi:ss'));
           DBMS_OUTPUT.put_line('Date of Order: ' || message1);
           DBMS_OUTPUT.put_line('Order Number: ' || message2);
           DBMS_OUTPUT.put_line('Number of Items In Order: ' || message3);
           DBMS_OUTPUT.put_line('Item Type in Order: ' || message4);
       END IF;
    
   END;
   /

   Quando você está na mesma instância do Autonomous Database, a credencial já existe e não é necessário executar DBMS_CLOUD.CREATE_CREDENTIAL para receber uma mensagem. Isso se aplica quando o pipe foi criado na mesma instância, conforme mostrado em Criar um Pipe Persistente Explícito e Enviar uma Mensagem.

Descreve as etapas para recuperar uma mensagem persistente armazenada no Cloud Object Store com um pipe explícito em uma instância do Autonomous Database diferente da instância que enviou a mensagem.

1. Armazene suas credenciais de armazenamento de objetos usando o procedimento DBMS_CLOUD.CREATE_CREDENTIAL. Por exemplo:

   BEGIN
     DBMS_CLOUD.CREATE_CREDENTIAL(
       credential_name => 'my_persistent_pipe_cred',
       username => 'adb_user@example.com',
       password => 'password'
     );
   END;
   /

   Esta operação armazena as credenciais no banco de dados em um formato criptografado. Você pode usar qualquer nome para o nome da credencial. Observe que essa etapa só é necessária uma vez, a menos que suas credenciais do armazenamento de objetos sejam alteradas. Depois de armazenar as credenciais, você poderá usar o mesmo nome de credencial para acessar o Armazenamento de Objetos na Nuvem para enviar e receber mensagens com DBMS_PIPE.

   Para obter informações detalhadas sobre os parâmetros, consulte CREATE_CREDENTIAL Procedure.

   A criação de uma credencial para acessar o Oracle Cloud Infrastructure Object Store não será necessária se você ativar as credenciais do controlador de recursos. Para obter mais informações, consulte Usar o Controlador de Recursos para Acessar Recursos do Oracle Cloud Infrastructure.

   Observação
   
   Algumas ferramentas como SQL*Plus e SQL Developer usam o E comercial (&) como caractere especial. Se você tiver o caractere E comercial em sua senha, use o comando SET DEFINE OFF nessas ferramentas, conforme mostrado no exemplo, para desativar o caractere especial e fazer com que a credencial seja criada corretamente.
2. Crie um pipe explícito com o mesmo nome do pipe que enviou a mensagem. Por exemplo, crie um pipe chamado ORDER_PIPE.

   DECLARE
     r_status INTEGER;
   BEGIN
       r_status := DBMS_PIPE.CREATE_PIPE(pipename => 'ORDER_PIPE');
   END;
   /

   Consulte CREATE_PIPE Função.

3. Verifique se o pipe foi criado.

   SELECT ownerid, name, type FROM v$db_pipes 
          WHERE name = 'ORDER_PIPE';
   

   OWNERID NAME       TYPE    
   ------- ---------- ------- 
        80 ORDER_PIPE PRIVATE 

4. Use procedimentos DBMS_PIPE para definir a credencial de acesso padrão e o URI de local do Armazenamento de Objetos para que DBMS_PIPE possa acessar a mensagem persistente.

   BEGIN
       DBMS_PIPE.SET_CREDENTIAL_NAME('my_persistent_pipe_cred');
       DBMS_PIPE.SET_LOCATION_URI('https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/'); 
   END;
   /

   Esses procedimentos definem o nome da credencial padrão e o URI de localização padrão para uso com procedimentos DBMS_PIPE.

   Se você usar o Oracle Cloud Infrastructure Object Storage para armazenar mensagens, poderá usar URIs Nativos do Oracle Cloud Infrastructure ou URIs Swift. No entanto, o URI do local e a credencial devem corresponder ao tipo da seguinte forma:

   • Se você usar um formato de URI nativo para acessar o Oracle Cloud Infrastructure Object Storage, deverá usar a autenticação de Chaves de Assinatura Nativas do Oracle Cloud Infrastructure no objeto de credencial.

   • Se você usar o formato de URI Swift para acessar o Oracle Cloud Infrastructure Object Storage, deverá usar uma autenticação de token de autenticação no objeto de credencial.

   Consulte Procedimento SET_CREDENTIAL_NAME e Procedimento SET_LOCATION_URI para obter mais informações.

5. Receba uma mensagem do pipe persistente.

   DECLARE
       message1  DATE;
       message2  VARCHAR2(100);
       message3  INTEGER;
       message4  VARCHAR2(100);
       l_result  INTEGER;
   
   BEGIN
   
       DBMS_PIPE.SET_CREDENTIAL_NAME('my_persistent_pipe_cred');
       DBMS_PIPE.SET_LOCATION_URI('https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/'); 
       l_result := DBMS_PIPE.RECEIVE_MESSAGE (
                     pipename => 'ORDER_PIPE',
                     timeout  => DBMS_PIPE.MAXWAIT,
                     credential_name => DBMS_PIPE.GET_CREDENTIAL_NAME,
                     location_uri => DBMS_PIPE.GET_LOCATION_URI);
    
       IF l_result = 0 THEN
           DBMS_PIPE.unpack_message(message1);
           DBMS_PIPE.unpack_message(message2);
           DBMS_PIPE.unpack_message(message3);
           DBMS_PIPE.unpack_message(message4);
    
           DBMS_OUTPUT.put_line('Order Received Successfully On: ' || TO_CHAR(sysdate, 'dd-mm-yyyy hh24:mi:ss'));
           DBMS_OUTPUT.put_line('Date of Order: ' || message1);
           DBMS_OUTPUT.put_line('Order Number: ' || message2);
           DBMS_OUTPUT.put_line('Number of Items In Order: ' || message3);
           DBMS_OUTPUT.put_line('Item Type in Order: ' || message4);
       END IF;
    
   END;
   /

   Consulte RECEIVE_MESSAGE Função para obter mais informações.

Descreve as etapas para remover um pipe persistente.

1. Chame a função DBMS_PIPE.REMOVE_PIPE para remover um pipe.

   DECLARE
      l_result  INTEGER;
   BEGIN
        l_result := DBMS_PIPE.REMOVE_PIPE('ORDER_PIPE');
   END;
   /

   A função REMOVE_PIPE remove o pipe da instância do Autonomous Database em que ele é executado; no entanto, REMOVE_PIPE não afeta outras instâncias do Autonomous Database com um pipe com o mesmo nome que usa o mesmo URI de local.

2. Na instância do Autonomous Database em que você executou DBMS_PIPE.REMOVE_PIPE, verifique se o pipe foi removido.

   SELECT ownerid, name, type FROM v$db_pipes 
          WHERE name = 'ORDER_PIPE';
   

   No rows selected