Nesta secção, exploraremos a interface para gerenciar APIs, que requer vários tipos de API: um para o DeepL lidar com a tradução de dados, outro para contornar o CAPTCHA e outro para análise de texto.

Os tópicos abordados nesta secção incluem:

  1. Modelos de base de dados
  2. Backend para gerenciamento de API
  3. Frontend para gerenciamento de API
  4. Testes

Este capítulo será direto, pois apresenta as operações CRUD básicas. CRUD significa Create, Read, Update e Delete (Criar, Ler, Atualizar e Excluir), operações fundamentais no desenvolvimento de aplicações. Na verdade, a maioria das aplicações depende principalmente da funcionalidade CRUD.

Modelos de base de dados

Os seus modelos estão dentro de app/database/models.py.

Aqui está como é a sua tabela para armazenar APIs:

class APIs(Base):
    __tablename__ = "apis"
    id = Column(Integer, primary_key=True, index=True)
    api_name = Column(String, unique=True, index=True)
    api_provider = Column(String)
    api_type = Column(String)
    api_key = Column(String)
    model = Column(String)
    prompt = Column(Text)
    max_tokens = Column(Integer)
    timestamp = Column(DateTime, default=datetime.utcnow)
    is_active = Column(Boolean, default=False)

Algumas APIs incluem um parâmetro chamado temperatura, mas não o armazenaremos aqui. Na minha experiência, a temperatura padrão de 0,1 é suficiente para a maioria das consultas. No entanto, pode experimentar adicionar uma coluna de temperatura ao banco de dados, o que exigiria atualizações correspondentes no backend e no frontend.

Back-end para gestão de API

O código para gerir APIs está dentro de app/routes/manage_api.py. Ao contrário de algumas outras rotas, esta não usa nenhum serviço ou módulo de scraper.

O script manage_api.py define rotas FastAPI para gerir configurações de API (por exemplo, DeepL, Anthropic, OpenAI) na aplicação tornet_scraper, interagindo com a base de dados para criar, atualizar, eliminar, listar e ativar APIs. Abaixo está uma explicação concisa dos seus principais componentes e funcionalidades.

Variáveis globais

  1. logger:
    • Objetivo: Configura o registo para depuração e rastreamento de erros.
    • Detalhes: Utiliza o módulo logging com o nível INFO para registar operações e erros.
  2. manage_api_router:
    • Objetivo: Roteador FastAPI para pontos finais de gestão de API.
    • Detalhes: Configurado com o prefixo /api/manage-api e as tags [“API”, “API Management”] para organização.

Modelos Pydantic

  1. DeepLCreateRequest:
    • Finalidade: Valida os dados da solicitação POST para criar uma API DeepL.
    • Campos: api_name (str), api_key (str).
  2. IABCreateRequest:
    • Finalidade: Valida os dados da solicitação POST para criar uma API Anthropic (IAB).
    • Campos: api_name (str), api_key (str), model (str), max_tokens (int), prompt (str).
  3. CaptchaCreateRequest:
    • Objetivo: Valida os dados da solicitação POST para criar uma API OpenAI (Captcha).
    • Campos: api_name (str), api_key (str), model (str), max_tokens (int), prompt (str).
  4. UpdateRequest:
    • Objetivo: Valida os dados da solicitação PUT para atualizar uma API.
    • Campos: api_name (str), api_key (str), model (str, opcional), max_tokens (int, opcional), prompt (str, opcional).

Funções

  1. set_active_api:

    • Objetivo: Ativa uma API específica e desativa outras do mesmo fornecedor.
    • Parâmetros-chave:
      • db: SQLAlchemy Session para operações de base de dados.
      • api_id: ID inteiro da API a ativar.
      • api_provider: String que identifica o fornecedor (por exemplo, deepl, anthropic).
    • Retorna: Nenhum.
    • Detalhes: Atualiza o campo is_active para False para todas as APIs do mesmo fornecedor, exceto o api_id especificado, que é definido como True. Confirma as alterações no banco de dados.

  2. create_deepl_api:

    • Objetivo: Cria uma nova configuração da API DeepL.
    • Parâmetros principais:
      • request: DeepLCreateRequest com nome e chave da API.
      • db: SQLAlchemy Session.
    • Retorna: JSONResponse com mensagem de sucesso.
    • Detalhes: Verifica se há api_name duplicado, cria uma instância do modelo APIs (api_provider=“deepl”, api_type=“translation_api”), guarda-a na base de dados e retorna uma resposta de sucesso. Levanta HTTPException (400 para duplicados, 500 para erros).

  3. create_iab_api:

    • Objetivo: Cria uma nova configuração de API Anthropic (IAB).
    • Parâmetros-chave:
      • request: IABCreateRequest com nome da API, chave, modelo, tokens máximos e prompt.
      • db: SQLAlchemy Session.
    • Retorna: JSONResponse com mensagem de sucesso.
    • Detalhes: Semelhante a create_deepl_api, mas define api_provider=“anthropic”, api_type=“iab_api”. Valida e armazena campos adicionais (model, max_tokens, prompt).

  4. create_captcha_api:

    • Objetivo: Cria uma nova configuração de API OpenAI (Captcha).
    • Parâmetros-chave:
      • request: CaptchaCreateRequest com nome da API, chave, modelo, tokens máximos e prompt.
      • db: SQLAlchemy Session.
    • Retorna: JSONResponse com mensagem de sucesso.
    • Detalhes: Semelhante a create_iab_api, mas define api_provider=“openai”, api_type=“captcha_api”.

  5. list_apis:

    • Objetivo: Recupera todas as configurações da API.
    • Parâmetros principais:
      • db: SQLAlchemy Session.
    • Retorna: Dicionário com uma lista de APIs (ID, nome, provedor, tipo, chave, modelo, tokens máximos, prompt, carimbo de data/hora, status ativo).
    • Detalhes: consulta todos os registos APIs e devolve-os como JSON. Apresenta HTTPException (500) em caso de erros.

  6. update_api:

    • Finalidade: atualiza uma configuração de API existente.
    • Parâmetros-chave:
      • api_id: ID inteiro da API a atualizar.
      • request: UpdateRequest com campos atualizados.
      • db: Session do SQLAlchemy.
    • Retorna: JSONResponse com mensagem de sucesso.
    • Detalhes: Verifica se a API existe, verifica se há api_name duplicados, atualiza campos (apenas valores não None para model, max_tokens, prompt) e confirma as alterações. Gera HTTPException (404 se não for encontrado, 400 para duplicatas, 500 para erros).

  7. delete_api:

    • Objetivo: exclui uma configuração de API.
    • Parâmetros principais:
      • api_id: ID inteiro da API a ser excluída.
      • db: Session do SQLAlchemy.
    • Retorna: JSONResponse com mensagem de sucesso.
    • Detalhes: Verifica se a API existe, elimina-a da base de dados e confirma. Gera HTTPException (404 se não for encontrada, 500 para erros).

  8. activate_api:

    • Objetivo: Ativa uma API específica, desativando outras do mesmo fornecedor.
    • Parâmetros principais:
      • api_id: ID inteiro da API a ser ativada.
      • db: SQLAlchemy Session.
    • Retorna: JSONResponse com mensagem de sucesso.
    • Detalhes: Verifica se a API existe, chama set_active_api para alternar is_active e retorna uma mensagem de sucesso. Levanta HTTPException (404 se não for encontrado, 500 para erros).

  9. get_api:

    • Objetivo: Recupera uma única configuração de API por ID.
    • Parâmetros-chave:
      • api_id: ID inteiro da API.
      • db: Session do SQLAlchemy.
    • Retorna: Dicionário com detalhes da API (ID, nome, provedor, tipo, chave, modelo, tokens máximos, prompt, carimbo de data/hora, status ativo).
    • Detalhes: consulta a tabela APIs pelo ID especificado e retorna os seus detalhes. Gera HTTPException (404 se não encontrado, 500 para erros).

Frontend para gestão de API

O código frontend está localizado dentro de app/templates/manage_api.html.

O modelo manage_api.html estende base.html para fornecer uma interface de utilizador para gerir configurações de API (DeepL, IAB/Anthropic, Captcha/OpenAI) na aplicação tornet_scraper. Ele interage com o backend por meio de chamadas de API para criar, atualizar, excluir, listar e ativar APIs. Abaixo está uma explicação concisa de suas principais funcionalidades e sua interação com o backend.

  1. Herança de modelo:

    • Objetivo: aproveita o layout base.html para obter uma estrutura consistente.
    • Interação com o backend: herda a barra de navegação e o tratamento de mensagens flash de base.html. Define o título da página como “Gerenciamento de API” por meio de {% block title %}. Os dados iniciais da API (apis) são passados de main.py::manage_api e renderizados na tabela usando Jinja2. As mensagens flash do backend (armazenadas na sessão) são exibidas no contentor herdado.

  2. Criação da API:

    • Objetivo: permite aos utilizadores adicionar novas configurações de API para os serviços DeepL, IAB ou Captcha.
    • Interação com o backend:
      • Três botões (“Adicionar API DeepL”, “Adicionar API IAB”, “Adicionar API Captcha”) abrem os modais respectivos (addDeepLModal, addIABModal, addCaptchaModal) através de openModal().
      • Cada modal contém um formulário com campos obrigatórios (por exemplo, api_name, api_key para DeepL; model, max_tokens, prompt adicionais para IAB/Captcha).
      • O envio do formulário aciona createDeepLAPI(), createIABAPI() ou createCaptchaAPI(), enviando solicitações AJAX POST para /api/manage-api/create/deepl, /iab ou /captcha (tratadas por manage_api.py::create_deepl_api, create_iab_api, create_captcha_api).
      • O backend valida a solicitação (usando modelos Pydantic), verifica se há api_name duplicados, salva a API na tabela APIs e retorna uma mensagem de sucesso. Em caso de sucesso, uma mensagem flash é exibida, o modal é fechado, o formulário é reiniciado e a tabela é atualizada. Erros acionam uma mensagem flash de erro.

  3. Exibição e atualizações da tabela API:

    • Objetivo: exibe uma lista dinâmica de APIs com status em tempo real.
    • Interação com o backend:
      • A tabela é inicialmente preenchida com apis de main.py::manage_api, mostrando o tipo de API, nome, data de criação e status ativo.
      • A função updateTable() é executada a cada 10 segundos (através de setInterval) e após ações de criação/atualização/eliminação/ativação, enviando um pedido AJAX GET para /api/manage-api/list (tratado por manage_api.py::list_apis).
      • O backend consulta a tabela APIs e retorna uma lista JSON de APIs (ID, nome, provedor, tipo, chave, modelo, tokens máximos, prompt, carimbo de data/hora, status ativo). A tabela é atualizada com esses dados, mostrando os emblemas “Ativo” ou “Inativo”. Erros acionam uma mensagem de erro flash.

  4. Edição da API:

    • Objetivo: atualiza as configurações da API existente.
    • Interação com o backend:
      • Cada linha da tabela tem um botão “Editar” que chama openEditModal(apiId), enviando uma solicitação AJAX GET para /api/manage-api/get/{api_id} (tratada por manage_api.py::get_api).
      • O backend retorna os detalhes da API, que preenchem o formulário editAPIModal. Para APIs DeepL, apenas os campos api_name e api_key são exibidos; para IAB/Captcha, campos adicionais model, max_tokens e prompt são exibidos.
      • O envio do formulário aciona updateAPI(), enviando uma solicitação AJAX PUT para /api/manage-api/update/{api_id} (tratada por manage_api.py::update_api) com os campos atualizados. O backend valida e atualiza a tabela APIs, retornando uma mensagem de sucesso. Em caso de sucesso, uma mensagem flash é exibida, o modal é fechado e a tabela é atualizada. Erros acionam uma mensagem flash de erro.

  5. Eliminação da API:

    • Objetivo: Elimina uma configuração da API.
    • Interação com o backend:
      • Cada linha da tabela tem um botão «Eliminar» que chama openDeleteModal(apiId), abrindo o deleteAPIModal com o ID da API armazenado numa entrada oculta.
      • O botão «Eliminar» aciona confirmDeleteAPI(), enviando um pedido AJAX DELETE para /api/manage-api/delete/{api_id} (tratada por manage_api.py::delete_api).
      • O backend verifica se a API existe, elimina-a da tabela APIs e devolve uma mensagem de sucesso. Em caso de sucesso, é apresentada uma mensagem flash, o modal fecha-se e a tabela é atualizada. Os erros acionam uma mensagem flash de erro.

  6. Ativação da API:

    • Objetivo: Ativa uma API específica, desativando outras do mesmo fornecedor.
    • Interação do backend:
      • Cada linha da tabela tem um botão «Ativar» (desativado se já estiver ativo) que chama activateAPI(apiId, apiType), enviando uma solicitação AJAX POST para /api/manage-api/activate/{api_id} (tratada por manage_api.py::activate_api).
      • O backend chama set_active_api para definir is_active=True para a API especificada e False para outras do mesmo fornecedor, confirmando as alterações na tabela APIs. Em caso de sucesso, é exibida uma mensagem flash e a tabela é atualizada. Erros acionam uma mensagem flash de erro.

Embora o uso do Anthropic ou do OpenAI não seja obrigatório, simplifiquei o processo para facilitar. Noutra aplicação, implementei suporte para quatro fornecedores diferentes, oferecendo dezenas de modelos. No entanto, este nível de flexibilidade é muitas vezes desnecessário, pois adiciona complexidade ao código do backend.

Testes

Veja como pode adicionar duas APIs DeepL, mas ativar apenas uma delas de cada vez.

API Management Testing