SDK v1 — Documentação Legacy

Esta página documenta o Actions SDK v1. Para a versão atual (v2), consulte a documentação do SDK v2.

HTTP Client

Visão Geral

O http_client padroniza chamadas HTTP dentro de Actions com:

• Timeout e retry configuráveis
• Tratamento canônico de erros (SDKHttpError)
• Suporte a expected_status para aceitar status não-2xx como sucesso
• Modo de IP fixo (use_fixed_ip=True)
• Sanitização de dados sensíveis para observabilidade
• Instrumentação automática de span

O http_client está disponível tanto em Actions quanto em Tasks. Em ambos os contextos, o SDK expõe diretamente http_client, RetryPolicy, HttpResult e SDKHttpError no namespace de execução.

---

Métodos Disponíveis

• http_client.get
• http_client.post
• http_client.put
• http_client.patch
• http_client.delete

Todos os métodos compartilham os mesmos parâmetros opcionais e o mesmo fluxo interno de retry, erro canônico e observabilidade.

Parâmetros:

• url (str): URL de destino
• params (dict): query params
• headers (dict): headers da chamada
• json (dict | list): payload JSON — disponível em post, put, patch
• data (dict | str | bytes): payload raw/form — disponível em post, put, patch
• timeout (float): timeout em segundos (default: 30 segundos)
• follow_redirects (bool): seguir redirects (padrão: True)
• use_fixed_ip (bool): habilita modo de IP fixo
• x_redirect_key (str): valor do header X-Redirect quando IP fixo estiver ativo
• retry_policy (RetryPolicy): política de retry customizada
• expected_status (set[int]): status aceitos como sucesso além de 2xx
• sensitive_json_keys (list[str]): chaves JSON a sanitizar no trace

Retorno:

• HttpResult em caso de sucesso (2xx ou status em expected_status)

Estrutura de retorno da chamada:

Campo	Tipo	Descrição
status_code	int	Status HTTP da resposta
headers	dict	Headers da resposta
text	str	Body da resposta como string
duration_ms	float	Tempo total da chamada em ms
request_url	str	URL final (após redirects)
request_method	str	Método HTTP utilizado

Exceção:

• SDKHttpError em falhas HTTP, rede ou validação

---

RetryPolicy

Estrutura de configuração do retry:

Campo	Tipo	Padrão	Descrição
max_attempts	int	3	Número máximo de tentativas (incluindo a inicial)
base_delay_ms	int	0	Delay base em ms para backoff exponencial
max_delay_ms	int	1000	Delay máximo em ms
jitter_factor	float	0.1	Fator de variação aleatória para evitar thundering herd (0.0 a 1.0)
retry_on_status_codes	set[int]	{429, 500, 502, 503, 504}	Status codes que devem ser retentados

Interação com expected_status

Status codes presentes em expected_status não são retentados, mesmo que estejam em retry_on_status_codes. O expected_status tem precedência.

policy = RetryPolicy(
    max_attempts=3,
    base_delay_ms=100,
    max_delay_ms=500,
    jitter_factor=0.1,
    retry_on_status_codes={429, 502, 503, 504},
)

---

Exemplos Práticos

Exemplo 1: GET simples

def consultar_status():
    try:
        result = http_client.get(
            "https://postman-echo.com/get?source=actions_sdk",
            timeout=8.0,
        )
        data = result.json()
        return ResponseToUser(message=f"OK. Origin: {data.get('origin', 'N/A')}")
    except Exception as e:
        error_type = getattr(e, "error_type", "unknown")
        message = getattr(e, "message", str(e))
        return ResponseToUser(
            message=f"Request failed ({error_type}): {message}",
            detail=f"Request failed ({error_type}): {message}",
            status=ResponseStatus.ERROR,
        )

Exemplo 2: Aceitar 404 com expected_status

def consultar_recurso():
    try:
        result = http_client.get(
            "https://api.interna.com/recurso/123",
            expected_status={404},
            timeout=5.0,
        )
        if result.status_code == 404:
            return ResponseToUser(message="Recurso não encontrado.")
        data = result.json()
        return ResponseToUser(message=f"Recurso: {data.get('nome', 'N/A')}")
    except Exception as e:
        message = getattr(e, "message", str(e))
        return ResponseToUser(
            message=f"Erro: {message}",
            detail=f"Erro: {message}",
            status=ResponseStatus.ERROR,
        )

Exemplo 3: POST com JSON

def enviar_dados(nome: str, email: str):
    try:
        result = http_client.post(
            "https://api.interna.com/cadastros",
            json={"nome": nome, "email": email},
            timeout=10.0,
        )
        data = result.json()
        return ResponseToUser(message=f"Cadastrado com ID: {data.get('id')}")
    except Exception as e:
        error_type = getattr(e, "error_type", "unknown")
        status_code = getattr(e, "status_code", None)
        message = getattr(e, "message", str(e))
        return ResponseToUser(
            message=f"Falha ({error_type}, status={status_code}): {message}",
            detail=f"Falha ({error_type}, status={status_code}): {message}",
            status=ResponseStatus.ERROR,
        )

Exemplo 4: Retry customizado para erros transitórios

def consultar_com_retry():
    try:
        policy = RetryPolicy(
            max_attempts=3,
            base_delay_ms=100,
            max_delay_ms=500,
            jitter_factor=0.1,
            retry_on_status_codes={429, 502, 503},
        )
        result = http_client.get(
            "https://api.interna.com/status",
            retry_policy=policy,
            timeout=5.0,
        )
        return ResponseToUser(message=f"Status: {result.status_code}")
    except Exception as e:
        error_type = getattr(e, "error_type", "unknown")
        status_code = getattr(e, "status_code", None)
        message = getattr(e, "message", str(e))
        return ResponseToUser(
            message=f"Falha após retries ({error_type}, status={status_code}): {message}",
            detail=f"Falha após retries ({error_type}, status={status_code}): {message}",
            status=ResponseStatus.ERROR,
        )

Exemplo 5: GET com IP fixo

def consultar_via_ip_fixo():
    try:
        result = http_client.get(
            "https://api.parceiro.com/dados",
            use_fixed_ip=True,
            x_redirect_key="nome-do-redirect",
            timeout=10.0,
        )
        data = result.json()
        return ResponseToUser(message=f"Dados recebidos: {data.get('status', 'N/A')}")
    except Exception as e:
        error_type = getattr(e, "error_type", "unknown")
        status_code = getattr(e, "status_code", None)
        message = getattr(e, "message", str(e))
        return ResponseToUser(
            message=f"Falha IP fixo ({error_type}, status={status_code}): {message}",
            detail=f"Falha IP fixo ({error_type}, status={status_code}): {message}",
            status=ResponseStatus.ERROR,
        )

Exemplo 6: Uso em Tasks

Em Tasks, o módulo pode ser usado da mesma forma que em Actions, mas o retorno de uma task deve ser um dict ou uma lista de dicts.

def buscar_habilidade():
    """Fetch a specific skill by ID with a custom retry policy."""
    try:
        skill_id = "seu-skill-id-aqui"
        policy = RetryPolicy(
            max_attempts=2,
            base_delay_ms=200,
            max_delay_ms=1000,
            jitter_factor=0.1,
            retry_on_status_codes={429, 502, 503},
        )
        result = http_client.get(
            f"https://api.interna.com/admin/skill/{skill_id}",
            headers={"slug": "seu-slug-aqui"},
            retry_policy=policy,
            timeout=5.0,
        )
        return {"status": result.status_code, "skill_id": skill_id}
    except Exception as e:
        error_type = getattr(e, "error_type", "unknown")
        status_code = getattr(e, "status_code", None)
        message = getattr(e, "message", str(e))
        return {"error": error_type, "status_code": status_code, "message": message}

---

Boas Práticas

✅ Faça

• Use os métodos de conveniência (get, post, etc.) ao invés de construir a request manualmente
• Use expected_status quando 404/409/503 forem resultados válidos de negócio
• Use RetryPolicy para cenários com erros transitórios conhecidos
• Defina sensitive_json_keys quando o payload contiver PII ou segredos

❌ Evite

• Implementar lógica de retry manualmente fora do client
• Ignorar status_code em fluxos de negócio críticos
• Expor tokens ou segredos nas mensagens de erro retornadas ao usuário