Aller au contenu principal
Dernière mise à jour le

Ingérer des fichiers depuis des serveurs SFTP

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

Fonctionnalités clés​

Le connecteur SFTP offre ce qui suit :

  • Authentification par clé privée et par mot de passe.
  • Ingestion et traitement incrémentiels de fichiers avec sémantique « exactly-once ».
  • Inférence automatique du schéma, évolution et récupération des données.
  • Gouvernance Unity Catalog pour une ingestion et des informations d'identification sécurisées.
  • Large prise en charge des formats de fichier : JSON, CSV, XML, PARQUET, AVRO, TEXT, BINARYFILE et ORC.
  • Support intégré pour la correspondance de modèles et de caractères génériques afin de cibler facilement des sous-ensembles de données.
  • Disponibilité sur tous les types de compute, y compris les LakeFlow Pipelines, Databricks SQL, Serverless et classique, avec Databricks Runtime 17.3 et versions supérieures.

Avant de commencer​

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

  • Un Workspace avec Unity Catalog activé.

  • CREATE CONNECTION privilèges pour créer une connexion SFTP, ou le privilège approprié pour en utiliser une existante 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.

  • Compute qui utilise Databricks Runtime version 17.3 ou supérieure. Pour les Workspace conformes aux normes FedRAMP, Canada Protected B et IRAP, Databricks Runtime 18 ou supérieur est requis.

Configurer SFTP​

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

  • Vérifiez que le serveur distant est disponible dans le Virtual Private Cloud (VPC) qui a été configuré avec votre Workspace.
  • Vérifiez que vos règles SSH autorisent la plage IP du Virtual Private Cloud (VPC) Databricks (si vous utilisez le compute classique) ou les adresses IP sortantes (si vous utilisez le compute Serverless).
  • Depuis le plan de compute classique, configurez une adresse IP stable avec un équilibreur de charge, une passerelle NAT, une passerelle Internet ou un équivalent, et connectez-la au sous-réseau où le compute Databricks est déployé. Cela permet à la ressource de compute de partager une adresse IP publique stable qui peut être mise en liste blanche côté serveur SFTP. Pour des instructions sur la configuration des paramètres réseau, consultez le peering Virtual Private Cloud (VPC).
  • Depuis le plan de compute serverless, consultez Configuration du pare-feu pour le compute serverless pour obtenir les adresses IP sortantes.

Créer la connexion​

Créez une connexion Unity Catalog pour stocker vos informations d'identification SFTP. Vous devez disposer des privilèges CREATE CONNECTION.

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

  • Clé privée PEM
  • Authentification par mot de passe

Databricks recommande l'utilisation de l'authentification par clé privée PEM. Databricks recommande également d'utiliser des identifiants avec le privilège le moins élevé sur le serveur SFTP source (par exemple, un utilisateur non root limité à un 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 avec succès à l'hôte. À partir de DBR 18.2, vous pouvez spécifier explicitement la connexion à l'aide de l'option databricks.connection. C'est l'option recommandée et elle évite toute ambiguïté lorsque plusieurs connexions existent pour le même hôte.

Clé privée PEM (recommandée)​

  1. Dans le Workspace Databricks, cliquez sur Icône de données. Catalogue .

  2. Cliquez sur Icône de prise. Connexion , puis cliquez sur Connexions .

  3. Veuillez cliquer sur le bouton Créer une connexion .

  4. Sur la page Informations de base de la connexion de l'assistant Configurer la connexion , saisissez un Nom de connexion unique.

  5. Pour Type de connexion , sélectionnez SFTP .

  6. Pour Type d'authentification , sélectionnez Clé privée PEM .

  7. Sélectionnez **Suivant**.

  8. Sur la page Authentification , pour Hôte , entrez le Hostname du serveur étranger.

  9. Pour Utilisateur , saisissez l’identité de l’utilisateur utilisée pour accéder à l’instance étrangère.

  10. Sélectionnez **Suivant**.

  11. Sur la page Détails de la connexion , entrez la clé privée au format PEM. Fournissez également la phrase secrète de la clé, le cas échéant.

  12. Si vous souhaitez ignorer la vérification de l'empreinte de la clé d'hôte, décochez **Appliquer l'empreinte de la clé d'hôte**.

    Lorsque cette option est sélectionnée, la connexion ne se poursuit que si la clé publique du serveur correspond à l’empreinte SHA-256 attendue. Lorsqu’elle est désactivée, la connexion se poursuit indépendamment de la correspondance. Veuillez vérifier auprès de votre administrateur réseau avant de désactiver cette option.

  13. Si l'option Appliquer l'empreinte digitale de la clé d'hôte est cochée, saisissez l'empreinte digitale du serveur SFTP.

    Vous pouvez récupérer l'empreinte digitale auprès de votre administrateur de serveur ou en utilisant des commandes CLI. Vous pouvez également appuyer sur Tester et créer la connexion > Test . Le message d'erreur résultant fournit l'empreinte digitale. Par exemple :

    ECDSA key fingerprint is SHA256:XXX/YYY

  14. Sélectionnez Tester et créer la connexion .

  15. Si la connexion est réussie, cliquez sur Créer .

Authentification par mot de passe​

  1. Dans le Workspace Databricks, cliquez sur Icône de données. Catalogue .

  2. Cliquez sur Icône de prise. Connexion , puis cliquez sur Connexions .

  3. Veuillez cliquer sur le bouton Créer une connexion .

  4. Sur la page Informations de base de la connexion de l'assistant Configurer la connexion , saisissez un Nom de connexion unique.

  5. Pour Type de connexion , sélectionnez SFTP .

  6. Pour Type d'authentification , sélectionnez Nom d'utilisateur et mot de passe .

  7. Sélectionnez **Suivant**.

  8. Sur la page Authentification , pour Hôte , entrez le Hostname du serveur étranger.

  9. Pour Utilisateur , saisissez l’identité de l’utilisateur utilisée pour accéder à l’instance étrangère.

  10. Pour Mot de passe , entrez le mot de passe de l'instance distante.

  11. Sélectionnez **Suivant**.

  12. Si vous souhaitez ignorer la vérification de l'empreinte de la clé d'hôte, décochez **Appliquer l'empreinte de la clé d'hôte**.

    Lorsque cette option est sélectionnée, la connexion ne se poursuit que si la clé publique du serveur correspond à l’empreinte SHA-256 attendue. Lorsqu’elle est désactivée, la connexion se poursuit indépendamment de la correspondance. Veuillez vérifier auprès de votre administrateur réseau avant de désactiver cette option.

  13. Si l'option Appliquer l'empreinte digitale de la clé d'hôte est cochée, saisissez l'empreinte digitale du serveur SFTP.

    Vous pouvez récupérer l'empreinte digitale auprès de votre administrateur de serveur ou en utilisant des commandes CLI. Vous pouvez également appuyer sur Tester et créer la connexion > Test . Le message d'erreur résultant fournit l'empreinte digitale. Par exemple :

    ECDSA key fingerprint is SHA256:XXX/YYY

  14. Sélectionnez Tester et créer la connexion .

  15. Si la connexion est réussie, cliquez sur Créer .

Lisez les fichiers depuis le serveur SFTP​

Les exemples suivants montrent comment lire des fichiers à partir d'un serveur SFTP en utilisant les capacités de streaming d'Auto Loader. Pour plus de détails sur l'utilisation d'Auto Loader, consultez les modèles courants de chargement de données.

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

  • **Explicite (recommandé, Requiert DBR 18,2 et plus) :** Spécifiez la connexion par nom à l'aide de databricks.connection l'option. Lorsque vous spécifiez la connexion, l'hôte et le port de l'URI doivent correspondre aux identifiants de connexion stockés. 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 faisant correspondre les <host> et <username> de l’URI aux connexions disponibles. S’il existe plusieurs connexions correspondantes, le connecteur utilise la première qui se connecte avec succès.

L'exemple suivant montre comment lire des fichiers en utilisant la résolution automatique des connexions :

Python
# 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 Unity Catalog en utilisant l'option databricks.connection. Cela nécessite DBR 18,2 ou une version supérieure.

Python
# 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 depuis un serveur SFTP à l'aide d'Auto Loader dans LakeFlow Pipelines :

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>")))

Configurez les options d'Auto Loader. Toutes les options sont prises en charge, sauf :

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

Limitations​

  • SFTP n'est pas pris en charge par d'autres surfaces d'ingestion, y compris COPY INTO, spark.read et dbutils.ls.
  • L’écriture vers un serveur SFTP n'est pas prise en charge.
  • Auto Loader cleanSource (suppression ou archivage des fichiers à la source après ingestion) n'est pas pris en charge.
  • Le protocole FTP n'est pas pris en charge.

FAQ​

Trouvez les 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 noms de fichiers pour sélectionner les fichiers à ingérer ?​

Le connecteur SFTP s'appuie sur le framework Auto Loader standard pour lire à partir des serveurs SFTP. Cela signifie que toutes les options d'Auto Loader sont prises en charge. Pour les modèles de noms de fichiers et les caractères génériques, utilisez les options pathGlobFilter ou fileNamePattern. See Auto Loader.

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

Le connecteur ne déchiffre pas en transit, mais vous pouvez ingérer les fichiers chiffrés en tant que 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 nouvelle clé RSA au format PEM standard :

    Shell
    % ssh-keygen -t rsa -m pem

  • (Option 2) Convertir la clé existante au format OpenSSH au format PEM :

    Shell
    % ssh-keygen -p -m pem -f /path/to/key  # This updates the key file.

Ressources supplémentaires​

Sur cette page