Copiar dados do servidor FTP utilizando o Azure Data Factory ou Synapse Analytics

  • Artigo

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Dica

Experimente o Data Factory no Microsoft Fabric, uma solução de análise tudo-em-um para empresas. O Microsoft Fabric abrange desde movimentação de dados até ciência de dados, análise em tempo real, business intelligence e relatórios. Saiba como iniciar uma avaliação gratuita!

Este artigo descreve como copiar dados do servidor FTP. Para saber mais, leia o artigo introdutório do Azure Data Factory e do Synapse Analytics.

Funcionalidades com suporte

Há suporte para este conector do FTP nas seguintes funcionalidades:

Funcionalidades com suporte IR
Atividade de cópia (origem/-) 6/6
Atividade de pesquisa 6/6
Atividade GetMetadata 6/6
Excluir atividade 6/6

① Runtime de integração do Azure ② Runtime de integração auto-hospedada

Especificamente, este conector de FTP dá suporte a:

O conector de FTP é compatível com o servidor FTP em execução no modo passivo. Não há suporte para o modo ativo.

Pré-requisitos

Se o armazenamento de dados estiver localizado dentro de uma rede local, em uma rede virtual do Azure ou na Amazon Virtual Private Cloud, você precisará configurar um runtime de integração auto-hospedada para se conectar a ele.

Se o armazenamento de dados for um serviço de dados de nuvem gerenciado, você poderá usar o Azure Integration Runtime. Se o acesso for restrito aos IPs que estão aprovados nas regras de firewall, você poderá adicionar IPs do Azure Integration Runtime à lista de permissões.

Você também pode usar o recurso de runtime de integração da rede virtual gerenciada no Azure Data Factory para acessar a rede local sem instalar e configurar um runtime de integração auto-hospedada.

Para obter mais informações sobre os mecanismos de segurança de rede e as opções compatíveis com o Data Factory, consulte Estratégias de acesso a dados.

Introdução

Para executar a atividade de Cópia com um pipeline, será possível usar as ferramentas ou os SDKs abaixo:

Criar um serviço vinculado para um servidor FTP usando a interface do usuário

Use as etapas a seguir para criar um serviço vinculado para um servidor FTP na interface do usuário do portal do Azure.

  1. Navegue até a guia Gerenciar no workspace do Azure Data Factory ou do Synapse, selecione Serviços Vinculados e clique em Novo:

  2. Procure FTP e selecione o conector do FTP.

    Screenshot of the FTP connector.

  3. Configure os detalhes do serviço, teste a conexão e crie o novo serviço vinculado.

    Screenshot of linked service configuration for an FTP server.

Detalhes da configuração do conector

As seções a seguir fornecem detalhes sobre as propriedades que são usadas para definir entidades específicas do FTP.

Propriedades do serviço vinculado

As propriedades a seguir têm suporte para o serviço vinculado do FTP:

Propriedade Descrição Obrigatório
type A propriedade type deve ser definida como: FtpServer. Sim
host Especifique o nome ou endereço IP do servidor FTP. Sim
porta Especifique a porta ouvida pelo servidor FTP.
Os valores permitidos são: inteiro, o valor padrão é 21.		 Não
enableSsl Especifique se o canal FTP sobre SSL/TLS deve ser usado.
Os valores permitidos são: true (padrão), false.		 Não
enableServerCertificateValidation Especifique se deseja habilitar a validação do certificado TLS/SSL do servidor ao usar o canal FTP sobre SSL/TLS.
Os valores permitidos são: true (padrão), false.		 Não
authenticationType Especifique o tipo de autenticação.
Valores permitidos são: Básica, Anônima		 Sim
userName Especifique o usuário que tem acesso ao servidor FTP. Não
password Especifica a senha para o usuário (userName). Marque este campo como um SecureString para armazená-lo com segurança ou referencie um segredo armazenado no Azure Key Vault. Não
connectVia O Integration Runtime a ser usado para se conectar ao armazenamento de dados. Saiba mais na seção Pré-requisitos. Se não for especificado, ele usa o Integration Runtime padrão do Azure. Não

Observação

O conector FTP oferece suporte ao acessar o servidor FTP sem criptografia ou a criptografia de SSL/TLS explícita; ele não oferece suporte a criptografia SSL/TLS implícita.

Exemplo 1: usando a autenticação Anônima

{
    "name": "FTPLinkedService",
    "properties": {
        "type": "FtpServer",
        "typeProperties": {
            "host": "<ftp server>",
            "port": 21,
            "enableSsl": true,
            "enableServerCertificateValidation": true,
            "authenticationType": "Anonymous"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Exemplo 2: usando a autenticação Básica

{
    "name": "FTPLinkedService",
    "properties": {
        "type": "FtpServer",
        "typeProperties": {
            "host": "<ftp server>",
            "port": 21,
            "enableSsl": true,
            "enableServerCertificateValidation": true,
            "authenticationType": "Basic",
            "userName": "<username>",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Propriedades do conjunto de dados

Para obter uma lista completa das seções e propriedades disponíveis para definir os conjuntos de dados, confira o artigo sobre Conjuntos de Dados.

O Azure Data Factory é compatível com os formatos de arquivo a seguir. Confira cada artigo para obter configurações baseadas em formato.

As seguintes propriedades são compatíveis com FTP em configurações de location no conjunto de dados com base em formato:

Propriedade Descrição Obrigatório
type A propriedade de tipo em location no conjunto de dados deve ser definida como FtpServerLocation. Sim
folderPath O caminho para a pasta. Se quiser usar um caractere curinga para filtrar a pasta, ignore essa configuração e especifique nas configurações de origem da atividade. Não
fileName O nome do arquivo sob o folderPath fornecido. Se quiser usar um caractere curinga para filtrar os arquivos, ignore essa configuração e especifique nas configurações de origem da atividade. Não

Exemplo:

{
    "name": "DelimitedTextDataset",
    "properties": {
        "type": "DelimitedText",
        "linkedServiceName": {
            "referenceName": "<FTP linked service name>",
            "type": "LinkedServiceReference"
        },
        "schema": [ < physical schema, optional, auto retrieved during authoring > ],
        "typeProperties": {
            "location": {
                "type": "FtpServerLocation",
                "folderPath": "root/folder/subfolder"
            },
            "columnDelimiter": ",",
            "quoteChar": "\"",
            "firstRowAsHeader": true,
            "compressionCodec": "gzip"
        }
    }
}

Propriedades da atividade de cópia

Para obter uma lista completa das seções e propriedades disponíveis para definir atividades, confia o artigo Pipelines. Esta seção fornece uma lista das propriedades com suporte pela fonte FTP.

FTP como fonte

O Azure Data Factory é compatível com os formatos de arquivo a seguir. Confira cada artigo para obter configurações baseadas em formato.

As seguintes propriedades são compatíveis com FTP em configurações de storeSettings na origem de cópia baseada em formato:

Propriedade Descrição Obrigatório
type A propriedade de tipo em storeSettings deve ser definida como FtpReadSettings. Sim
Localize os arquivos a serem copiados:
OPÇÃO 1: caminho estático
 Copiar do caminho de pasta/arquivo especificado no conjunto de dados. Se quiser copiar todos os arquivos de uma pasta, especifique também wildcardFileName como *.
OPÇÃO 2: curinga
- wildcardFolderPath		 O caminho da pasta com caracteres curinga para filtrar as pastas de origem.
Os curingas permitidos são: * (corresponde a zero ou mais caracteres) e ? (corresponde a zero ou caractere único); use ^ para escape se o nome de pasta atual tiver curinga ou esse caractere interno de escape.
Veja mais exemplos em Exemplos de filtro de pastas e arquivos.		 Não
OPÇÃO 2: curinga
- wildcardFileName		 O nome do arquivo com caracteres curinga sob o folderPath/wildcardFolderPath fornecido para filtrar os arquivos de origem.
Os curingas permitidos são: * (corresponde a zero ou mais caracteres) e ? (corresponde a zero ou caractere único); use ^ para escape se o nome de arquivo real tiver curinga ou esse caractere interno de escape. Veja mais exemplos em Exemplos de filtro de pastas e arquivos.		 Sim
OPÇÃO 3: uma lista de arquivos
- fileListPath		 Indica a cópia de um determinado conjunto de arquivos. Aponte para um arquivo de texto que inclui a lista de arquivos que você deseja copiar com um arquivo por linha, que é o caminho relativo para o caminho configurado no conjunto de dados.
Ao usar essa opção, não especifique o nome do arquivo no conjunto de dados. Veja mais exemplos em Exemplos de lista de arquivos.		 Não
Configurações adicionais:
recursiva Indica se os dados são lidos recursivamente das subpastas ou somente da pasta especificada. Observe que quando recursiva é definida como true e o coletor é um armazenamento baseado em arquivo, uma pasta vazia ou subpasta não é copiada ou criada no coletor.
Os valores permitidos são true (padrão) e false.
Essa propriedade não se aplica quando você configura fileListPath.		 Não
deleteFilesAfterCompletion Indica se os arquivos binários serão excluídos do repositório de origem após a movimentação com êxito para o repositório de destino. A exclusão do arquivo é feita por arquivo, portanto, quando a atividade de cópia falhar, você verá que alguns arquivos já foram copiados para o destino e excluídos da origem, enquanto outros ainda permanecem no repositório de origem.
Essa propriedade só é válida no cenário de cópia de arquivos binários. O valor padrão é false.		 Não
useBinaryTransfer Especifique se o modo de transferência binário deve ser usado. Os valores são true para o modo binário (padrão) e false para ASCII. Não
enablePartitionDiscovery Para arquivos que são particionados, especifique se deseja analisar as partições do caminho do arquivo e adicioná-las como colunas de origem adicionais.
Os valores permitidos são false (padrão) e true.		 No
partitionRootPath Quando a descoberta de partição estiver habilitada, especifique o caminho raiz absoluto para ler as pastas particionadas como colunas de dados.

Se ele não for especificado, por padrão ocorrerá o seguinte:
– Quando você usa o caminho do arquivo no conjunto de dados ou na lista de arquivos na origem, o caminho raiz da partição é o caminho configurado no conjunto de dados.
– Quando você usa o filtro de pasta curinga, o caminho raiz da partição é o subcaminho antes do primeiro curinga.

Por exemplo, supondo que você configure o caminho no conjunto de dados como "root/folder/year=2020/month=08/day=27":
– Se você especifica o caminho raiz da partição como "root/folder/year=2020", a atividade de cópia gera mais duas colunas month e day com o valor "08" e "27", respectivamente, além das colunas dentro dos arquivos.
– Se o caminho raiz da partição não for especificado, nenhuma coluna extra será gerada.		 Não
maxConcurrentConnections O limite superior de conexões simultâneas estabelecidas com o armazenamento de dados durante a execução da atividade. Especifique um valor somente quando desejar limitar as conexões simultâneas. Não
disableChunking Ao copiar dados do FTP, o serviço tenta obter o comprimento do arquivo primeiro, depois divide o arquivo em várias partes e as lê em paralelo. Especifique se o servidor FTP dá suporte para obter o comprimento do arquivo ou procurando ler de um determinado deslocamento.
Os valores permitidos são false (padrão) e true.		 Não

Exemplo:

"activities":[
    {
        "name": "CopyFromFTP",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Delimited text input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "DelimitedTextSource",
                "formatSettings":{
                    "type": "DelimitedTextReadSettings",
                    "skipLineCount": 10
                },
                "storeSettings":{
                    "type": "FtpReadSettings",
                    "recursive": true,
                    "wildcardFolderPath": "myfolder*A",
                    "wildcardFileName": "*.csv",
                    "disableChunking": false
                }
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Exemplos de filtro de pasta e arquivo

Esta seção descreve o comportamento resultante do caminho da pasta e do nome de arquivo com filtros curinga.

folderPath fileName recursiva Estrutura da pasta de origem e resultado do filtro (os arquivos em negrito são recuperados)
Folder* (vazio, usar padrão) false FolderA
    Arquivo1.csv
    File2.json
    Subpasta1
        File3.csv
        File4.json
        File5.csv
OutraPastaB
    Arquivo6.csv
Folder* (vazio, usar padrão) true FolderA
    Arquivo1.csv
    File2.json
    Subpasta1
        File3.csv
        File4.json
        File5.csv
OutraPastaB
    Arquivo6.csv
Folder* *.csv false FolderA
    Arquivo1.csv
    Arquivo2.json
    Subpasta1
        File3.csv
        File4.json
        File5.csv
OutraPastaB
    Arquivo6.csv
Folder* *.csv true FolderA
    Arquivo1.csv
    Arquivo2.json
    Subpasta1
        File3.csv
        File4.json
        File5.csv
OutraPastaB
    Arquivo6.csv

Exemplos de lista de arquivos

Esta seção descreve o comportamento resultante do uso do caminho da lista de arquivos na origem da atividade de cópia.

Supondo que você tenha a seguinte estrutura de pasta de origem e queira copiar os arquivos em negrito:

Exemplo de estrutura de origem Conteúdo em FileListToCopy.txt Configuração
root
    FolderA
        Arquivo1.csv
        Arquivo2.json
        Subpasta1
            File3.csv
            File4.json
            File5.csv
    Metadados
        FileListToCopy.txt		 File1.csv
Subfolder1/File3.csv
Subfolder1/File5.csv		 No conjunto de dados:
- Caminho da pasta: root/FolderA

Na origem da atividade de cópia:
- Caminho da lista de arquivos: root/Metadata/FileListToCopy.txt

O caminho da lista de arquivos aponta para um arquivo de texto no mesmo armazenamento de dados que inclui a lista de arquivos que você deseja copiar, um arquivo por linha, com o caminho relativo do caminho configurado no conjunto de dados.

Pesquisar propriedades de atividades

Para saber detalhes sobre as propriedades, verifique Atividade de pesquisa.

Propriedades de atividade GetMetadata

Para saber detalhes sobre as propriedades, verifique Atividade GetMetadata

Excluir propriedades da atividade

Para saber mais detalhes sobre as propriedades, marque Excluir atividade

Modelos herdados

Observação

Os modelos a seguir ainda têm suporte no estado em que se encontram, para compatibilidade com versões anteriores. É recomendável usar o novo modelo mencionado nas seções acima no futuro, e a interface do usuário de criação mudou para gerar o novo modelo.

Modelo de conjunto de dados herdado

Propriedade Descrição Obrigatório
type A propriedade type do conjunto de dados deve ser definida como: FileShare Sim
folderPath Caminho para a pasta. O filtro curinga é permitido; os curingas permitidos são: * (corresponde a zero ou mais caracteres) e ? (corresponde a zero ou caractere único); use ^ para escape se o nome real da pasta tiver um curinga ou esse caractere interno de escape.

Exemplos: rootfolder/subfolder/; veja mais exemplos em Exemplos de filtro de pasta e arquivo.		 Sim
fileName Filtro de nome ou curinga para os arquivos em "folderPath" especificado. Se você não especificar um valor para essa propriedade, o conjunto de dados apontará para todos os arquivos na pasta.

Para filtro, os curingas permitidos são: * (corresponde a zero ou mais caracteres) e ? (corresponde a zero ou caractere único).
– Exemplo 1: "fileName": "*.csv"
– Exemplo 2: "fileName": "???20180427.txt"
Use ^ para se seu nome de arquivo real curinga ou esse caractere de escape dentro de escape.		 Não
format Se você quiser copiar arquivos no estado em que se encontram entre repositórios baseados em arquivo (cópia binária), ignore a seção de formato nas duas definições de conjunto de dados de entrada e de saída.

Se você quer analisar arquivos com um formato específico, os seguintes tipos de formato de arquivo têm suporte: TextFormat, JsonFormat, AvroFormat, OrcFormat, ParquetFormat. Defina a propriedade type sob formato como um desses valores. Para saber mais, veja as seções Formato de texto, Formato Json, Formato Avro, Formato Orc, e Formato Parquet.		 Não (somente para o cenário de cópia binária)
compactação Especifique o tipo e o nível de compactação para os dados. Para obter mais informações, consulte Formatos de arquivo e codecs de compactação com suporte.
Tipos compatíveis são: GZip, Deflate, BZip2 e ZipDeflate.
Níveis compatíveis são: Ideal e Mais Rápido.		 Não
useBinaryTransfer Especifique se o modo de transferência binário deve ser usado. Os valores são true para o modo binário (padrão) e false para ASCII. Não

Dica

Para copiar todos os arquivos em uma pasta, especifique folderPath somente.
Para copiar um único arquivo com um determinado nome, especifique folderPath com parte da pasta e fileName com nome de arquivo.
Para copiar um subconjunto de arquivos em uma pasta, especifique folderPath com parte da pasta e fileName com filtro curinga.

Observação

Se você estivesse usando a propriedade "fileFilter" para o filtro de arquivo, ele ainda tem suporte como-é, enquanto são sugeridos para usar o novo recurso de filtro adicionado ao "fileName" no futuro.

Exemplo:

{
    "name": "FTPDataset",
    "properties": {
        "type": "FileShare",
        "linkedServiceName":{
            "referenceName": "<FTP linked service name>",
            "type": "LinkedServiceReference"
        },
        "typeProperties": {
            "folderPath": "folder/subfolder/",
            "fileName": "myfile.csv.gz",
            "format": {
                "type": "TextFormat",
                "columnDelimiter": ",",
                "rowDelimiter": "\n"
            },
            "compression": {
                "type": "GZip",
                "level": "Optimal"
            }
        }
    }
}

Modelo de origem de atividade de cópia herdado

Propriedade Descrição Obrigatório
type A propriedade type da fonte da atividade de cópia deve ser definida como: FileSystemSource Sim
recursiva Indica se os dados são lidos recursivamente a partir das subpastas ou somente da pasta especificada. Observe que quando o recursivo estiver definido como verdadeiro e o coletor for um armazenamento baseado em arquivo, subpasta/pasta vazia não será copiada/criada no coletor.
Os valores permitidos são: true (padrão), false		 Não
maxConcurrentConnections O limite superior de conexões simultâneas estabelecidas com o armazenamento de dados durante a execução da atividade. Especifique um valor somente quando desejar limitar as conexões simultâneas. Não

Exemplo:

"activities":[
    {
        "name": "CopyFromFTP",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<FTP input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "FileSystemSource",
                "recursive": true
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Conteúdo relacionado

Para obter uma lista de armazenamentos de dados com suporte como coletores e fontes da atividade de cópia, confira os armazenamentos de dados com suporte.