API REST

validado

Use o conector da API REST para extração de API HTTP limitada com configuração de solicitação explícita, paginação, limites, segredos redigidos e extração de registros ou captura de carga útil bruta.

Quando usar

APIs operacionais

APIs limitadas

Instantâneos diários, endpoints de referência, pequenas APIs paginadas, conjuntos de dados públicos e feeds operacionais controlados.

Caminho alternativo

Grandes extratos

Se a carga útil for muito grande ou de longa duração, coloque os arquivos primeiro no armazenamento de objetos e use a ingestão de arquivos ou do carregador automático.

Limite do conector

Recuperar, não modelar

O conector deve buscar páginas e expor metadados. Use transform.shape para registros aninhados, matrizes e projeções de domínio.

Limite de runtime

HTTP do lado do driver

As solicitações são feitas a partir do driver Python. As listas de permissões de saída de rede, DNS, proxy e API devem ser resolvidas pela plataforma.

Requisitos de runtime

Exigência	Detalhes
Saída do motorista	O driver Python deve alcançar o endpoint da API, incluindo configuração de DNS, proxy, firewall e lista de permissões.
Limites de API	Use limites explícitos de página, registro, byte, tempo limite e novas tentativas.
Autenticação	Armazene tokens, chaves e cabeçalhos em segredos. Os metadados redigidos são gravados em tabelas de controle.
Modelo de carga útil	Use o modo de registro para matrizes tabulares e o modo bruto para documentos JSON complexos ou em evolução.

Exemplo básico

Use a extração de registros quando a resposta contiver uma lista clara de registros e o formato JSON já estiver próximo do tabular.

source:
  type: connector
  connector: rest_api
  request:
    method: GET
    url: https://api.example.com/v1/orders
    headers:
      Accept: application/json
      Authorization: "Bearer {{ secret:orders-api/token }}"
    query:
      status: closed
  response:
    records_path: $.data
  pagination:
    type: cursor
    cursor_param: cursor
    next_cursor_path: $.next_cursor
  limits:
    max_pages: 50
    max_records: 100000
    max_page_bytes: 10485760
    timeout_seconds: 60
    retry_attempts: 3
    retry_backoff_seconds: 2

target:
  catalog: main
  schema: bronze_api
  table: b_orders_api

layer: bronze
mode: append
schema_policy: additive_only

Modo de carga útil bruta

Use o modo bruto quando a resposta for um documento, quando a carga estiver profundamente aninhada ou quando o formato da API puder evoluir. Este é o padrão preferido para APIs como NASA EONET, onde um documento de nível superior contém matrizes de objetos de domínio.

source:
  type: connector
  connector: rest_api
  request:
    method: GET
    url: https://eonet.gsfc.nasa.gov/api/v3/events
    query:
      status: open
      days: "30"
  response:
    mode: raw
    raw_column: raw_response
  limits:
    max_pages: 1
    max_page_bytes: 10485760
    timeout_seconds: 60

target:
  catalog: main
  schema: bronze_public
  table: b_nasa_eonet_raw

layer: bronze
mode: overwrite

Em seguida, use transform.shape no próximo contrato ou no mesmo contrato, dependendo do design da camada.

transform:
  shape:
    parse_json:
      - column: raw_response
        alias: payload
        schema: "STRUCT<events:ARRAY<STRUCT<id:STRING,title:STRING,geometry:ARRAY<STRUCT<date:STRING,type:STRING,coordinates:ARRAY<DOUBLE>>>>>"
    arrays:
      - path: payload.events
        mode: explode_outer
        alias: event
      - path: event.geometry
        mode: explode_outer
        alias: geometry
    columns:
      event.id: event_id
      event.title: title
      geometry.date:
        alias: event_ts
        cast: TIMESTAMP
      geometry.type: geometry_type
      geometry.coordinates[0]:
        alias: longitude
        cast: DOUBLE
      geometry.coordinates[1]:
        alias: latitude
        cast: DOUBLE

Estratégias de paginação

Estratégia	Usar quando	Campos típicos
none	O endpoint retorna a resposta limitada completa em uma chamada.	max_pages: 1
cursor	A resposta retorna um token para a próxima página.	cursor_param, next_cursor_path
page	A API aceita números de página.	page_param, start_page, max_pages
offset	A API usa semântica de deslocamento/limite.	offset_param, limit_param, page_size

pagination:
  type: offset
  offset_param: offset
  limit_param: limit
  page_size: 1000
  start_offset: 0
limits:
  max_pages: 100
  max_records: 100000

Autenticação e segredos

Mantenha as credenciais em segredos do Databricks ou em outra fonte secreta compatível. Os valores secretos são editados de cargas de resultados, metadados de origem e tabelas de controle persistentes.

request:
  url: https://api.example.com/v1/customers
  headers:
    Authorization: "Bearer {{ secret:crm-api/token }}"
    x-api-key: "{{ secret:crm-api/key }}"
  query:
    tenant: "{{ secret:crm-api/tenant }}"

Não registre cabeçalhos brutos

Use os campos de metadados de origem nas tabelas de controle para diagnósticos. Eles são projetados para armazenar opções redigidas e solicitar detalhes.

Limites e comportamento de falha

A extração REST é intencionalmente limitada. Não deixe os trabalhos de API em aberto.

Limite	Por que isso importa
timeout_seconds	Impede que solicitações suspensas bloqueiem um trabalho indefinidamente.
retry_attempts	Lida com falhas transitórias de API sem ocultar erros persistentes.
retry_backoff_seconds	Reduz a pressão sobre APIs com taxa limitada.
max_pages	Protege o driver contra loops de paginação ilimitados.
max_records	Limita o conjunto de registros materializados.
max_page_bytes	Evita páginas de resposta inesperadamente grandes.

Padrão de API incremental

Se a API suportar um filtro de tempo, combine o estado da marca d'água ContractForge com os parâmetros de consulta da solicitação. Mantenha a semântica do filtro da API explícita e teste o comportamento dos dados que chegam atrasados.

source:
  type: connector
  connector: rest_api
  request:
    url: https://api.example.com/v1/orders
    query:
      updated_after: "{{ watermark:updated_at }}"
  response:
    records_path: $.orders
  incremental:
    watermark_column: updated_at

watermark_columns: [updated_at]
mode: upsert
merge_keys: [order_id]
transform:
  deduplicate:
    keys: [order_id]
    order_by: updated_at DESC NULLS LAST

Atualizações tardias

As APIs baseadas em marca d'água pressupõem que a coluna de atualização de origem é adequada para extração incremental. Se a API puder alterar registros antigos sem atualizar a coluna da marca d'água, use reconciliação periódica ou padrões de instantâneo.

Metadados operacionais

REST executa conector de registro, URL, metadados de solicitação editados, detalhes de paginação e métricas de origem para solução de problemas.

SELECT
  run_id,
  source_connector,
  source_request_redacted_json,
  source_pagination_redacted_json,
  source_response_redacted_json,
  source_limits_redacted_json,
  source_metrics_json
FROM main.ops.ctrl_ingestion_runs
WHERE source_connector = 'rest_api'
ORDER BY started_at_utc DESC;

Problemas comuns

Sintoma	Causa provável	Ação
DNS ou tempo limite de conexão	O runtime não pode alcançar o endpoint da API.	Corrija a rede do espaço de trabalho, a saída, a lista de permissões, o proxy ou o endpoint privado.
401 ou 403	Token inválido, segredo expirado ou escopo ausente.	Verifique o valor secreto e as permissões da API.
Carga útil muito grande	O endpoint retornou mais dados do que o esperado.	Use paginação, filtros ou arquivos de destino externamente.
Linhas incorretas após análise	A carga útil foi aninhada e achatada no código do notebook.	Mova a manipulação de estrutura para transform.shape com esquema explícito.