Ingerir arquivos de servidores SFTP

Saiba como ingerir arquivos de servidores SFTP usando o Lakeflow Connect. O conector SFTP amplia a funcionalidade do Auto Loader para proporcionar uma ingestão segura e incremental a partir de servidores SFTP com a governança do Unity Catalog.

Principais características

O conector SFTP oferece o seguinte:

Autenticação baseada em chave privada e palavra-passe.
Ingestão e processamento incremental de arquivos com garantias de execução exatamente uma vez.
Inferência automática de esquema, evolução e resgate de dados.
Governança do Catálogo Unity para importação segura de dados e gestão de credenciais.
Amplo suporte a formatos de arquivo: JSON, CSV, XML, PARQUET, AVRO, TEXT, BINARYFILE, e ORC.
Suporte integrado para correspondência de padrões e curingas para direcionar facilmente subconjuntos de dados.
Disponibilidade em todos os tipos de computação, incluindo pipelines Lakeflow, Databricks SQL, serverless e classic, com Databricks Runtime 17.3 e versões posteriores.

Antes de começar

Para criar a conexão e o pipeline de ingestão, você deve ter o seguinte:

Um espaço de trabalho com o Unity Catalog ativado.
CREATE CONNECTION privilégios para criar uma ligação SFTP, ou o privilégio apropriado para usar uma existente com base no seu modo de acesso ao cluster:
- Modo de Acesso Dedicado: MANAGE CONNECTION.
- Modo de Acesso Padrão: USE CONNECTION.
Computação que usa o Databricks Runtime versão 17.3 ou superior. Para espaços de trabalho compatíveis com FedRAMP, Canada Protected B e IRAP, é necessário Databricks Runtime 18 LTS ou superior.

Configurar SFTP

Primeiro, confirme se o servidor SFTP de origem está acessível ao seu ambiente de cluster Databricks:

Verifique se o servidor remoto está disponível na VPC configurada com o seu espaço de trabalho.
Verifique se as suas regras SSH permitem o intervalo de IPs da VPC da Databricks (se estiver a utilizar computação clássica) ou os IPs de saída (se estiver a utilizar computação sem servidor).
A partir do plano de computação clássico, configure um endereço IP estável com um balanceador de carga, gateway NAT, gateway de internet ou equivalente, e ligue-o à sub-rede onde o Azure Databricks é implementado. Isso permite que o recurso computacional compartilhe um endereço IP público estável que pode ser listado como permitido no servidor SFTP. Para obter instruções sobre como definir as configurações de rede, consulte Redes virtuais de mesmo nível.
No plano de computação sem servidor, consulte Configurar conectividade privada a recursos do Azure para obter os endereços IP de saída.

Criar a conexão

Crie uma conexão com o Catálogo Unity para armazenar suas credenciais SFTP. Deve ter CREATE CONNECTION privilégios.

O conector suporta os seguintes métodos de autenticação:

Chave privada PEM
Autenticação baseada em palavra-passe

O Databricks recomenda o uso da autenticação de chave privada PEM. O Databricks também recomenda o uso de credenciais com o menor privilégio no servidor SFTP de origem (por exemplo, um usuário não-root limitado ao acesso somente leitura).

Quando você cria o pipeline, o conector tenta localizar automaticamente uma conexão que você pode usar e que corresponde ao host. Se houver várias conexões correspondentes, o conector escolhe a primeira conexão que se conecta com êxito ao host. A partir do DBR 18.2, pode especificar explicitamente a ligação usando a databricks.connection opção. Esta é a opção recomendada e evita ambiguidade quando existem múltiplas ligações para o mesmo hospedeiro.

Chave privada PEM (recomendado)

Explorador de Catálogos

No espaço de trabalho Azure Databricks, clique em Catálogo.
Clica Liga, depois clica em Ligações.
Clica no botão Criar ligação .
Na página Noções básicas de conexão do assistente Configurar conexão , insira um Nome de conexão exclusivo.
Em Tipo de conexão, selecione SFTP.
Para Tipo de autenticação, selecione Chave privada PEM.
Selecione Avançar.
Na página de Autenticação , para Host, introduza o nome de host do servidor estrangeiro.
Em User, insira a identidade de usuário usada para acessar a instância estrangeira.
Selecione Avançar.
Na página Detalhes da conexão , insira a chave privada no formato PEM. Forneça também a senha-chave, se aplicável.
Se quiser ignorar a verificação da impressão digital da chave do anfitrião, limpe Verificação da impressão digital da chave do anfitrião.

Quando isso é selecionado, a conexão só prossegue se a chave pública do servidor corresponder à impressão digital SHA-256 esperada. Quando desativada, a conexão continua independentemente da correspondência. Verifique com o administrador da rede antes de desativar isso.
Se a opção Impor impressão digital da chave do host estiver marcada, insira a impressão digital do servidor SFTP.

Você pode recuperar a impressão digital do administrador do servidor ou usando comandos da CLI. Você também pode pressionar Testar e criar conexão>Teste. A mensagem de erro resultante fornece a impressão digital. Por exemplo:

ECDSA key fingerprint is SHA256:XXX/YYY
Selecione Testar e crie ligação.
Se a conexão for bem-sucedida, clique em Criar.

SQL

-- Create a connection using a username and SSH private key.
CREATE CONNECTION my_sftp_connection
TYPE sftp
OPTIONS (
  host 'my.sftpserver.com',
  -- The following credentials can also be used in-line, but Databricks recommends
  -- accessing them using the secrets scope.
  user secret('my_secret_scope','my_sftp_username'),
  pem_private_key secret('my_secret_scope','my_sftp_private_key'),
  -- Port for the host
  port '22',
  -- Passphrase for the private key (optional).
  pem_key_passphrase secret('my_secret_scope','my_sftp_private_key_passphrase'),
  -- SFTP server fingerprint. You can retrieve this from your server administrator or using CLI commands.
  key_fingerprint 'SHA256:ASampleFingerprintValueZy...',
);

Autenticação baseada em palavra-passe

Explorador de Catálogos

No espaço de trabalho Azure Databricks, clique em Catálogo.
Clica Liga, depois clica em Ligações.
Clica no botão Criar ligação .
Na página Noções básicas de conexão do assistente Configurar conexão , insira um Nome de conexão exclusivo.
Em Tipo de conexão, selecione SFTP.
Para Tipo de autenticação, selecione Nome de usuário e senha.
Selecione Avançar.
Na página de Autenticação , para Host, introduza o nome de host do servidor estrangeiro.
Em User, insira a identidade de usuário usada para acessar a instância estrangeira.
Em Senha, digite a senha da instância estrangeira.
Selecione Avançar.
Se quiser ignorar a verificação da impressão digital da chave do anfitrião, limpe Verificação da impressão digital da chave do anfitrião.

Quando isso é selecionado, a conexão só prossegue se a chave pública do servidor corresponder à impressão digital SHA-256 esperada. Quando desativada, a conexão continua independentemente da correspondência. Verifique com o administrador da rede antes de desativar isso.
Se a opção Impor impressão digital da chave do host estiver marcada, insira a impressão digital do servidor SFTP.

Você pode recuperar a impressão digital do administrador do servidor ou usando comandos da CLI. Você também pode pressionar Testar e criar conexão>Teste. A mensagem de erro resultante fornece a impressão digital. Por exemplo:

ECDSA key fingerprint is SHA256:XXX/YYY
Selecione Testar e crie ligação.
Se a conexão for bem-sucedida, clique em Criar.

SQL

-- Create a connection using a username and password.
CREATE CONNECTION my_sftp_connection
TYPE sftp
OPTIONS (
  host 'my.sftpserver.com',
  user secret('my_secret_scope','my_sftp_username'),
  password secret('my_secret_scope','my_sftp_password'),
  -- Port for the host.
  port '22',
  -- SFTP server fingerprint. You can retrieve this from your server administrator or using CLI commands.
  key_fingerprint 'SHA256:ASampleFingerprintValueZy...',
);

Ler arquivos do servidor SFTP

Os exemplos seguintes mostram como ler ficheiros de um servidor SFTP usando as capacidades de streaming do Auto Loader. Para obter detalhes sobre o uso do Auto Loader, consulte Padrões comuns de carregamento de dados.

Pode especificar a ligação do Catálogo Unity para autenticação de duas formas:

Explícito (recomendado, requer o DBR 18.2 ou superior): Especifique a ligação pelo nome utilizando a opção databricks.connection. Quando especifica a ligação, o host e a porta no URI têm de corresponder às credenciais de ligação armazenadas. O campo de nome de utilizador no URI é opcional. Se for omitido, o conector usa o nome de utilizador da ligação.
Automático: Se não especificar a ligação usando a databricks.connection opção, o conector resolve a ligação ao comparar o <host> e <username> no URI com as ligações disponíveis. Se existirem múltiplas ligações correspondentes, o conector usa a primeira que se conecta com sucesso.

O exemplo seguinte mostra como ler ficheiros usando resolução automática de ligação:

# Run the Auto Loader job to ingest all existing data in the SFTP server.
# The <username> and <host> in the URI must match the connection created in the previous step.
# The connector automatically resolves the matching Unity Catalog connection for authentication.
df = (spark.readStream.format("cloudFiles")
  .option("cloudFiles.schemaLocation", "<path to store schema information>") # This is a cloud storage path
  .option("cloudFiles.format", "csv") # Or other format supported by Auto Loader
  # Specify the absolute path on the SFTP server starting from the root /.
  # Example: /home/<username>/data/files or /uploads/csv_files
  .load("sftp://<username>@<host>:<port>/<absolute_path_to_files>")
  .writeStream
  .format("delta")
  .option("checkpointLocation", "<path to store checkpoint information>") # This is a cloud storage path.
  .trigger(availableNow = True)
  .table("<table name>"))
df.awaitTermination()

O exemplo seguinte mostra como especificar explicitamente a ligação ao Catálogo Unity usando a databricks.connection opção. Isto requer DBR 18.2 ou superior.

# Requires DBR 18.2 or above. Explicitly specify the Unity Catalog connection by name (recommended).
# The username is optional in the URI when databricks.connection is provided.
df = (spark.readStream.format("cloudFiles")
  .option("cloudFiles.schemaLocation", "<path to store schema information>") # This is a cloud storage path
  .option("cloudFiles.format", "csv") # Or other format supported by Auto Loader
  .option("databricks.connection", "<connection_name>")
  # Specify the absolute path on the SFTP server starting from the root /.
  # Example: /uploads/csv_files
  .load("sftp://<host>:<port>/<absolute_path_to_files>")
  .writeStream
  .format("delta")
  .option("checkpointLocation", "<path to store checkpoint information>") # This is a cloud storage path.
  .trigger(availableNow = True)
  .table("<table name>"))
df.awaitTermination()

Os exemplos seguintes mostram como ler ficheiros de um servidor SFTP usando o Auto Loader em pipelines Lakeflow:

Python

from pyspark import pipelines as dp

# The <username> and <host> in the URI must match the connection created in the previous step.
# The connector automatically resolves the matching Unity Catalog connection for authentication.
@dp.table
def sftp_bronze_table():
  return (spark.readStream.format("cloudFiles")
    .option("cloudFiles.format", "csv") # Or other format supported by Auto Loader
    # Specify the absolute path on the SFTP server starting from the root /.
    # Example: /home/username/data/files or /uploads/csv_files
    .load("sftp://<username>@<host>:<port>/<absolute_path_to_files>")))

SQL

-- The <username> and <host> in the URI must match the connection created in the previous step.
-- The connector automatically resolves the matching Unity Catalog connection for authentication.
CREATE OR REFRESH STREAMING TABLE sftp_bronze_table
AS SELECT * FROM STREAM read_files(
  "sftp://<username>@<host>:<port>/<absolute_path_to_files>",
  format => "csv"
)

Configure as opções do Auto Loader. Todas as opções são suportadas, exceto:

cloudFiles.useNotifications
cloudFiles.useManagedFileEvents
cloudFiles.cleanSource
Opções específicas da nuvem

Limitações

SFTP não é suportado em outras superfícies de ingestão, incluindo COPY INTO, spark.reade dbutils.ls.
Não há suporte para gravar novamente em um servidor SFTP.
Auto Loader cleanSource (excluindo ou arquivando arquivos na origem após a ingestão) não é suportado.
O protocolo FTP não é suportado.

FAQ

Encontre respostas para perguntas frequentes sobre o conector SFTP.

Como posso usar wildcards ou padrões de nomes de ficheiros para selecionar ficheiros a ingerir?

O conector SFTP baseia-se na estrutura padrão do Auto Loader para ler a partir de servidores SFTP. Isto significa que todas as opções do Auto Loader são suportadas. Para padrões de nome de arquivo e curingas, use as opções pathGlobFilter ou fileNamePattern. Ver Auto Loader.

O conector SFTP pode ingerir ficheiros encriptados? (O PGP é suportado?)

O conector não desencripta em voo, mas pode ingerir os ficheiros encriptados como ficheiros binários e desencriptar após a ingestão.

Como lidar com formatos de chave privada incompatíveis?

Apenas o formato PEM é suportado. Você pode gerar uma chave privada no formato PEM seguindo um destes procedimentos:

(Opção 1) Crie uma nova chave RSA no formato PEM padrão:
```
% ssh-keygen -t rsa -m pem
```
(Opção 2) Converta a chave de formato OpenSSH existente para o formato PEM:
```
% ssh-keygen -p -m pem -f /path/to/key  # This updates the key file.
```

Recursos adicionais

Comentários

Esta página foi útil?

Last updated on 2026-07-28