Copiar dados de ou para os Arquivos do Azure usando o Azure Data Factory

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Este artigo descreve como copiar dados de e para os Arquivos do Azure. Para saber mais sobre o Azure Data Factory, leia as artigo introdutório.

Funcionalidades com suporte

O conector dos Arquivos do Azure é compatível com as seguintes funcionalidades:

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

Você pode copiar os dados dos Arquivos do Azure para qualquer armazenamento de dados de origem com suporte, ou copiar os dados de qualquer armazenamento de dados de origem com suporte para os Arquivos do Azure. Para obter uma lista de armazenamentos de dados que o Copy Activity suporta como fontes e coletores, consulte Armazenamentos de dados e formatos compatíveis.

Especificamente, este conector dos Arquivos do Azure dá suporte a:

• Copiar arquivos usando autenticações SAS (assinatura de acesso compartilhado) de serviço ou chave de conta.
• Cópia de arquivos no estado em que se encontram ou análise/geração de arquivos com os formatos de arquivo e codecs de compactação com suporte.

Introdução

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

• A ferramenta Copiar Dados
• O portal do Azure
• O SDK do .NET
• O SDK do Python
• PowerShell do Azure
• A API REST
• O modelo do Azure Resource Manager

Criar um serviço vinculado para os Arquivos do Azure usando a interface do usuário

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

1. Navegue até a guia Gerenciar em seu espaço de trabalho do Azure Data Factory ou do Synapse, selecione Serviços Vinculados e clique em Novo:

   • Azure Data Factory
   • Azure Synapse

   

2. Pesquise o arquivo e selecione o conector para os Arquivos do Azure rotulado como Armazenamento de Arquivos do Azure.

   

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

   

Detalhes da configuração do conector

As seções que se seguem fornecem detalhes sobre as propriedades que são usadas para definir entidades específicas dos Arquivos do Azure.

Propriedades do serviço vinculado

O conector dos Arquivos do Azure dá suporte aos seguintes tipos de autenticação. Consulte as seções correspondentes para obter detalhes.

• Autenticação de chave de conta
• Autenticação de assinatura de acesso compartilhado
• Autenticação de identidade gerenciada atribuída pelo sistema
• Autenticação de identidade gerenciada atribuída pelo usuário

Autenticação de chave de conta

O Data Factory dá suporte às seguintes propriedades para autenticação de chave de conta dos Arquivos do Azure:

Exemplo:

{
    "name": "AzureFileStorageLinkedService",
    "properties": {
        "type": "AzureFileStorage",
        "typeProperties": {
            "connectionString": "DefaultEndpointsProtocol=https;AccountName=<accountName>;AccountKey=<accountKey>;EndpointSuffix=core.windows.net;",
            "fileShare": "<file share name>"
        },
        "connectVia": {
          "referenceName": "<name of Integration Runtime>",
          "type": "IntegrationRuntimeReference"
        }
    }
}

Exemplo: armazenar a chave de conta no Azure Key Vault

{
    "name": "AzureFileStorageLinkedService",
    "properties": {
        "type": "AzureFileStorage",
        "typeProperties": {
            "connectionString": "DefaultEndpointsProtocol=https;AccountName=<accountname>;",
            "fileShare": "<file share name>",
            "accountKey": { 
                "type": "AzureKeyVaultSecret", 
                "store": { 
                    "referenceName": "<Azure Key Vault linked service name>", 
                    "type": "LinkedServiceReference" 
                }, 
                "secretName": "<secretName>" 
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }            
    }
}

Autenticação de assinatura de acesso compartilhado

Uma assinatura de acesso compartilhado fornece acesso delegado aos recursos da sua conta de armazenamento. Você pode usar uma assinatura de acesso compartilhado para conceder a um cliente permissões limitadas para objetos em sua conta de armazenamento por determinado tempo. Para obter mais informações sobre assinaturas de acesso compartilhado, consulte Assinaturas de acesso compartilhado: Entender o modelo de assinatura de acesso compartilhado.

O serviço dá suporte às seguintes propriedades para usar a autenticação de assinatura de acesso compartilhado:

Exemplo:

{
    "name": "AzureFileStorageLinkedService",
    "properties": {
        "type": "AzureFileStorage",
        "typeProperties": {
            "sasUri": {
                "type": "SecureString",
                "value": "<SAS URI of the resource e.g. https://<accountname>.file.core.windows.net/?sv=<storage version>&st=<start time>&se=<expire time>&sr=<resource>&sp=<permissions>&sip=<ip range>&spr=<protocol>&sig=<signature>>"
            },
            "fileShare": "<file share name>",
            "snapshot": "<snapshot version>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Exemplo: armazenar o token SAS em Azure Key Vault

{
    "name": "AzureFileStorageLinkedService",
    "properties": {
        "type": "AzureFileStorage",
        "typeProperties": {
            "sasUri": {
                "type": "SecureString",
                "value": "<SAS URI of the Azure Storage resource without token e.g. https://<accountname>.file.core.windows.net/>"
            },
            "sasToken": { 
                "type": "AzureKeyVaultSecret", 
                "store": { 
                    "referenceName": "<Azure Key Vault linked service name>", 
                    "type": "LinkedServiceReference" 
                }, 
                "secretName": "<secretName with value of SAS token e.g. ?sv=<storage version>&st=<start time>&se=<expire time>&sr=<resource>&sp=<permissions>&sip=<ip range>&spr=<protocol>&sig=<signature>>" 
            },
            "fileShare": "<file share name>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Autenticação de identidade gerenciada atribuída pelo sistema

Um pipeline do data factory ou do Synapse pode ser associado a uma identidade gerenciada atribuída pelo sistema para recursos do Azure, que representa esse recurso para autenticação em outros serviços do Azure. Você pode usar essa identidade gerenciada atribuída pelo sistema para autenticação de Arquivos do Azure. Para saber mais sobre as identidades gerenciadas para recursos do Azure, confira Identidades gerenciadas para recursos do Azure.

Para usar a autenticação de identidade gerenciada atribuída pelo sistema, siga estas etapas:

1. Recuperar identidade gerenciada atribuída pelo sistema copiando o valor da ID de objeto de identidade gerenciada atribuída pelo sistema gerado com o workspace do Factory ou do Synapse.

2. Conceda a permissão de identidade gerenciada nos Arquivos do Azure. Para mais informações sobre as funções, confira este artigo.

   • Como origem, em Controle de acesso (IAM), conceda pelo menos a função Leitor privilegiado de dados de arquivo de armazenamento.
   • Como coletor, em Controle de acesso (IAM), conceda pelo menos a função Colaborador privilegiado de dados de arquivo de armazenamento.

Essas propriedades têm suporte para um serviço vinculado de Arquivos do Azure:

Exemplo:

{
    "name": "AzureFileStorageLinkedService",
    "properties": {
        "type": "AzureFileStorage",
        "typeProperties": {            
            "serviceEndpoint": "https://<accountName>.file.core.windows.net/",
            "fileShare": "<file share name>",
            "snapshot": "<snapshot version>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Autenticação de identidade gerenciada atribuída pelo usuário

Um data factory pode ser atribuído com uma ou várias identidades gerenciadas atribuídas pelo usuário. Você pode usar essa identidade gerenciada atribuída pelo usuário para autenticação de Arquivos do Azure, que permite acessar e copiar dados de ou para Arquivos do Azure. Para saber mais sobre as identidades gerenciadas para recursos do Azure, confira Identidades gerenciadas para recursos do Azure.

Para usar a autenticação de identidade gerenciada atribuída pelo usuário, siga estas etapas:

1. Crie uma ou várias identidades gerenciadas atribuídas ao usuário e conceda permissão nos Arquivos do Azure. Para mais informações sobre as funções, confira este artigo.

   • Como origem, em Controle de acesso (IAM), conceda pelo menos a função Leitor privilegiado de dados de arquivo de armazenamento.
   • Como coletor, em Controle de acesso (IAM), conceda pelo menos a função Colaborador privilegiado de dados de arquivo de armazenamento.

2. Atribua uma ou várias identidades gerenciadas atribuídas pelo usuário a seu data factory e crie credenciais para cada identidade gerenciada atribuída pelo usuário.

Essas propriedades têm suporte para um serviço vinculado de Arquivos do Azure:

Exemplo:

{
    "name": "AzureFileStorageLinkedService",
    "properties": {
        "type": "AzureFileStorage",
        "typeProperties": {            
            "serviceEndpoint": "https://<accountName>.file.core.windows.net/",
            "credential": {
                "referenceName": "credential1",
                "type": "CredentialReference"
            },
            "fileShare": "<file share name>",
            "snapshot": "<snapshot version>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Modelo herdado

Exemplo:

{
    "name": "AzureFileStorageLinkedService",
    "properties": {
        "type": "AzureFileStorage",
        "typeProperties": {
            "host": "\\\\<storage name>.file.core.windows.net\\<file service name>",
            "userid": "AZURE\\<storage name>",
            "password": {
                "type": "SecureString",
                "value": "<storage 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.

• Formato Avro
• Formato binário
• Formato de texto delimitado
• Formato do Excel
• Formato JSON
• Formato ORC
• Formato Parquet
• Formato XML

As propriedades a seguir são suportadas para os Arquivos do Azure em location configurações de conjunto de dados baseado em formato:

Exemplo:

{
    "name": "DelimitedTextDataset",
    "properties": {
        "type": "DelimitedText",
        "linkedServiceName": {
            "referenceName": "<Azure File Storage linked service name>",
            "type": "LinkedServiceReference"
        },
        "schema": [ < physical schema, optional, auto retrieved during authoring > ],
        "typeProperties": {
            "location": {
                "type": "AzureFileStorageLocation",
                "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 e pelo coletor dos Arquivos do Azure.

Arquivos do Azure como origem

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

• Formato Avro
• Formato binário
• Formato de texto delimitado
• Formato do Excel
• Formato JSON
• Formato ORC
• Formato Parquet
• Formato XML

Os Arquivos do Azure dão suporte às seguintes propriedades nas configurações storeSettings na origem da cópia baseada no formato:

Exemplo:

"activities":[
    {
        "name": "CopyFromAzureFileStorage",
        "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": "AzureFileStorageReadSettings",
                    "recursive": true,
                    "wildcardFolderPath": "myfolder*A",
                    "wildcardFileName": "*.csv"
                }
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Arquivos do Azure como coletor

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

• Formato Avro
• Formato binário
• Formato de texto delimitado
• Formato JSON
• Formato ORC
• Formato Parquet

Os Arquivos do Azure dão suporte às seguintes propriedades nas configurações storeSettings no coletor da cópia baseada no formato:

Exemplo:

"activities":[
    {
        "name": "CopyToAzureFileStorage",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<Parquet output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "ParquetSink",
                "storeSettings":{
                    "type": "AzureFileStorageWriteSettings",
                    "copyBehavior": "PreserveHierarchy"
                }
            }
        }
    }
]

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.

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:

exemplos de recursive e copyBehavior

Esta seção descreve o comportamento resultante da operação de cópia para diferentes combinações de valores recursive e copyBehavior.

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

Modelo de conjunto de dados herdado

Exemplo:

{
    "name": "AzureFileStorageDataset",
    "properties": {
        "type": "FileShare",
        "linkedServiceName":{
            "referenceName": "<Azure File Storage linked service name>",
            "type": "LinkedServiceReference"
        },
        "typeProperties": {
            "folderPath": "folder/subfolder/",
            "fileName": "*",
            "modifiedDatetimeStart": "2018-12-01T05:00:00Z",
            "modifiedDatetimeEnd": "2018-12-01T06:00:00Z",
            "format": {
                "type": "TextFormat",
                "columnDelimiter": ",",
                "rowDelimiter": "\n"
            },
            "compression": {
                "type": "GZip",
                "level": "Optimal"
            }
        }
    }
}

Modelo de origem de atividade de cópia herdado

Exemplo:

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

Modelo do coletor de atividade de cópia herdado

Exemplo:

"activities":[
    {
        "name": "CopyToAzureFileStorage",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<Azure File Storage output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "FileSystemSink",
                "copyBehavior": "PreserveHierarchy"
            }
        }
    }
]

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.