Aprenda a acessar uma API via PL/SQL no Oracle 19c

Como acessar uma API via PL/SQL no Oracle 19c

Uma API (Application Programming Interface) é um conjunto de regras e funcionalidades que possibilita que diferentes softwares se comuniquem e interajam entre si de maneira padronizada. Com o uso de APIs, os desenvolvedores são capazes de criar aplicativos que se integram facilmente com outros sistemas, compartilham dados e oferecem serviços para outros aplicativos.

Neste artigo, vamos aprender como acessar uma API via PL/SQL no Oracle 19c. O PL/SQL é uma linguagem de programação procedural que permite executar blocos de código dentro do banco de dados, manipulando dados e realizando operações lógicas.

Para acessar uma API via PL/SQL, precisamos usar o pacote UTL_HTTP, que fornece funções e procedimentos para realizar requisições HTTP e obter respostas. O pacote UTL_HTTP faz parte da biblioteca padrão do PL/SQL e está disponível em todas as versões do Oracle Database.

Exemplo prático

Vamos supor que queremos acessar uma API que retorna o preço atual do Bitcoin em reais. A API que vamos usar é a seguinte: https://economia.awesomeapi.com.br/json/all/BTC-BRL

Para acessar essa API via PL/SQL, podemos seguir os seguintes passos:

Criar uma variável do tipo UTL_HTTP.REQ para armazenar a requisição HTTP.
Criar uma variável do tipo UTL_HTTP.RESP para armazenar a resposta HTTP.
Criar uma variável do tipo VARCHAR2 para armazenar o conteúdo da resposta.
Iniciar a requisição HTTP usando a função UTL_HTTP.BEGIN_REQUEST, passando a URL da API e o método GET como parâmetros.
Obter a resposta HTTP usando a função UTL_HTTP.GET_RESPONSE, passando a variável da requisição como parâmetro.
Ler o conteúdo da resposta usando um loop e a função UTL_HTTP.READ_TEXT, passando a variável da resposta e a variável do conteúdo como parâmetros.
Finalizar a resposta HTTP usando o procedimento UTL_HTTP.END_RESPONSE, passando a variável da resposta como parâmetro.
Exibir o conteúdo da resposta usando o procedimento DBMS_OUTPUT.PUT_LINE, passando a variável do conteúdo como parâmetro.

O código PL/SQL ficaria assim:

declare
  v_req utl_http.req; -- variável da requisição
  v_res utl_http.resp; -- variável da resposta
  v_content varchar2(4000); -- variável do conteúdo
begin
  -- iniciar a requisição HTTP
  v_req := utl_http.begin_request('https://economia.awesomeapi.com.br/json/all/BTC-BRL', 'GET');
  
  -- obter a resposta HTTP
  v_res := utl_http.get_response(v_req);
  
  -- ler o conteúdo da resposta
  begin
    loop
      utl_http.read_text(v_res, v_content);
      -- exibir o conteúdo da resposta
      dbms_output.put_line(v_content);
    end loop;
    -- finalizar a resposta HTTP
    utl_http.end_response(v_res);
  exception
    when utl_http.end_of_body then
      utl_http.end_response(v_res);
  end;
end;

Ao executar esse código, obteremos uma saída semelhante a esta:

{"BTC":{"code":"BTC","codein":"BRL","name":"Bitcoin","high":"243000","low":"233000","varBid":"-10000","pctChange":"-4.1","bid":"233000","ask":"233000","timestamp":"1628174400","create_date":"2021-08-05 17:00:00"}}

Essa saída é um objeto JSON que contém as informações sobre o preço do Bitcoin em reais. Podemos usar funções JSON do Oracle Database para extrair os valores desejados desse objeto.

Por exemplo, se quisermos obter apenas o valor de compra (bid) do Bitcoin, podemos usar a função JSON_VALUE, passando o conteúdo da resposta e o caminho do atributo como parâmetros. O código ficaria assim:

declare
  v_req utl_http.req; -- variável da requisição
  v_res utl_http.resp; -- variável da resposta
  v_content varchar2(4000); -- variável do conteúdo
  v_bid number; -- variável do valor de compra
begin
  -- iniciar a requisição HTTP
  v_req := utl_http.begin_request('https://economia.awesomeapi.com.br/json/all/BTC-BRL', 'GET');
  
  -- obter a resposta HTTP
  v_res := utl_http.get_response(v_req);
  
  -- ler o conteúdo da resposta
  begin
    loop
      utl_http.read_text(v_res, v_content);
    end loop;
    -- finalizar a resposta HTTP
    utl_http.end_response(v_res);
  exception
    when utl_http.end_of_body then
      utl_http.end_response(v_res);
  end;
  
  -- extrair o valor de compra do Bitcoin
  v_bid := json_value(v_content, '$.BTC.bid');
  
  -- exibir o valor de compra do Bitcoin
  dbms_output.put_line('O valor de compra do Bitcoin é: ' || v_bid || ' reais');
end;

Ao executar esse código, obteremos uma saída semelhante a esta:

O valor de compra do Bitcoin é: 233000 reais

Considerações

Para acessar uma API via PL/SQL, é necessário ter permissão para abrir uma conexão TCP com o servidor da API. Isso pode ser feito usando o pacote DBMS_NETWORK_ACL_ADMIN, que permite criar e atribuir listas de controle de acesso (ACL) para os hosts e portas desejados.

Por exemplo, se quisermos permitir que o usuário SCOTT acesse a API do exemplo anterior, podemos usar o seguinte código:

begin
  -- criar uma ACL para acessar a API
  dbms_network_acl_admin.create_acl(
    acl => 'api_acl.xml',
    description => 'ACL para acessar a API do Bitcoin',
    principal => 'SCOTT',
    is_grant => true,
    privilege => 'connect',
    start_date => systimestamp,
    end_date => null
  );
  
  -- atribuir a ACL para o host e porta da API
  dbms_network_acl_admin.assign_acl(
    acl => 'api_acl.xml',
    host => 'economia.awesomeapi.com.br',
    lower_port => 443,
    upper_port => null
  );
  
  commit;
end;

Bônus: Como criar uma API em Python

Python é uma linguagem de programação de alto nível, dinâmica, interpretada e multiparadigma. Ela é amplamente usada para diversos fins, como desenvolvimento web, análise de dados, automação, inteligência artificial e muito mais.

Python também é uma ótima linguagem para criar APIs, pois oferece diversos frameworks e bibliotecas que facilitam e agilizam o processo de desenvolvimento. Alguns dos frameworks mais populares para criar APIs em Python são:

Flask: um framework leve e simples que permite criar aplicações web e APIs com poucas linhas de código. Ele é ideal para projetos pequenos e rápidos, mas também pode ser usado para projetos maiores com o uso de extensões.
Django: um framework completo e robusto que segue o padrão MVC (Model-View-Controller) e oferece diversas funcionalidades integradas, como autenticação, administração, ORM (Object-Relational Mapping) e muito mais. Ele é ideal para projetos complexos e escaláveis que exigem alta performance e segurança.
FastAPI: um framework moderno e rápido que segue o padrão ASGI (Asynchronous Server Gateway Interface) e oferece suporte a requisições assíncronas, validação de dados, documentação automática e muito mais. Ele é ideal para projetos que requerem alta performance e produtividade.

Exemplo prático

Vamos supor que queremos criar uma API simples em Python que retorna uma mensagem de boas-vindas com o nome do usuário. A API que vamos criar é a seguinte: http://localhost:5000/hello/<name>

Para criar essa API simples em Python, podemos seguir os seguintes passos:

Escolher um framework, como Flask, Django ou FastAPI. Neste exemplo, usaremos o Flask devido à sua simplicidade e facilidade de uso.
Instalar o Flask e criar um arquivo chamado app.py com o seguinte código:

# importar o Flask
from flask import Flask

# criar uma instância do Flask
app = Flask(__name__)

# definir uma rota para a API
@app.route('/hello/<name>')
def hello(name):
  # retornar uma mensagem de boas-vindas com o nome do usuário
  return f'Olá, {name}! Seja bem-vindo à API do Flask!'

# executar a aplicação
if __name__ == '__main__':
  app.run()

Executar o arquivo app.py no terminal usando o comando:

python app.py

Acessar a API no navegador usando a URL: [http://localhost:5000/hello/<name>], substituindo <name> pelo nome desejado. Por exemplo, se acessarmos a URL: [http://localhost:5000/hello/Giovano], obteremos a seguinte saída:

Olá, Giovano! Seja bem-vindo à API do Flask!

Considerações

Para criar uma API em Python, é necessário ter o Python instalado na máquina, bem como o framework escolhido. O Flask pode ser instalado usando o gerenciador de pacotes pip, com o comando:

pip install flask

O Flask é um framework que segue o princípio da convenção sobre configuração, ou seja, ele usa valores padrão para a maioria das opções, como a porta, o modo de depuração e o ambiente. No entanto, esses valores podem ser alterados conforme a necessidade, usando variáveis de ambiente ou parâmetros na função app.run().

Por exemplo, se quisermos mudar a porta da aplicação para 8080, podemos usar o parâmetro port na função app.run(), assim:

app.run(port=8080)

Ou podemos usar a variável de ambiente FLASK_RUN_PORT, assim:

export FLASK_RUN_PORT=8080

Para mais informações sobre o Flask e como criar APIs mais complexas e completas com ele, consulte a documentação oficial do framework.

Abs

Referências

Documentação oficial do pacote UTL_HTTP, que explica como usar as funções e procedimentos para realizar requisições HTTP e obter respostas.
Documentação oficial do Oracle Database sobre JSON, que explica como usar as funções JSON para manipular dados no formato JSON.
Documentação oficial do pacote DBMS_NETWORK_ACL_ADMIN, que explica como criar e atribuir listas de controle de acesso para os hosts e portas desejados.
Documentação oficial do Flask, que explica como instalar e usar o framework Flask para criar aplicações web e APIs em Python.

Aprenda a acessar uma API via PL/SQL no Oracle 19c

Como acessar uma API via PL/SQL no Oracle 19c

Exemplo prático

Considerações

Bônus: Como criar uma API em Python

Exemplo prático

Considerações

Giovano Silva

Deixe um comentário Cancelar resposta