Armazenamento de objetos

validado

Use object_storage ou blob quando o contrato deve permanecer neutro em relação ao provedor enquanto o runtime lida com o acesso ao armazenamento em nuvem.

Quando usar

Escolha o conector neutro para o provedor quando o runtime já expõe um caminho de nuvem legível e o contrato não deve codificar detalhes de autenticação específicos do provedor. Use as páginas dedicadas do S3 ou do Azure Blob quando o contrato precisar configurar credenciais diretas ou comportamento de acesso específico da plataforma.

Contratos portáteis

Caminho neutro do provedor

Mantenha o contrato de origem focado no caminho, formato e esquema enquanto o IAM, o local externo do UC ou as montagens controlam o acesso.

Autenticação de propriedade do runtime

Sem segredos explícitos

Utilize isto quando as credenciais já estão configuradas pela plataforma e não pertencem ao contrato.

Semântica de arquivo

Comportamento do leitor Spark

Análise, pesquisa recursiva, esquema e filtros seguem as mesmas expectativas dos conectores de arquivo.

Armazenamento governado

Volumes e localizações externas

Boa opção para ambientes Databricks onde o Unity Catalog rege o acesso ao armazenamento.

Requisitos de runtime

Exigência	Detalhes
Caminho legível	O runtime já deve ser capaz de ler/listar o caminho declarado.
Suporte de formato	O formato declarado deve ser suportado pelo Spark ou por bibliotecas de runtime instaladas.
Subsídios de governança	Para volumes UC ou locais externos, o principal do trabalho precisa das permissões apropriadas de catálogo/armazenamento.
Evidência completa da fonte	Defina source_complete: true somente quando a pasta representar a fatia de origem completa exigida pelo modo de gravação.

Exemplo básico

source:
  type: connector
  connector: object_storage
  provider: adls
  path: abfss://landing@account.dfs.core.windows.net/orders/
  format: json
  read:
    schema: "order_id STRING, updated_at TIMESTAMP, amount DOUBLE"
    recursiveFileLookup: true

Provedores suportados

• S3: AWS S3 com localização externa ou credenciais S3A.
• Azure Blob: Azure Blob/ADLS com localização externa UC, volume ou SAS em tempos de execução permitidos.

Padrão neutro em relação ao provedor

Use esse conector quando o caminho já estiver legível pelo runtime e o contrato não se importar se o acesso é fornecido pelo IAM, pelo Unity Catalog, pelo armazenamento montado ou pela configuração do sistema de arquivos local.

source:
  type: connector
  connector: object_storage
  provider: s3
  path: s3://company-landing/orders/
  format: parquet
  read:
    schema: "order_id STRING, updated_at TIMESTAMP, amount DOUBLE"

Validação operacional

SELECT run_id, status, source_connector, source_provider, source_format, source_path, rows_read, rows_written
FROM main.ops.ctrl_ingestion_runs
WHERE source_connector IN ('object_storage', 'blob')
ORDER BY started_at_utc DESC;

Problemas comuns

Sintoma	Causa provável	Ação
Caminho não encontrado	O runtime não pode resolver o caminho da nuvem ou o prefixo está errado.	Valide primeiro o caminho com o Spark ou a listagem de arquivos da plataforma.
Acesso negado	Permissões de IAM, local externo, volume ou montagem ausentes.	Corrija o acesso ao runtime em vez de incorporar lógica específica do provedor neste conector.
Erro de formato	O formato declarado não corresponde ao conteúdo do arquivo ou a biblioteca de runtime está ausente.	Valide o formato com um esquema mínimo e um caminho de amostra.

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 soluções alternativas específicas do conector se tornem uma lógica de negócios oculta.