Arquivo HTTP

validado

Use http_file para arquivos limitados servidos por HTTP(S), especialmente quando o runtime do Spark não consegue ler caminhos HTTPS arbitrários diretamente. O conector baixa o arquivo no driver, materializa-o para o Spark e preserva os metadados de origem nas tabelas de controle.

Quando usar

Conjuntos de dados públicos

Download direto de arquivo

Use isto para arquivos CSV, JSON, JSONL, NDJSON ou de texto limitados expostos por HTTP(S).

Reserva de runtime

Spark não consegue ler HTTPS

O driver baixa o arquivo e, em seguida, entrega um arquivo local/preparado materializado para o Spark.

Arquivos pequenos e médios

Cargas controladas

Use limites explícitos de tempo limite, repetição e tamanho. Mova feeds recorrentes grandes para armazenamento de objetos.

Limite do conector

Sem análise de negócios

Use transform.shape ou contratos downstream para normalização de carga útil aninhada.

Requisitos de runtime

Exigência	Detalhes
Saída do motorista	O driver Databricks ou o processo Spark local deve atingir o endpoint HTTP(S).
Limites de carga útil	Configure o tempo limite/nova tentativa e evite downloads ilimitados.
Suporte de formato	O Spark deve oferecer suporte ao formato de arquivo declarado após a materialização do arquivo.
Autenticação	Use cabeçalhos ou URLs protegidos por segredo para arquivos autenticados.

Exemplo básico

YAML

source:
  type: connector
  connector: http_file
  path: https://example.org/data/orders.csv
  format: csv
  options:
    header: true
    inferSchema: false
  read:
    schema: "order_id STRING, order_ts TIMESTAMP, amount DOUBLE"
    source_complete: true
  limits:
    timeout_seconds: 60
    retry_attempts: 3
    retry_backoff_seconds: 2
    max_bytes: 52428800
    max_records: 100000

target:
  catalog: contractforge
  schema: bronze_examples
  table: b_http_orders

layer: bronze
mode: overwrite

Python

from contractforge import ingest

result = ingest(
    source={
        "type": "connector",
        "connector": "http_file",
        "path": "https://example.org/data/orders.csv",
        "format": "csv",
        "options": {"header": True, "inferSchema": False},
        "read": {
            "schema": "order_id STRING, order_ts TIMESTAMP, amount DOUBLE",
            "source_complete": True,
        },
        "limits": {
            "timeout_seconds": 60,
            "retry_attempts": 3,
            "retry_backoff_seconds": 2,
            "max_bytes": 52_428_800,
            "max_records": 100_000,
        },
    },
    catalog="contractforge",
    target_schema="bronze_examples",
    target_table="b_http_orders",
    layer="bronze",
    mode="overwrite",
)

Formatos suportados

Os formatos suportados são csv, json, jsonl, ndjson e text. Os aliases http_csv, http_json e http_text estão disponíveis quando você deseja que o nome do conector implique o formato do arquivo.

Orientação operacional

• Use este conector para arquivos pequenos e médios, não para extração ilimitada de API.
• Defina limites explícitos de bytes, tempo limite e novas tentativas porque o driver executa o download.
• Para feeds recorrentes de alto volume, coloque os arquivos no armazenamento de objetos e use o Auto Loader ou um conector de arquivo.

Padrão de conjunto de dados público

Esse padrão é útil para extrações públicas completas que são mais fáceis de baixar como um arquivo limitado do que de acessar por meio de um leitor de sistema de arquivos Spark.

YAML

source:
  type: connector
  connector: http_file
  path: https://example.org/public/covid.csv
  format: csv
  options:
    header: true
    inferSchema: false
  read:
    schema: "submission_date DATE, state STRING, tot_cases BIGINT"
    source_complete: true
  limits:
    timeout_seconds: 60
    retry_attempts: 3
    retry_backoff_seconds: 2
    max_bytes: 52428800
    max_records: 100000

target:
  catalog: contractforge
  schema: bronze_health
  table: b_public_covid

layer: bronze
mode: overwrite

Python

from contractforge import ingest

result = ingest(
    source={
        "type": "connector",
        "connector": "http_file",
        "path": "https://example.org/public/covid.csv",
        "format": "csv",
        "options": {"header": True, "inferSchema": False},
        "read": {
            "schema": "submission_date DATE, state STRING, tot_cases BIGINT",
            "source_complete": True,
        },
        "limits": {"timeout_seconds": 60},
    },
    catalog="contractforge",
    target_schema="bronze_health",
    target_table="b_public_covid",
    layer="bronze",
    mode="overwrite",
)

Use apenas arquivos limitados

Para feeds recorrentes de alto volume, coloque os arquivos no armazenamento de objetos e use o Auto Loader ou um conector de arquivo.

Validação operacional

SELECT
  run_id,
  status,
  source_connector,
  source_format,
  source_path,
  rows_read,
  rows_written,
  source_metrics_json
FROM main.ops.ctrl_ingestion_runs
WHERE source_connector IN ('http_file', 'http_csv', 'http_json', 'http_text')
ORDER BY started_at_utc DESC;

Problemas comuns

Sintoma	Causa provável	Ação
DNS ou falha de conexão	O driver não pode alcançar o host.	Valide listas de permissões de saída, DNS, proxy e endpoint do runtime.
Tempo esgotado	O arquivo é muito grande ou o endpoint está lento.	Aumente os limites com cautela ou mova o feed para o armazenamento de objetos.
Esquema inesperado	O formato do arquivo foi alterado ou a inferência de esquema foi usada.	Declare o esquema explícito e as opções do leitor.
Pressão de memória	A carga útil é muito grande para download do lado do driver.	Use a ingestão de armazenamento de objetos ou o Auto Loader para feeds grandes.

Como este conector se enquadra no contrato

Mantenha as preocupações de extração em source, normalização estrutural em transform, validação em quality_rules e semântica de destino em mode. Essa separação mantém os exemplos portáteis e evita que correções de runtime específicas do conector se tornem uma lógica de negócios oculta.