Usar Mensagens Persistentes com Mensagens Armazenadas no Cloud Object Store

O pacote DBMS_PIPE tem funcionalidade estendida no Autonomous AI Database para suportar mensagens persistentes, nas quais as mensagens são armazenadas no Cloud Object Store.

Sobre Mensagens Persistentes com DBMS_PIPE

As mensagens persistentes com o DBMS_PIPE permitem que uma ou mais sessões do banco de dados se comuniquem na mesma região ou entre regiões com mensagens armazenadas no Cloud Object Store.

Mensagens persistentes em DBMS_PIPE:

• Permita 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.

• Suporte a vários pipes usando o mesmo URI de local 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.

• Tubulação Pública: Acessível por qualquer usuário com permissão EXECUTE no pacote DBMS_PIPE.

• Pipe Privado: acessível por sessões com o mesmo usuário que o criador do pipe.

Observação: A Oracle recomenda criar um pipe explícito antes de enviar ou receber mensagens com mensagens persistentes. A criação de um pipe explícito com DBMS_PIPE.CREATE_PIPE garante que o pipe seja criado com as permissões de acesso desejadas, públicas ou privadas (definindo o parâmetro private).

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

Descrição da ilustração database-pipe-persistent-messaging.svg

Os aplicativos existentes que usam DBMS_PIPE podem continuar a operar com alterações mínimas. Você pode configurar aplicativos existentes que usam DBMS_PIPE com um objeto de credencial e 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 uso subsequente do pipe armazena as mensagens no Cloud Object Store em vez de na memória do banco de dados. Isso permite que você altere o método de armazenamento de mensagens da memória para o Cloud Object Storage persistente, com alterações mínimas.

Visão Geral e Recursos de Mensagens Persistentes

Recursos do DBMS_PIPE usando mensagens persistentes:

• As mensagens podem ser enviadas e recuperadas em várias instâncias do Autonomous AI Database na mesma região ou entre regiões.

• As mensagens persistentes são garantidas para serem escritas ou lidas por exatamente um processo. Isso evita a inconsistência do conteúdo da mensagem devido a leituras e gravações simultâneas. O DBMS_PIPE permite que apenas uma operação, enviando uma mensagem ou recebendo uma mensagem, esteja ativa em um determinado momento e essas operações são protegidas por um mecanismo de bloqueio. No entanto, se uma operação não for possível devido a uma operação em andamento, o processo será repetido periodicamente até que o valor timeout seja atingido.

• O DBMS_PIPE usa DBMS_CLOUD para acessar o Cloud Object Store. As mensagens podem ser armazenadas em qualquer um dos Cloud Object Stores suportados. Consulte Formatos de URI do Cloud Object Storage para obter mais informações.

• O DBMS_PIPE usa DBMS_CLOUD para acessar o Cloud Object Store e todos os tipos de credenciais suportados estão disponíveis:

  • DBMS_CLOUD.CREATE_CREDENTIAL: Consulte procedimento CREATE_CREDENTIAL para obter mais informações.

Autorização e segurança de privilégios DBMS_PIPE

Os procedimentos DBMS_PIPE são executados com os direitos do chamador. Os pipes privados são de propriedade do usuário atual e um pipe privado criado por um usuário só pode ser usado pelo mesmo usuário. Isso se aplica a pipes na memória e a pipes de mensagens persistentes em que as mensagens são armazenadas no Cloud Object Store. O envio e o recebimento de mensagens são executados no esquema do chamador.

Usando pipes privados, em que as mensagens são armazenadas no Cloud Object Store, é necessário um objeto de credencial para autenticação com o Cloud Object Store identificado pelo parâmetro location_uri. O usuário que chama deve ter o privilégio EXECUTE no objeto de credencial especificado com o parâmetro credential_name usado para acessar o Object Store.

Para usar um pipe público, o usuário, a sessão do banco de dados, deve ter privilégio de execução em DBMS_PIPE. Para um pipe público que usa mensagens persistentes e armazena mensagens no Cloud Object Store, o usuário, a sessão do banco de dados deve ter o privilégio de execução em DBMS_CLOUD e o privilégio de execução no objeto de credencial (ou você pode criar um objeto de credencial com permissão para acessar o URI do local que contém a mensagem).

Limitação de DBMS_PIPE

O pacote DBMS_PIPE não suporta o envio de mensagens entre bancos de dados que usam conjuntos de caracteres diferentes. Por exemplo, se você tiver uma instância do Autonomous AI Database que use AL32UTF8 e outra instância que use WE8MSWIN1252, não poderá enviar mensagens com DBMS_PIPE entre esses dois bancos de dados. Nesse caso, o sistema gerará o erro ORA-12704 se você tentar enviar mensagens com DBMS_PIPE entre esses dois bancos de dados.

Consulte Seleção do Conjunto de Caracteres para o Autonomous AI Database para obter mais informações.

Criar um Pipe Persistente Explícito e Enviar uma Mensagem

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

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

    BEGIN
      DBMS_CLOUD.CREATE_CREDENTIAL(
        credential_name => 'my_persistent_pipe_cred',
        username => '[e-mail]',
        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 Procedimento CREATE_CREDENTIAL. Para o Oracle Cloud Infrastructure Object Storage, é necessário que a credencial use autenticação nativa do Oracle Cloud Infrastructure.

   Observação: Algumas ferramentas, como o SQL*Plus e o SQL Developer, usam o caractere E comercial (&) como um 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 obter a credencial criada corretamente.

2. Criar 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 Função CREATE_PIPE 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 do 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 do local padrão para uso com procedimentos DBMS_PIPE.

   Se você usar o Oracle Cloud Infrastructure Object Storage para armazenar mensagens, poderá usar URIs Nativos ou URIs Swift do Oracle Cloud Infrastructure. No entanto, o URI de local e a credencial devem corresponder no 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 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 Função GET_LOCATION_URI para obter mais informações.

5. Empacote e envie uma mensagem no canal.

    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 PACK_MESSAGE Procedures em Oracle Database 19c PL/SQL Packages and Types Reference ou Oracle Database 26ai PL/SQL Packages and Types Reference e SEND_MESSAGE Function para obter mais informações.

Recuperar uma Mensagem Persistente no Mesmo Banco de Dados

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

Em uma instância do Autonomous AI Database, você pode receber mensagens enviadas a um pipe de outra sessão. Os procedimentos DBMS_PIPE são procedimentos de direitos do chamador e são executados como o usuário chamado atual.

Os pipes privados pertencem ao usuário atual que cria o pipe. Os pipes privados só podem ser acessados pelo mesmo usuário que criou o pipe. Isso se aplica a pipes que usam mensagens na memória e a pipes que usam mensagens persistentes com mensagens armazenadas no Cloud Object Store.

Os pipes públicos podem ser acessados por qualquer sessão de banco de dados que tenha privilégio de execução em DBMS_PIPE. Isso se aplica a pipes que usam mensagens na memória e a pipes que usam mensagens persistentes com mensagens armazenadas no Cloud Object Store.

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 AI Database e o pipe existir, não precisará executar o comando DBMS_PIPE.CREATE_PIPE antes de receber uma mensagem. Isso se aplica quando o pipe foi criado na mesma instância, conforme mostrado em Create an Explicit Persistent Pipe and Send a Message.

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 AI Database, a credencial já existe e não precisa 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.

Consulte Procedimento SET_CREDENTIAL_NAME e Função GET_LOCATION_URI para obter mais informações.

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

Recuperar uma Mensagem Persistente Criando um Pipe em um Banco de Dados Diferente

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

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

    BEGIN
      DBMS_CLOUD.CREATE_CREDENTIAL(
        credential_name => 'my_persistent_pipe_cred',
        username => '[e-mail]',
        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 o DBMS_PIPE.

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

   Observação: Algumas ferramentas, como o SQL*Plus e o SQL Developer, usam o caractere E comercial (&) como um 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 obter a credencial 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 Função CREATE_PIPE.

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 o Object Store 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 do local padrão para uso com procedimentos DBMS_PIPE.

   Se você usar o Oracle Cloud Infrastructure Object Storage para armazenar mensagens, poderá usar URIs Nativos ou URIs Swift do Oracle Cloud Infrastructure. No entanto, o URI de local e a credencial devem corresponder no 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 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 Função GET_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 Função RECEIVE_MESSAGE para obter mais informações.

Remover uma tubulação persistente

Descreve as etapas para remover um pipe persistente.

Pipes persistentes enviam e recebem mensagens armazenando mensagens no Cloud Object Store. Use DBMS_PIPE.REMOVE_PIPE para remover um pipe persistente em uma instância do Autonomous AI Database.

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 AI Database em que ele é executado; no entanto, REMOVE_PIPE não afeta outras instâncias do Autonomous AI Database com um pipe com o mesmo nome que usa o mesmo URI de local.

2. Na instância do Autonomous AI Database em que você executou o comando 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
   

Conteúdo Relacionado

• Armazenar Mensagens em Cache com Pipes Singleton

• Pacote DBMS_PIPE (Pipes de Mensagens Persistentes)