Copiar dados do Armazenamento Compatível do Amazon S3 usando o Azure Data Factory ou o 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 Amazon S3 (Simple Storage Service) de Armazenamento Compatível. 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 Armazenamento Compatível do Amazon S3 para as 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 do Armazenamento Compatível do Amazon S3 dá suporte à cópia de arquivos no estado em que se encontram ou à análise de arquivos com os formatos de arquivo e codecs de compactação com suporte. O conector usa a Assinatura da AWS versão 4 para autenticar solicitações para S3. Você pode usar esse conector do Armazenamento Compatível do Amazon S3 para copiar dados de qualquer provedor de armazenamento compatível com o S3. Especifique a URL do serviço correspondente na configuração do serviço vinculado.

Permissões necessárias

Para copiar dados do Armazenamento Compatível do Amazon S3, verifique se você recebeu as seguintes permissões para operações de objeto do Amazon S3: s3:GetObject e s3:GetObjectVersion.

Se você usar a interface do usuário para criar, s3:ListAllMyBuckets e s3:ListBucket/s3:GetBucketLocation serão necessárias permissões adicionais para operações como testar a conexão com o serviço vinculado e navegar da raiz. Se você não quiser conceder essas permissões, poderá escolher as opções "Testar a conexão com o caminho do arquivo" ou "Procurar a partir do caminho especificado" na interface do usuário.

Parra detalhes sobre a lista completa e detalhada das permissões do Amazon S3,consulte Especificar permissões em uma política no site da AWS.

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 ao Armazenamento Compatível do Amazon S3 usando a interface do usuário

Use as etapas a seguir para criar um serviço vinculado ao Armazenamento Compatível do Amazon S3 na interface do usuário do portal do Microsoft 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. Pesquise por Amazon e selecione o conector do Armazenamento Compatível do Amazon S3.

    Select the Amazon S3 Compatible Storage connector.

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

    Configure a linked service to Amazon S3 Compatible Storage.

Detalhes da configuração do conector

As seções seguintes fornecem detalhes sobre as propriedades que são usadas para definir entidades específicas ao Armazenamento Compatível do Amazon S3.

Propriedades do serviço vinculado

As propriedades a seguir têm suporte para um serviço vinculado compatível do Amazon S3:

Propriedade Descrição Obrigatório
type A propriedade type deve ser definida como AmazonS3Compatible. Sim
accessKeyId ID da chave de acesso secreta. Sim
secretAccessKey A chave de acesso do secreta em si. Marque esse campo como SecureString para armazená-lo com segurança ou referencie um segredo armazenado no Azure Key Vault. Sim
serviceUrl Especifique o ponto de extremidade S3 personalizado como https://<service url>. Não
forcePathStyle Indica se deve ser usado o acesso estilo de caminho do S3 em vez do acesso estilo hospedado virtual. Os valores permitidos são false (padrão) e true.
Verifique a documentação de cada repositório de dados sobre se o acesso ao estilo de caminho é necessário ou não.		 Não
connectVia O runtime de integração a ser usado para se conectar ao armazenamento de dados. Use o runtime de integração do Azure ou o runtime de integração auto-hospedada (se o seu armazenamento de dados estiver em uma rede privada). Se essa propriedade não for especificada, o serviço usará o runtime de integração do Azure padrão. Não

Exemplo:

{
    "name": "AmazonS3CompatibleLinkedService",
    "properties": {
        "type": "AmazonS3Compatible",
        "typeProperties": {
            "accessKeyId": "<access key id>",
            "secretAccessKey": {
                "type": "SecureString",
                "value": "<secret access key>"
            }
        },
        "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.

O Amazon S3 Compatível suporta as seguintes propriedades nas configurações location em um conjunto de dados baseado no formato:

Propriedade Descrição Obrigatório
type A propriedade de tipo sob location em um conjunto de dados deve ser configurada como AmazonS3CompatibleLocation. Sim
bucketName O nome do bucket do Armazenamento Compatível do S3. Sim
folderPath O caminho para a pasta sob o bucket fornecido. Se quiser usar um caractere curinga para filtrar a pasta, ignore essa configuração e especifique isso nas configurações de origem da atividade. Não
fileName O nome do arquivo sob o bucket e caminho da pasta fornecidos. Se você quiser usar um caractere curinga para filtrar os arquivos, ignore essa configuração e especifique isso nas configurações de origem da atividade. Não
version A versão do objeto de Armazenamento Compatível do S3, se o controle de versão do S3 de Armazenamento Compatível estiver habilitado. Se não for especificada, a versão mais recente será buscada. Não

Exemplo:

{
    "name": "DelimitedTextDataset",
    "properties": {
        "type": "DelimitedText",
        "linkedServiceName": {
            "referenceName": "<Amazon S3 Compatible Storage linked service name>",
            "type": "LinkedServiceReference"
        },
        "schema": [ < physical schema, optional, auto retrieved during authoring > ],
        "typeProperties": {
            "location": {
                "type": "AmazonS3CompatibleLocation",
                "bucketName": "bucketname",
                "folderPath": "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 para as quais a fonte do Armazenamento Compatível do Amazon S3 oferece suporte.

Armazenamento Compatível do Amazon S3 como tipo de origem

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

O Armazenamento Compatível do Amazon S3 suporta as seguintes propriedades em storeSettings configurações na fonte de cópia baseada em formato:

Propriedade Descrição Obrigatório
type A propriedade tipo em storeSettings deve ser configurada para AmazonS3CompatibleReadSettings. Sim
Localize os arquivos a serem copiados:
OPÇÃO 1: caminho estático
 Copiar do caminho do bucket ou de pasta/arquivo especificado no conjunto de dados. Caso deseje copiar todos os arquivos de um bucket ou uma pasta, especifique também wildcardFileName como *.
OPÇÃO 2: prefixo do Armazenamento Compatível do S3
– prefix		 Prefixo para o nome da chave Armazenamento Compatível do S3 sob o bucket especificado configurado no conjunto de dados para filtrar os arquivos do Armazenamento Compatível do S3 de origem. As chaves do Armazenamento Compatível do S3 cujos nomes começam com bucket_in_dataset/this_prefix são selecionadas. Utiliza o filtro do lado do serviço de Armazenamento Compatível do S3, que fornece melhor desempenho do que o filtro curinga.

Quando você usa o prefixo e opta por copiar para o coletor baseado em arquivo com a hierarquia de preservação, observe que o subcaminho após o último "/" no prefixo será preservado. Por exemplo, você tem a origem bucket/folder/subfolder/file.txt e configura o prefixo como folder/sub, então o caminho do arquivo preservado é subfolder/file.txt.		 Não
OPÇÃO 3: curinga
- wildcardFolderPath		 O caminho da pasta com caracteres curinga sob o bucket fornecido configurado no conjunto de dados 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 ^ como escape se o nome real da pasta tiver curingas ou esse caractere de escape.
Veja mais exemplos em Exemplos de filtro de pastas e arquivos.		 Não
OPÇÃO 3: curinga
- wildcardFileName		 O nome do arquivo com caracteres curinga sob o bucket e caminho da pasta fornecidos (ou o caminho da pasta curinga) 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 ^ como escape se o nome do arquivo contiver um curinga ou esse caractere de escape. Veja mais exemplos em Exemplos de filtro de pastas e arquivos.		 Sim
OPÇÃO 4: 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 um nome de 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 repositório baseado em arquivo, uma pasta vazia ou uma subpasta não é copiada nem 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
modifiedDatetimeStart Os arquivos são filtrados com base no atributo última modificação.
Os arquivos serão selecionados se a hora da última modificação for maior ou igual a modifiedDatetimeStart e menor que modifiedDatetimeEnd. A hora é aplicada ao fuso horário de UTC no formato "2018-12-01T05:00:00Z".
As propriedades podem ser NULL, o que significa que nenhum filtro de atributo de arquivo será aplicado ao conjunto de dados. Quando modifiedDatetimeStart tiver um valor de datetime, mas modifiedDatetimeEnd for NULL, serão selecionados os arquivos cujo último atributo modificado for maior ou igual ao valor de datetime. Quando modifiedDatetimeEnd tem um valor datetime, mas modifiedDatetimeStart é NULL, serão selecionados os arquivos cujo último atributo modificado for menor que o valor do datetime.
Essa propriedade não se aplica quando você configura fileListPath.		 Não
modifiedDatetimeEnd Mesmo que acima. 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.
-Quando você usa o prefixo, o caminho raiz da partição é o subcaminho antes do último "/".

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

Exemplo:

"activities":[
    {
        "name": "CopyFromAmazonS3CompatibleStorage",
        "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": "AmazonS3CompatibleReadSettings",
                    "recursive": true,
                    "wildcardFolderPath": "myfolder*A",
                    "wildcardFileName": "*.csv"
                }
            },
            "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.

bucket chave recursiva Estrutura da pasta de origem e resultado do filtro (os arquivos em negrito são recuperados)
bucket Folder*/* false bucket
    FolderA
        Arquivo1.csv
        File2.json
        Subpasta1
            File3.csv
            File4.json
            File5.csv
    OutraPastaB
        Arquivo6.csv
bucket Folder*/* true bucket
    FolderA
        Arquivo1.csv
        File2.json
        Subpasta1
            File3.csv
            File4.json
            File5.csv
    OutraPastaB
        Arquivo6.csv
bucket Folder*/*.csv false bucket
    FolderA
        Arquivo1.csv
        Arquivo2.json
        Subpasta1
            File3.csv
            File4.json
            File5.csv
    OutraPastaB
        Arquivo6.csv
bucket Folder*/*.csv true bucket
    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 Copy.

Suponha 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
bucket
    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:
– Bucket: bucket
- Caminho da pasta: FolderA

Na origem da atividade Copy:
- Caminho da lista de arquivos: bucket/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 atividade

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

Propriedades de atividade GetMetadata

Para saber detalhes sobre as propriedades, confira Atividade GetMetadata.

Excluir propriedades da atividade

Para saber mais detalhes sobre as propriedades, confira Atividade Delete.

Conteúdo relacionado

Para obter uma lista de armazenamentos de dados que a atividade Copy suporta, como fontes e coletores, consulte Armazenamentos de dados compatíveis.