(+351) 21 24 10006  ·  info@bconcepts.pt
Carnaxide, Lisboa

Como copiar ficheiros SFTP para ADLS Gen2 em Azure Data Factory: passo a passo

João Barros 20 de November de 2026 4 min de leitura

Este tutorial mostra como copiar ficheiros de um servidor SFTP para uma conta ADLS Gen2 usando o Azure Data Factory, mantendo a estrutura de pastas, registando metadados e tratando falhas comuns. É útil para automatizar a ingestão segura de ficheiros externos para processamento posterior.

Pré-requisitos

  • Conta Azure com permissões para criar recursos.
  • Azure Data Factory (v2) criado.
  • Acesso a um servidor SFTP (host, porta, utilizador, palavra-passe ou chave SSH).
  • Conta ADLS Gen2 com um container e permissões (Storage Blob Data Contributor).
  • Azure Key Vault opcional para guardar credenciais (recomendado).

Passo 1: Criar Linked Service para SFTP

Um Linked Service descreve como ligar ao SFTP. Se usar palavra-passe ou chave SSH, prefira armazenar no Azure Key Vault. No portal do ADF, vá a Manage > Linked services > New e escolha SFTP. Configure o host, a porta, a autenticação e teste a ligação.

{
  "type": "Sftp",
  "typeProperties": {
    "host": "sftp.exemplo.com",
    "port": 22,
    "authenticationType": "Basic", /* ou "SSHPublicKey" */
    "userName": "meu_utilizador",
    "password": "@Microsoft.KeyVault(\'https://meu-kv.vault.azure.net/secrets/sftp-pwd\')"
  }
}

Passo 2: Criar Linked Service para ADLS Gen2

Criar o Linked Service para a conta de armazenamento ADLS Gen2. Use a Managed Identity do ADF para evitar credenciais nas configurações. No portal, escolha Azure Data Lake Storage Gen2 e seleccione Authorization via Managed Identity.

{
  "type": "AzureDataLakeStorageGen2",
  "typeProperties": {
    "url": "https://meuaccount.dfs.core.windows.net"
  },
  "connectVia": null
}

Passo 3: Criar DataSet SFTP e DataSet ADLS Gen2

Defina DataSets que apontem para o caminho de origem no SFTP e para a pasta de destino em ADLS Gen2. Configure wildcardPaths se quiser copiar múltiplos ficheiros ou toda a árvore.

{
  "name": "SftpFiles",
  "properties": {
    "type": "FileShare",
    "linkedServiceName": {"referenceName":"LS_SFTP","type":"LinkedServiceReference"},
    "typeProperties": {"folderPath":"/incoming/{{year}}/{{month}}"}
  }
}

{
  "name": "ADLSFiles",
  "properties": {
    "type": "AzureBlobFS",
    "linkedServiceName": {"referenceName":"LS_ADLS","type":"LinkedServiceReference"},
    "typeProperties": {"folderPath":"/raw/sftp/{{year}}/{{month}}"}
  }
}

Passo 4: Criar Pipeline com actividade Copy

Crie um pipeline com a actividade Copy. Para manter a estrutura de pastas use a opção Preserve Hierarchy no Copy behaviour. Configure fault tolerance e retry para lidar com falhas transitórias.

{
  "name": "CopyFromSftpToADLS",
  "properties": {
    "activities": [
      {
        "name": "CopySftpToADLS",
        "type": "Copy",
        "typeProperties": {
          "source": {"type":"BinarySource"},
          "sink": {"type":"BinarySink"},
          "enableStaging": false
        },
        "inputs": [{"referenceName":"SftpFiles","type":"DatasetReference"}],
        "outputs": [{"referenceName":"ADLSFiles","type":"DatasetReference"}],
        "policy": {"retry":3,"timeout":"00:30:00","retryIntervalInSeconds":60}
      }
    ]
  }
}

Passo 5: Registar metadados com actividade Lookup/Stored Procedure

Após a cópia, registe metadados (origem, destino, timestamp, tamanho) num ficheiro JSON ou numa tabela de metadados. Pode usar uma actividade Lookup para obter detalhes do ficheiro e depois uma Stored Procedure para gravar numa base de dados ou um Copy para um ficheiro de log.

{
  "name": "WriteMetadata",
  "type": "Copy",
  "inputs": [{"referenceName":"MetadataSource","type":"DatasetReference"}],
  "outputs": [{"referenceName":"ADLSMetadata","type":"DatasetReference"}]
}

Passo 6: Tratar erros comuns e limpar ficheiros incompletos

Erros comuns: falha de autenticação SFTP, timeouts, ficheiros bloqueados. Use politica de retry, validação do tamanho do ficheiro e uma coluna de estado nos metadados. Para ficheiros parcialmente transferidos, copie para uma pasta temporária e só mova para a pasta final após validação.

// Exemplo de lógica: mover apenas after_success
1. Copy para /raw/sftp/_staging/{{...}}
2. Verificar tamanho/MD5
3. Se OK, mover para /raw/sftp/{{year}}/{{month}}/
4. Se NOK, mover para /raw/sftp/_quarantine/

Verificar o resultado

Confirme que os ficheiros chegaram: abra o container ADLS Gen2 e verifique a estrutura de pastas preservada e ficheiros com tamanhos correctos. Verifique os logs do pipeline no Monitor do Azure Data Factory para entradas de sucesso e falhas. Confirme também que a tabela/ficheiro de metadados contém registos para cada ficheiro processado.

Conclusão

Agora tem um pipeline ADF que copia ficheiros de um servidor SFTP para ADLS Gen2, preservando a hierarquia, tratando falhas e guardando metadados. Próximos passos: automatizar com trigger, encriptar em trânsito/e em repouso e integrar com um processo ETL/Mapping Data Flows. Dica: experimente Managed Identity + Key Vault para a segurança das credenciais — já testou essa combinação?