Cliente SDK Python

A secção atual detalha o cliente SDK Python da Jotelulu para o acesso simplificado à API Pública da Jotelulu.

📖 Documentação da API

Endpoints Principais

Serviço	Endpoint	Descrição
Núcleo	/core/v1/organizations	Gestão de organizações
Núcleo	/core/v1/organizations/{id}/users	Gestão de utilizadores
Servidores	/servers/v1/subscriptions/{id}/instances	Instâncias de servidor
Servidores	/servers/v1/subscriptions/{id}/networks	Gestão de redes
Desktops Remotos	/remote-desktops/v1/subscriptions/{id}/instances	Instâncias de Desktop Remoto
Desktops Remotos	/remote-desktops/v1/subscriptions/{id}/applications	Aplicações

Modelos Principais

• Organização: Representa uma organização
• Utilizador: Utilizador do sistema
• Subscrição: Subscrição a serviços
• Instância: Instância de servidor ou Desktop Remoto
• Aplicação: Aplicação instalável
• NetworkInterface: Interface de rede
• FirewallInboundRule: Regra de firewall

🚀 Instalação em Ambiente Virtual (Recomendado)

# Criar ambiente virtual
python -m venv jotelulu-env

# Ativar ambiente virtual
# No Windows:
jotelulu-env\Scripts\activate
# No Linux/macOS:
source jotelulu-env/bin/activate

# Instalar o SDK
pip install generated-client-python

🔐 Autenticação com JWT

Configuração Básica

import openapi_client
from openapi_client.configuration import Configuration
from openapi_client.api_client import ApiClient

# Configurar o cliente com JWT
configuration = Configuration(
    host="https://connect-eu1.jotelulu.com",  # Produção
    access_token="your_jwt_token_here"
)

# Criar cliente API
api_client = ApiClient(configuration)

Configuração de Ambientes

# Ambientes disponíveis
ENVIRONMENTS = {
    'production': 'https://connect-eu1.jotelulu.com'
}

# Configuração por ambiente
def create_jotelulu_client(environment='production', token=None):
    configuration = Configuration(
        host=ENVIRONMENTS[environment],
        access_token=token
    )
    return ApiClient(configuration)

Gestão Segura de Tokens

import os
from openapi_client import Configuration, ApiClient

class JoteluluClient:
    def __init__(self, environment='production'):
        # Obter token a partir de variáveis de ambiente
        token = os.getenv('JOTELULU_JWT_TOKEN')
        if not token:
            raise ValueError("A variável de ambiente JOTELULU_JWT_TOKEN é obrigatória")
        
        self.configuration = Configuration(
            host=ENVIRONMENTS.get(environment, ENVIRONMENTS['production']),
            access_token=token
        )
        self.api_client = ApiClient(self.configuration)
    
    def get_organizations_api(self):
        from openapi_client.api.organizations_api import OrganizationsApi
        return OrganizationsApi(self.api_client)
    
    def get_instances_api(self):
        from openapi_client.api.instances_api import InstancesApi
        return InstancesApi(self.api_client)

🐍 Integração com Django

1. Instalação no Projeto Django

# Criar novo projeto Django
django-admin startproject mi_projeto_jotelulu
cd mi_projeto_jotelulu

# Criar aplicação
python manage.py startapp jotelulu_integration

# Instalar dependências
pip install django
pip install generated-client-python

2. Configuração em settings.py

# settings.py
import os

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'jotelulu_integration',  # A tua aplicação
]

# Configuração Jotelulu
JOTELULU_SETTINGS = {
    'ENVIRONMENT': os.getenv('JOTELULU_ENV', 'production'),
    'JWT_TOKEN': os.getenv('JOTELULU_JWT_TOKEN'),
    'API_ENDPOINTS': {
        'production': 'https://connect-eu1.jotelulu.com'
    }
}

3. Serviço Django para Jotelulu

# jotelulu_integration/services.py
from django.conf import settings
import openapi_client
from openapi_client.api.organizations_api import OrganizationsApi
from openapi_client.api.instances_api import InstancesApi
from openapi_client.api.applications_api import ApplicationsApi
from openapi_client.exceptions import ApiException

class JoteluluService:
    def __init__(self):
        jotelulu_config = settings.JOTELULU_SETTINGS
        environment = jotelulu_config['ENVIRONMENT']
        
        self.configuration = openapi_client.Configuration(
            host=jotelulu_config['API_ENDPOINTS'][environment],
            access_token=jotelulu_config['JWT_TOKEN']
        )
        self.api_client = openapi_client.ApiClient(self.configuration)
    
    def get_user_organizations(self):
        """Obter organizações do utilizador atual"""
        try:
            api_instance = OrganizationsApi(self.api_client)
            response = api_instance.list_user_organizations()
            return response.data
        except ApiException as e:
            print(f"Erro ao obter organizações: {e}")
            return []
    
    def get_organization_users(self, organization_id):
        """Obter utilizadores de uma organização"""
        try:
            api_instance = OrganizationsApi(self.api_client)
            response = api_instance.list_organization_users(organization_id)
            return response.data
        except ApiException as e:
            print(f"Erro ao obter utilizadores: {e}")
            return []
    
    def get_remote_desktop_instances(self, subscription_id):
        """Obter instâncias de Desktop Remoto"""
        try:
            api_instance = InstancesApi(self.api_client)
            response = api_instance.list_remote_desktop_subscription_instances(subscription_id)
            return response.data
        except ApiException as e:
            print(f"Erro ao obter instâncias: {e}")
            return []

4. Vistas Django

# jotelulu_integration/views.py
from django.shortcuts import render
from django.http import JsonResponse
from django.views.decorators.csrf import csrf_exempt
from .services import JoteluluService

def dashboard(request):
    """Vista principal do dashboard"""
    jotelulu = JoteluluService()
    organizations = jotelulu.get_user_organizations()
    
    context = {
        'organizations': organizations,
        'user': request.user
    }
    return render(request, 'jotelulu_integration/dashboard.html', context)

def organization_detail(request, organization_id):
    """Detalhe de uma organização"""
    jotelulu = JoteluluService()
    users = jotelulu.get_organization_users(organization_id)
    
    return JsonResponse({
        'organization_id': organization_id,
        'users': [{'id': user.id, 'name': user.name, 'email': user.email} for user in users]
    })

@csrf_exempt
def create_organization_user(request, organization_id):
    """Criar utilizador na organização"""
    if request.method == 'POST':
        import json
        from openapi_client.model.create_organization_user_request import CreateOrganizationUserRequest
        from openapi_client.model.create_organization_user_request_data import CreateOrganizationUserRequestData
        
        data = json.loads(request.body)
        jotelulu = JoteluluService()
        
        try:
            api_instance = jotelulu.get_organizations_api()
            user_request = CreateOrganizationUserRequest(
                data=CreateOrganizationUserRequestData(
                    email=data['email'],
                    name=data['name'],
                    last_name=data['lastName'],
                    password=data.get('password')
                )
            )
            
            response = api_instance.create_organization_user(organization_id, user_request)
            return JsonResponse({'success': True, 'user_id': response.data.user_id})
            
        except Exception as e:
            return JsonResponse({'success': False, 'error': str(e)})
    
    return JsonResponse({'error': 'Método não permitido'}, status=405)

5. URLs Django

# jotelulu_integration/urls.py
from django.urls import path
from . import views

app_name = 'jotelulu_integration'

urlpatterns = [
    path('', views.dashboard, name='dashboard'),
    path('organization/<str:organization_id>/', views.organization_detail, name='organization_detail'),
    path('organization/<str:organization_id>/users/', views.create_organization_user, name='create_user'),
]

# urls.py principal do projeto
from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('jotelulu/', include('jotelulu_integration.urls')),
]

📚 Exemplos de Utilização

Gestão de Organizações

from openapi_client.api.organizations_api import OrganizationsApi
from openapi_client.model.create_organization_user_request import CreateOrganizationUserRequest

# Inicializar cliente
client = JoteluluClient()
org_api = client.get_organizations_api()

# Listar organizações do utilizador
organizations = org_api.list_user_organizations()
print(f"Organizações encontradas: {len(organizations.data)}")

# Listar utilizadores de uma organização
org_id = "ORG-123"
users = org_api.list_organization_users(org_id)
for user in users.data:
    print(f"Utilizador: {user.name} ({user.email})")

# Criar novo utilizador
new_user_request = CreateOrganizationUserRequest(
    data={
        'email': '[e-mail]',
        'name': 'Novo',
        'lastName': 'Utilizador',
        'password': 'password123',
        'twoFactorAuthRequired': True
    }
)
result = org_api.create_organization_user(org_id, new_user_request)
print(f"Utilizador criado com ID: {result.data.user_id}")

Gestão de Instâncias e Servidores

from openapi_client.api.instances_api import InstancesApi
from openapi_client.api.instance_api import InstanceApi

# APIs de instâncias
instances_api = InstancesApi(api_client)
instance_api = InstanceApi(api_client)

# Listar instâncias de Desktop Remoto
subscription_id = "SUB-456"
rd_instances = instances_api.list_remote_desktop_subscription_instances(subscription_id)

for instance in rd_instances.data:
    print(f"Instância: {instance.name} - Estado: {instance.state}")
    
    # Obter progresso de implementação
    if instance.state == 'creating':
        progress = instance_api.get_instance_progress(subscription_id, instance.id)
        print(f"Progresso: {progress.data.progress}")

# Listar instâncias de servidor
server_instances = instance_api.list_server_subscription_instances(subscription_id)
print(f"Instâncias de servidor: {len(server_instances.data)}")

Gestão de Aplicações

from openapi_client.api.applications_api import ApplicationsApi
from openapi_client.model.create_instance_application_request import CreateInstanceApplicationRequest

apps_api = ApplicationsApi(api_client)

# Listar aplicações disponíveis
available_apps = apps_api.list_applications()
print("Aplicações disponíveis:")
for app in available_apps.data:
    print(f"- {app.name} (ID: {app.id})")

# Listar aplicações de uma subscrição
subscription_apps = apps_api.list_subscription_applications(subscription_id)
print(f"Aplicações instaladas: {len(subscription_apps.data)}")

# Instalar nova aplicação
install_request = CreateInstanceApplicationRequest(
    data={
        'instanceId': 'INST-789',
        'applicationId': 'APP-123'
    }
)
result = apps_api.create_instance_application(subscription_id, install_request)
print(f"Aplicação instalada: {result.data[0].id}")

Gestão de Redes e Firewall

from openapi_client.api.networks_api import NetworksApi
from openapi_client.api.firewall_api import FirewallApi
from openapi_client.model.create_isolated_network_request import CreateIsolatedNetworkRequest
from openapi_client.model.create_firewall_inbound_rule_request import CreateFirewallInboundRuleRequest

networks_api = NetworksApi(api_client)
firewall_api = FirewallApi(api_client)

# Criar rede isolada
network_request = CreateIsolatedNetworkRequest(
    data={
        'name': 'Minha Rede privada',
        'network': '192.168.100.0',
        'netmask': '255.255.255.0',
        'gateway': '192.168.100.1'
    }
)
network = networks_api.create_isolated_network(subscription_id, network_request)
print(f"Rede criada: {network.data.name}")

# Criar regra de firewall
firewall_rule = CreateFirewallInboundRuleRequest(
    data={
        'protocol': 'TCP',
        'publicNetworkId': 'NET-456',
        'privateNicAddressIpId': 'NIC-789',
        'publicPort': 80,
        'privatePort': 8080,
        'origin': '0.0.0.0/0'
    }
)
rule = firewall_api.create_firewall_inbound_rule(
    subscription_id, 
    network.data.main_network_id, 
    firewall_rule
)
print(f"Regra de firewall criada: {rule.data.id}")

🛠️ Gestão de Erros

from openapi_client.exceptions import ApiException
import logging

# Configurar logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def safe_api_call(api_function, *args, **kwargs):
    """Wrapper para chamadas seguras à API"""
    try:
        return api_function(*args, **kwargs)
    except ApiException as e:
        logger.error(f"Erro da API: {e.status} - {e.reason}")
        logger.error(f"Corpo da resposta: {e.body}")
        
        # Gestão específica por código de erro
        if e.status == 401:
            logger.error("Token JWT inválido ou expirado")
        elif e.status == 403:
            logger.error("Permissões insuficientes")
        elif e.status == 404:
            logger.error("Recurso não encontrado")
        elif e.status >= 500:
            logger.error("Erro interno do servidor")
        
        return None
    except Exception as e:
        logger.error(f"Erro inesperado: {str(e)}")
        return None

# Exemplo de utilização
organizations = safe_api_call(org_api.list_user_organizations)
if organizations:
    print(f"Organizações obtidas: {len(organizations.data)}")
else:
    print("Não foi possível obter as organizações")

🔧 Configuração Avançada

Cliente Personalizado com Retry

import time
from functools import wraps

def retry_on_failure(max_retries=3, delay=1):
    """Decorador para tentar novamente chamadas falhadas"""
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            for attempt in range(max_retries):
                try:
                    return func(*args, **kwargs)
                except ApiException as e:
                    if e.status >= 500 and attempt < max_retries - 1:
                        time.sleep(delay * (2 ** attempt))  # Backoff exponencial
                        continue
                    raise
            return None
        return wrapper
    return decorator

class RobustJoteluluClient(JoteluluClient):
    @retry_on_failure(max_retries=3)
    def get_organizations_with_retry(self):
        api = self.get_organizations_api()
        return api.list_user_organizations()

Configuração de Timeout

from openapi_client.configuration import Configuration
from openapi_client.api_client import ApiClient

# Configuração com timeouts personalizados
configuration = Configuration(
    host="https://connect-eu1.jotelulu.com",
    access_token="your_token"
)

# Configurar timeouts
api_client = ApiClient(configuration)
api_client.rest_client.pool_manager.connection_pool_kw['timeout'] = 30

---