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 reaisConsideraçõ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 flaskO 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=8080Para 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.