Ingérer des fichiers à partir de serveurs SFTP

Découvrez comment ingérer des fichiers à partir de serveurs SFTP à l’aide de Lakeflow Connect. Le connecteur SFTP étend la fonctionnalité Auto Loader pour fournir une ingestion sécurisée et incrémentielle à partir de serveurs SFTP avec la gouvernance Unity Catalog.

Fonctionnalités clés

Le connecteur SFTP offre les éléments suivants :

Authentification par clé privée et par mot de passe.
Ingestion et traitement incrémentiels des fichiers avec garantie de traitement unique (exactly-once).
Inférence de schéma automatique, évolution et sauvetage des données.
Gouvernance du catalogue Unity pour l’ingestion de données et les identifiants sécurisés.
Prise en charge de nombreux formats de fichiers : JSON, CSV, XML, PARQUET, AVRO, TEXT, BINARYFILE et ORC.
Prise en charge intégrée des modèles et des caractères génériques pour cibler facilement des sous-ensembles de données.
Disponibilité sur tous les types de calcul, notamment les pipelines Lakeflow, Databricks SQL, serverless et classique avec Databricks Runtime 17.3 et versions ultérieures.

Avant de commencer

Pour créer la connexion et le pipeline d’ingestion, vous devez disposer des éléments suivants :

Un espace de travail avec le catalogue Unity activé.
CREATE CONNECTION privilèges pour créer une connexion SFTP ou le privilège approprié pour utiliser un privilège existant en fonction de votre mode d’accès au cluster :
- Mode d’accès dédié : MANAGE CONNECTION.
- Mode d’accès standard : USE CONNECTION.
Calcul qui utilise Databricks Runtime version 17.3 ou ultérieure. Pour les espaces de travail conformes à FedRAMP, Canada Protected B et IRAP, Databricks Runtime 18 LTS ou version ultérieure sont requis.

Configurer SFTP

Tout d’abord, vérifiez que le serveur SFTP source est accessible à votre environnement de cluster Databricks :

Vérifiez que le serveur distant est disponible dans le VPC configuré avec votre espace de travail.
Vérifiez que vos règles SSH autorisent la plage d’adresses IP du VPC Databricks (si vous utilisez un calcul classique) ou les adresses IP sortantes (si vous utilisez le calcul serverless).
À partir du plan de calcul classique, configurez une adresse IP stable avec un équilibreur de charge, une passerelle NAT, une passerelle Internet ou un équivalent, puis connectez-le au sous-réseau où Azure Databricks calcul est déployé. Cela permet à la ressource de calcul de partager une adresse IP publique stable qui peut être autorisée côté serveur SFTP. Pour obtenir des instructions sur la configuration des paramètres réseau, consultez Réseaux virtuels homologues.
À partir du plan de calcul sans serveur, consultez Configurer la connectivité privée aux ressources Azure pour obtenir les adresses IP sortantes.

Créer la connexion

Créez une connexion de catalogue Unity pour stocker vos informations d’identification SFTP. Vous devez disposer de CREATE CONNECTION privilèges.

Le connecteur prend en charge les méthodes d’authentification suivantes :

Clé privée PEM
L’authentification basée sur un mot de passe

Databricks recommande d’utiliser l’authentification par clé privée PEM. Databricks recommande également d’utiliser des informations d’identification avec le privilège minimum sur le serveur SFTP source (par exemple, un utilisateur non racine limité à l’accès en lecture seule).

Lorsque vous créez le pipeline, le connecteur tente de trouver automatiquement une connexion que vous pouvez utiliser et qui correspond à l’hôte. S’il existe plusieurs connexions correspondantes, le connecteur choisit la première connexion qui se connecte correctement à l’hôte. À compter de DBR 18.2, vous pouvez spécifier explicitement la connexion à l’aide de l’option databricks.connection . Il s’agit de l’option recommandée et évite l’ambiguïté lorsque plusieurs connexions existent pour le même hôte.

Clé privée PEM (recommandé)

Explorateur de catalogues

Dans l’espace de travail Azure Databricks, cliquez sur Catalogue.
Cliquez sur Connectez-vous, puis cliquez sur Connexions.
Cliquez sur le bouton Créer une connexion .
Dans la page Principes de base de la connexion de l’Assistant de configuration de la connexion, entrez un nom de connexion unique.
Pour le type de connexion , sélectionnez SFTP.
Pour le type d’authentification, sélectionnez Clé privée PEM.
Cliquez sur Suivant.
Dans la page Authentification , pour Host, entrez le nom d’hôte du serveur étranger.
Pour l’utilisateur, entrez l’identité de l’utilisateur utilisée pour accéder à l’instance étrangère.
Cliquez sur Suivant.
Dans la page Détails de la connexion, entrez la clé privée au format PEM. Fournissez également la phrase secrète de clé, le cas échéant.
Si vous souhaitez ignorer la vérification de l'empreinte de la clé d'hôte, désactivez l'option Appliquer la vérification de l'empreinte de la clé d'hôte.

Lorsque cette option est sélectionnée, la connexion se poursuit uniquement si la clé publique du serveur correspond à l’empreinte SHA-256 attendue. Lorsque cette option est désactivée, la connexion se poursuit quel que soit le résultat de la vérification. Contactez votre administrateur réseau avant de le désactiver.
Si Enforcer l’empreinte digitale de la clé hôte est sélectionnée, entrez l’empreinte digitale du serveur SFTP.

Vous pouvez récupérer l’empreinte digitale de votre administrateur de serveur ou à l’aide de commandes CLI. Vous pouvez également appuyer sur Test et créer un test de connexion>. Le message d’erreur résultant fournit l’empreinte digitale. Par exemple:

ECDSA key fingerprint is SHA256:XXX/YYY
Sélectionnez Tester et créer une connexion.
Si la connexion réussit, cliquez sur Créer.

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...',
);

L’authentification basée sur un mot de passe

Explorateur de catalogues

Dans l’espace de travail Azure Databricks, cliquez sur Catalogue.
Cliquez sur Connectez-vous, puis cliquez sur Connexions.
Cliquez sur le bouton Créer une connexion .
Dans la page Principes de base de la connexion de l’Assistant de configuration de la connexion, entrez un nom de connexion unique.
Pour le type de connexion , sélectionnez SFTP.
Pour le type d’authentification, sélectionnez Nom d’utilisateur et mot de passe.
Cliquez sur Suivant.
Dans la page Authentification , pour Host, entrez le nom d’hôte du serveur étranger.
Pour l’utilisateur, entrez l’identité de l’utilisateur utilisée pour accéder à l’instance étrangère.
Pour mot de passe, entrez le mot de passe de l’instance étrangère.
Cliquez sur Suivant.
Si vous souhaitez ignorer la vérification de l'empreinte de la clé d'hôte, désactivez l'option Appliquer la vérification de l'empreinte de la clé d'hôte.

Lorsque cette option est sélectionnée, la connexion se poursuit uniquement si la clé publique du serveur correspond à l’empreinte SHA-256 attendue. Lorsque cette option est désactivée, la connexion se poursuit quel que soit le résultat de la vérification. Contactez votre administrateur réseau avant de le désactiver.
Si Enforcer l’empreinte digitale de la clé hôte est sélectionnée, entrez l’empreinte digitale du serveur SFTP.

Vous pouvez récupérer l’empreinte digitale de votre administrateur de serveur ou à l’aide de commandes CLI. Vous pouvez également appuyer sur Test et créer un test de connexion>. Le message d’erreur résultant fournit l’empreinte digitale. Par exemple:

ECDSA key fingerprint is SHA256:XXX/YYY
Sélectionnez Tester et créer une connexion.
Si la connexion réussit, cliquez sur Créer.

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...',
);

Lire des fichiers à partir du serveur SFTP

Les exemples suivants montrent comment lire des fichiers à partir d’un serveur SFTP à l’aide des fonctionnalités de streaming du chargeur automatique. Pour plus d’informations sur l’utilisation du chargeur automatique, consultez Modèles de chargement de données courants.

Vous pouvez spécifier la connexion du catalogue Unity pour l’authentification de l’une des deux manières suivantes :

Explicite (recommandé, nécessite DBR 18.2 et versions ultérieures) : Spécifiez la connexion par nom à l’aide de l’option databricks.connection . Lorsque vous spécifiez la connexion, l’hôte et le port dans l’URI doivent correspondre aux informations d’identification de connexion stockées. Le champ nom d’utilisateur dans l’URI est facultatif. S’il est omis, le connecteur utilise le nom d’utilisateur de la connexion.
Automatique: Si vous ne spécifiez pas la connexion à l’aide de l’option databricks.connection , le connecteur résout la connexion en correspondant à l’URI <host> et <username> dans l’URI par rapport aux connexions disponibles. S’il existe plusieurs connexions correspondantes, le connecteur utilise le premier qui se connecte correctement.

L’exemple suivant montre comment lire des fichiers à l’aide de la résolution de connexion automatique :

# 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()

L’exemple suivant montre comment spécifier explicitement la connexion du catalogue Unity à l’aide de l’option databricks.connection . Cela nécessite DBR 18.2 ou version ultérieure.

# 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()

Les exemples suivants montrent comment lire des fichiers à partir d’un serveur SFTP à l’aide du chargeur automatique dans des 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"
)

Configurer les options du chargeur automatique. Toutes les options sont prises en charge, sauf :

cloudFiles.useNotifications
cloudFiles.useManagedFileEvents
cloudFiles.cleanSource
Options spécifiques au cloud

Limites

SFTP n’est pas pris en charge sur d’autres surfaces d’ingestion, notamment COPY INTO, spark.readet dbutils.ls.
L'écriture vers un serveur SFTP n'est pas prise en charge.
Le chargeur cleanSource automatique (suppression ou archivage de fichiers à la source après l’ingestion) n’est pas pris en charge.
Le protocole FTP n’est pas pris en charge.

Questions fréquentes (FAQ)

Trouvez des réponses aux questions fréquemment posées sur le connecteur SFTP.

Comment utiliser des caractères génériques ou des modèles de nom de fichier pour sélectionner des fichiers à ingérer ?

Le connecteur SFTP s’appuie sur l’infrastructure de chargeur automatique standard pour lire à partir de serveurs SFTP. Cela signifie que toutes les options de chargeur automatique sont prises en charge. Pour les modèles de nom de fichier et les caractères génériques, utilisez les options pathGlobFilter ou fileNamePattern. Voir Chargeur automatique.

Le connecteur SFTP peut-il ingérer des fichiers chiffrés ? (Le protocole PGP est-il pris en charge ?)

Le connecteur ne déchiffre pas les données en transit, mais vous pouvez ingérer les fichiers chiffrés sous forme de fichiers binaires et les déchiffrer après l'ingestion.

Comment gérer les formats de clé privée incompatibles ?

Seul le format PEM est pris en charge. Vous pouvez générer une clé privée au format PEM en effectuant l’une des opérations suivantes :

(Option 1) Créez une clé RSA au format PEM standard :
```
% ssh-keygen -t rsa -m pem
```
(Option 2) Convertissez la clé de format OpenSSH existante au format PEM :
```
% ssh-keygen -p -m pem -f /path/to/key  # This updates the key file.
```

Ressources supplémentaires

Commentaires

Est-ce que cette page vous a été utile?

Last updated on 2026-07-28