Copiar dados de ou para 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 o artigo introdutório.

Capacidades suportadas

Este conector de Arquivos do Azure é suportado para os seguintes recursos:

(1) Infraestrutura de integração do Azure (2) Infraestrutura de integração auto-hospedada

Você pode copiar dados dos Arquivos do Azure para qualquer armazenamento de dados de destino com suporte, ou copiar dados de qualquer armazenamento de dados de origem com suporte para os Arquivos do Azure. Para obter uma lista de armazenamentos de dados que a Atividade de Cópia suporta como fontes e coletores, consulte Formatos e armazenamentos de dados suportados.

Especificamente, este conector de Arquivos do Azure dá suporte:

• Copiar ficheiros utilizando a chave de conta ou a autenticação por assinatura de acesso partilhado de serviço (SAS).
• Copiar ficheiros as-is ou analisar/gerar ficheiros com os formatos de ficheiro suportados e codecs de compressão.

Como Começar

Para executar a atividade de cópia com um pipeline, você pode usar uma das seguintes ferramentas ou SDKs:

• Ferramenta Copiar dados
• portal do Azure
• SDK do .NET
• Python SDK
• Azure PowerShell
• API REST
• Modelo Azure Resource Manager

Criar um serviço vinculado aos 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 Synapse e selecione Serviços Vinculados e clique em Novo:

   • Fábrica de Dados do Azure
   • Azure Synapse

   

2. Pesquise pelo ficheiro e selecione o conector para Ficheiros do Azure com a designação Armazenamento de Ficheiros do Azure.

   

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

   

Detalhes de configuração do conector

As seções a seguir fornecem detalhes sobre as propriedades usadas para definir entidades específicas dos Arquivos do Azure.

Propriedades do serviço vinculado

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

• Autenticação da 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 da chave de conta

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

Example:

{
    "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 da conta no Cofre da Chave do Azure

{
    "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 em 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 um tempo especificado. Para obter mais informações sobre assinaturas de acesso compartilhado, consulte Assinaturas de acesso compartilhado: entenda o modelo de assinatura de acesso compartilhado.

O serviço suporta as seguintes propriedades para usar a autenticação de assinatura de acesso compartilhado:

Example:

{
    "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 no 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

Uma fábrica de dados ou pipeline 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 identidades gerenciadas para recursos do Azure, consulte Identidades gerenciadas para recursos do Azure.

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

1. Recupere informações de identidade gerenciada atribuídas pelo sistema copiando o valor do ID do objeto de identidade gerenciado atribuído pelo sistema gerado junto com sua fábrica ou espaço de trabalho Sinapse.

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

   • Como fonte, no Controle de Acesso (IAM), conceda pelo menos a função Storage File Data Privileged Reader.
   • Como destino, no Controle de acesso (IAM), conceda pelo menos a função Colaborador privilegiado de dados de ficheiro de armazenamento.

Estas propriedades têm suporte para um serviço vinculado do Azure Files:

Example:

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

Uma fábrica de dados pode ser atribuída 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 identidades gerenciadas para recursos do Azure, consulte 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 pelo usuário e conceda permissão nos Arquivos do Azure. Para obter mais informações sobre as funções, consulte este artigo.

   • Como fonte, no Controle de Acesso (IAM), conceda pelo menos a função Storage File Data Privileged Reader.
   • Como destino, no Controle de acesso (IAM), conceda pelo menos a função Colaborador privilegiado de dados de ficheiro de armazenamento.

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

Estas propriedades têm suporte para um serviço vinculado do Azure Files:

Example:

{
    "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 antigo

Example:

{
    "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 de seções e propriedades disponíveis para definir conjuntos de dados, consulte o artigo Conjuntos de dados.

O Azure Data Factory suporta os seguintes formatos de ficheiro. Consulte cada artigo para obter as configurações de acordo com o formato.

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

As seguintes propriedades são suportadas para Arquivos do Azure nas definições location no conjunto de dados com base no formato.

Example:

{
    "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 de seções e propriedades disponíveis para definir atividades, consulte o artigo Pipelines . Esta seção fornece uma lista de propriedades suportadas pela origem e pelo coletor do Azure Files.

Arquivos do Azure como origem

O Azure Data Factory suporta os seguintes formatos de ficheiro. Consulte cada artigo para obter as configurações de acordo com o formato.

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

As seguintes propriedades têm suporte para os Azure Files nas definições storeSettings na fonte de cópia baseada em formato:

Example:

"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 suporta os seguintes formatos de ficheiro. Consulte cada artigo para obter as configurações de acordo com o formato.

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

As seguintes propriedades têm suporte para Arquivos do Azure nas configurações de storeSettings no sumidouro de cópia baseado em formato:

Example:

"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 filtros de pastas e ficheiros

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

Exemplos de lista de ficheiros

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

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

exemplos de recursão e copyBehavior

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

Propriedades da atividade de consulta

Para obter detalhes sobre as propriedades, consulte Lookup activity.

Propriedades de atividade GetMetadata

Para saber detalhes sobre as propriedades, verifique a atividade GetMetadata

Excluir propriedades de atividade

Para saber detalhes sobre as propriedades, marque Excluir atividade

Modelos antigos

Modelo de conjunto de dados herdado

Example:

{
    "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 da atividade de cópia herdada

Example:

"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 de coletor de atividade de cópia herdado

Example:

"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 suportados como fontes e destinos na atividade de cópia, consulte Armazenamentos de dados suportados.