Azure Blob e ADLS

validado

Use o connector Azure Blob/ADLS para arquivos no Azure Storage. No Databricks serverless, prefira Unity Catalog External Locations ou Volumes. Use SAS token em classic/job clusters quando a configuração de filesystem do runtime for permitida.

Quando usar

Databricks serverless

External Location ou Volume

Use acesso governado a storage quando Spark Connect/serverless bloquear configuração direta de filesystem SAS/Hadoop.

Classic/job cluster

Token SAS ou identidade de plataforma

Use este caminho quando o cluster puder receber a configuração do filesystem Azure e o contrato deve declarar acesso direto ao armazenamento.

Unity Catalog

Storage Credential e External Location

Prefira este modelo para equipes compartilhadas que precisam de acesso governado, auditoria e separação clara entre credenciais e contratos de ingestão.

Spark local

Configuração ABFS/SAS

Use para testes de desenvolvimento e compatibilidade quando bibliotecas Hadoop Azure e credenciais locais estão disponíveis.

Requisitos de runtime

Runtime	Modelo de acesso	Usar quando
Databricks serverless	Unity Catalog External Location ou Volume	A configuração direta de SAS/Hadoop é bloqueada ou gerenciada pela política da plataforma.
Classic cluster	SAS token, configuração ABFS/SAS ou service principal	Você controla a configuração Spark/Hadoop em nível de cluster.
Spark local	Configuração ABFS/WASBS ou provedor de credenciais local	Desenvolvimento e testes de compatibilidade fora do Databricks.

Exemplo básico

Quando o path já for governado pelo Unity Catalog, o contrato deve referenciar o path ABFS legível ou o caminho do Volume. A configuração da credencial pertence à plataforma.

YAML

source:
  type: connector
  connector: azure_blob
  path: abfss://databricksdata@generalcafe.dfs.core.windows.net/blob_teste/csv/
  format: csv
  options:
    header: true
  read:
    schema: "id STRING, event_ts TIMESTAMP, amount DOUBLE"
    source_complete: true

target:
  catalog: contractforge
  schema: bronze_examples
  table: b_blob_csv

layer: bronze
mode: overwrite

Python

from contractforge import ingest

result = ingest(
    source={
        "type": "connector",
        "connector": "azure_blob",
        "path": "abfss://databricksdata@generalcafe.dfs.core.windows.net/blob_teste/csv/",
        "format": "csv",
        "options": {"header": True},
        "read": {
            "schema": "id STRING, event_ts TIMESTAMP, amount DOUBLE",
            "source_complete": True,
        },
    },
    catalog="contractforge",
    target_schema="bronze_examples",
    target_table="b_blob_csv",
    layer="bronze",
    mode="overwrite",
)

Padrão de cluster clássico de token SAS

Use este padrão quando um cluster classic/job puder configurar o acesso ao filesystem Azure e um token SAS estiver armazenado em um secret scope.

YAML

source:
  type: connector
  connector: azure_blob
  account_url: https://generalcafe.blob.core.windows.net/
  container: databricksdata
  path: blob_teste/json/
  format: json
  auth:
    sas_token: "{{ secret:contractforge-azure/blob_sas_token }}"
  read:
    schema: "id STRING, event_ts TIMESTAMP, payload STRUCT<kind:STRING,value:DOUBLE>"
    recursiveFileLookup: true

target:
  catalog: contractforge
  schema: bronze_examples
  table: b_blob_json

layer: bronze
mode: append

Python

from contractforge import ingest

result = ingest(
    source={
        "type": "connector",
        "connector": "azure_blob",
        "account_url": "https://generalcafe.blob.core.windows.net/",
        "container": "databricksdata",
        "path": "blob_teste/json/",
        "format": "json",
        "auth": {"sas_token": "{{ secret:contractforge-azure/blob_sas_token }}"},
        "read": {
            "schema": "id STRING, event_ts TIMESTAMP, payload STRUCT<kind:STRING,value:DOUBLE>",
            "recursiveFileLookup": True,
        },
    },
    catalog="contractforge",
    target_schema="bronze_examples",
    target_table="b_blob_json",
    layer="bronze",
    mode="append",
)

Permissões SAS

As leituras de pasta requerem permissão de lista. A leitura de arquivos individuais pode funcionar com SAS somente leitura, mas a descoberta de diretório, leituras recursivas e seleção de regex precisam de permissão de lista.

Criando um local externo

O SQL exato depende de como a credencial de armazenamento está configurada. A credencial de armazenamento é um objeto do Catálogo do Unity, não um escopo secreto do Databricks.

CREATE EXTERNAL LOCATION IF NOT EXISTS contractforge_blob_teste
URL 'abfss://databricksdata@generalcafe.dfs.core.windows.net/blob_teste'
WITH (STORAGE CREDENTIAL my_storage_credential);

GRANT READ FILES ON EXTERNAL LOCATION contractforge_blob_teste TO `data-engineers`;

Validação de credenciais

O Unity Catalog valida o local tentando ler e muitas vezes criando um marcador de validação. As credenciais somente leitura podem falhar na criação do local mesmo quando a leitura do arquivo funcionaria.

Exemplos multiformato

O conector delega a análise aos leitores Spark. Mantenha as opções e o esquema do leitor explícitos para formatos que tenham comportamento de inferência ambíguo.

CSV

YAML

source:
  type: connector
  connector: azure_blob
  path: abfss://container@account.dfs.core.windows.net/blob_teste/csv/
  format: csv
  options:
    header: true
  read:
    schema: "id STRING, amount DOUBLE"

target:
  catalog: contractforge
  schema: bronze_examples
  table: b_blob_csv_extract

layer: bronze
mode: append

Python

from contractforge import ingest

result = ingest(
    source={
        "type": "connector",
        "connector": "azure_blob",
        "path": "abfss://container@account.dfs.core.windows.net/blob_teste/csv/",
        "format": "csv",
        "options": {"header": True},
        "read": {"schema": "id STRING, amount DOUBLE"},
    },
    catalog="contractforge",
    target_schema="bronze_examples",
    target_table="b_blob_csv_extract",
    layer="bronze",
    mode="append",
)

JSON

YAML

source:
  type: connector
  connector: azure_blob
  path: abfss://container@account.dfs.core.windows.net/blob_teste/json/
  format: json
  read:
    schema: "id STRING, payload STRUCT<a:STRING>"

target:
  catalog: contractforge
  schema: bronze_examples
  table: b_blob_nested_json

layer: bronze
mode: append

Python

from contractforge import ingest

result = ingest(
    source={
        "type": "connector",
        "connector": "azure_blob",
        "path": "abfss://container@account.dfs.core.windows.net/blob_teste/json/",
        "format": "json",
        "read": {"schema": "id STRING, payload STRUCT<a:STRING>"},
    },
    catalog="contractforge",
    target_schema="bronze_examples",
    target_table="b_blob_nested_json",
    layer="bronze",
    mode="append",
)

Parquete

YAML

source:
  type: connector
  connector: azure_blob
  path: abfss://container@account.dfs.core.windows.net/blob_teste/parquet/
  format: parquet
  read:
    recursiveFileLookup: true

target:
  catalog: contractforge
  schema: bronze_examples
  table: b_blob_parquet

layer: bronze
mode: append

Python

from contractforge import ingest

result = ingest(
    source={
        "type": "connector",
        "connector": "azure_blob",
        "path": "abfss://container@account.dfs.core.windows.net/blob_teste/parquet/",
        "format": "parquet",
        "read": {"recursiveFileLookup": True},
    },
    catalog="contractforge",
    target_schema="bronze_examples",
    target_table="b_blob_parquet",
    layer="bronze",
    mode="append",
)

XML

YAML

source:
  type: connector
  connector: azure_blob
  path: abfss://container@account.dfs.core.windows.net/blob_teste/xml/
  format: xml
  options:
    rowTag: item
  read:
    schema: "id STRING, amount DOUBLE"

target:
  catalog: contractforge
  schema: bronze_examples
  table: b_blob_xml

layer: bronze
mode: append

Python

from contractforge import ingest

result = ingest(
    source={
        "type": "connector",
        "connector": "azure_blob",
        "path": "abfss://container@account.dfs.core.windows.net/blob_teste/xml/",
        "format": "xml",
        "options": {"rowTag": "item"},
        "read": {"schema": "id STRING, amount DOUBLE"},
    },
    catalog="contractforge",
    target_schema="bronze_examples",
    target_table="b_blob_xml",
    layer="bronze",
    mode="append",
)

Tratamento de limitações serverless

ContractForge deve falhar claramente quando um runtime serverless/Spark Connect bloqueia a configuração direta de credenciais do sistema de arquivos. Não dependa de um substituto oculto que funcione apenas em um espaço de trabalho.

Sintoma	Causa provável	Ação
Falha no acesso ao armazenamento em nuvem durante a criação do local externo	A credencial de armazenamento não pode validar o comportamento de leitura/gravação/lista.	Conceda à entidade de serviço a função de armazenamento do Azure necessária e verifique o prefixo da URL.
SAS funciona no clássico, mas falha no serverless	Serverless bloqueia a configuração de credenciais do Hadoop em runtime.	Use localização externa, volume ou política de rede/armazenamento do espaço de trabalho.
A leitura do diretório falha, mas o arquivo único funciona	SAS não tem permissão de lista.	Gere novamente o SAS com permissão de lista para leituras de pastas.
Erros de DNS/saída	A rede do espaço de trabalho não pode alcançar o ponto final de armazenamento.	Corrija firewall, acesso à rede pública, endpoint privado ou política de rede.

Metadados operacionais

SELECT
  run_id,
  source_connector,
  source_path,
  source_auth_redacted_json,
  source_read_redacted_json,
  source_metrics_json
FROM main.ops.ctrl_ingestion_runs
WHERE source_connector = 'azure_blob'
ORDER BY started_at_utc DESC;

Problemas comuns

Sintoma	Causa provável	Ação
Acesso negado em serverless	A configuração direta do SAS/Hadoop está bloqueada pelo runtime.	Use localização externa, volume ou política de rede do espaço de trabalho.
A validação da credencial falha	A credencial de armazenamento não pode ler/gravar o caminho de validação.	Conceda a função de Armazenamento do Azure necessária à entidade de serviço ou à identidade gerenciada.
O caminho não lista nenhum arquivo	Configuração incorreta de contêiner, prefixo ou pesquisa recursiva.	Valide o caminho com uma listagem mínima e verifique o tamanho da pasta.
A análise de formato falha	Esquema/opções não correspondem ao formato do arquivo.	Comece com uma pequena amostra e um esquema explícito.