Copiar dados do Google Cloud Storage usando o Azure Data Factory ou o Synapse Analytics

Artigo
11/16/2023

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Gorjeta

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

Este artigo descreve como copiar dados do Google Cloud Storage (GCS). Para saber mais, leia os artigos introdutórios do Azure Data Factory e do Synapse Analytics.

Capacidades suportadas

Este conector do Google Cloud Storage é compatível com os seguintes recursos:

Capacidades suportadas	IR
Atividade de cópia (fonte/-)	① ②
Mapeando o fluxo de dados (fonte/-)	①
Atividade de Pesquisa	① ②
Atividade GetMetadata	① ②
Excluir atividade	① ②

(1) Tempo de execução de integração do Azure (2) Tempo de execução de integração auto-hospedado

Especificamente, este conector do Google Cloud Storage suporta a cópia de ficheiros tal como estão ou a análise de ficheiros com os formatos de ficheiro e codecs de compressão suportados. Ele aproveita a interoperabilidade compatível com o S3 do GCS.

Pré-requisitos

É necessária a seguinte configuração na sua conta do Google Cloud Storage:

Ativar a interoperabilidade para a sua conta do Google Cloud Storage
Defina o projeto padrão que contém os dados que você deseja copiar do bucket GCS de destino.
Crie uma conta de serviço e defina os níveis corretos de permissões usando o Cloud IAM no GCP.
Gere as chaves de acesso para esta conta de serviço.

Retrieve access key for Google Cloud Storage

Permissões obrigatórias

Para copiar dados do Google Cloud Storage, certifique-se de que recebeu as seguintes permissões para operações de objetos: storage.objects.get e storage.objects.list.

Se você usar a interface do usuário para criar, será necessária permissão adicional storage.buckets.list para operações como testar a conexão com o serviço vinculado e navegar a partir da raiz. Se não quiser conceder essa permissão, você pode escolher as opções "Testar conexão com o caminho do arquivo" ou "Procurar a partir do caminho especificado" na interface do usuário.

Para obter a lista completa de funções do Google Cloud Storage e permissões associadas, consulte Funções do IAM para armazenamento em nuvem no site do Google Cloud.

Introdução

Para executar a atividade Copiar com um pipeline, você pode usar uma das seguintes ferramentas ou SDKs:

Criar um serviço vinculado ao Google Cloud Storage usando a interface do usuário

Use as etapas a seguir para criar um serviço vinculado ao Google Cloud Storage na interface do usuário do portal do Azure.

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
Pesquise no Google e selecione o conector do Google Cloud Storage (API do S3).
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 do Data Factory específicas do Google Cloud Storage.

Propriedades do serviço vinculado

As seguintes propriedades são compatíveis com os serviços vinculados do Google Cloud Storage:

Propriedade	Descrição	Necessário
tipo	A propriedade type deve ser definida como GoogleCloudStorage.	Sim
accessKeyId	ID da chave de acesso secreta. Para encontrar a chave de acesso e o segredo, consulte Pré-requisitos.	Sim
secretAccessKey	A própria chave de acesso secreta. Marque este campo como SecureString para armazená-lo com segurança ou faça referência a um segredo armazenado no Cofre de Chaves do Azure.	Sim
serviceUrl	Especifique o ponto de extremidade GCS personalizado como `https://storage.googleapis.com`.	Sim
ConecteVia	O tempo de execução de integração a ser usado para se conectar ao armazenamento de dados. Você pode usar o tempo de execução de integração do Azure ou o tempo de execução de integração auto-hospedado (se seu armazenamento de dados estiver em uma rede privada). Se essa propriedade não for especificada, o serviço usará o tempo de execução de integração padrão do Azure.	Não

Eis um exemplo:

{
    "name": "GoogleCloudStorageLinkedService",
    "properties": {
        "type": "GoogleCloudStorage",
        "typeProperties": {
            "accessKeyId": "<access key id>",
            "secretAccessKey": {
                "type": "SecureString",
                "value": "<secret access key>"
            },
            "serviceUrl": "https://storage.googleapis.com"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Propriedades do conjunto de dados

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

As seguintes propriedades são compatíveis com o Google Cloud Storage em configurações em um conjunto de dados baseado em location formato:

Propriedade	Descrição	Necessário
tipo	A propriedade type em `location` no conjunto de dados deve ser definida como GoogleCloudStorageLocation.	Sim
Nome do bucket	O nome do bucket GCS.	Sim
folderPath	O caminho para a pasta sob o bucket fornecido. Se você quiser usar um curinga para filtrar a pasta, ignore essa configuração e especifique isso nas configurações da fonte de atividade.	Não
fileName	O nome do arquivo sob o bucket e o caminho da pasta fornecidos. Se você quiser usar um curinga para filtrar os arquivos, ignore essa configuração e especifique isso nas configurações da fonte de atividade.	Não

Exemplo:

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

Propriedades da atividade Copy

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 fonte do Google Cloud Storage.

Google Cloud Storage como tipo de origem

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

As seguintes propriedades são compatíveis com o Google Cloud Storage em configurações em uma fonte de cópia baseada em storeSettings formato:

Propriedade	Descrição	Necessário
tipo	A propriedade type under `storeSettings` deve ser definida como GoogleCloudStorageReadSettings.	Sim
Localize os ficheiros a copiar:
OPÇÃO 1: caminho estático	Copie do bucket ou caminho de pasta/arquivo especificado no conjunto de dados. Se você quiser copiar todos os arquivos de um bucket ou pasta, especifique `wildcardFileName` adicionalmente como `*`.
OPÇÃO 2: Prefixo GCS - prefixo	Prefixo para o nome da chave GCS sob o bucket fornecido configurado no conjunto de dados para filtrar arquivos GCS de origem. As chaves GCS cujos nomes começam com `bucket_in_dataset/this_prefix` são selecionadas. Ele utiliza o filtro do lado do serviço do GCS, que oferece melhor desempenho do que um filtro curinga.	Não
OPÇÃO 3: curinga - wildcardFolderPath	O caminho da pasta com caracteres curinga sob o bucket fornecido configurado em um conjunto de dados para filtrar pastas de origem. Os curingas permitidos são: `*` (corresponde a zero ou mais caracteres) e `?` (corresponde a zero ou caractere único). Use `^` para escapar se o nome da pasta tiver um curinga ou esse caractere de escape dentro. Veja mais exemplos em Exemplos de filtros de pastas e ficheiros.	Não
OPÇÃO 3: curinga - wildcardFileName	O nome do arquivo com caracteres curinga sob o bucket e o caminho da pasta fornecidos (ou 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 `^` para escapar se o nome do arquivo tiver um curinga ou esse caractere de escape dentro. Veja mais exemplos em Exemplos de filtros de pastas e ficheiros.	Sim
OPÇÃO 3: uma lista de ficheiros - fileListPath	Indica para copiar um determinado conjunto de arquivos. Aponte para um arquivo de texto que inclua uma lista de arquivos que você deseja copiar, um arquivo por linha, que é o caminho relativo para o caminho configurado no conjunto de dados. Quando estiver usando 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 recursivo é definido como true e o coletor é um armazenamento baseado em arquivo, uma pasta ou subpasta vazia não é copiada ou criada no coletor. Os valores permitidos são true (padrão) e false. Esta propriedade não se aplica quando você configura `fileListPath`o .	Não
deleteFilesAfterCompletion	Indica se os arquivos binários serão excluídos do armazenamento de origem depois de serem movidos com êxito para o repositório de destino. A exclusão do arquivo é 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 armazenamento de origem. Esta 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 o tempo da última modificação for maior ou igual a `modifiedDatetimeStart` e menor que `modifiedDatetimeEnd`. A hora é aplicada ao fuso horário 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 datetime, mas `modifiedDatetimeEnd` for NULL, os arquivos cujo último atributo modificado for maior ou igual ao valor datetime serão selecionados. Quando `modifiedDatetimeEnd` tiver um valor datetime, mas `modifiedDatetimeStart` for NULL, os arquivos cujo atributo da última modificação for menor que o valor datetime serão selecionados. Esta propriedade não se aplica quando você configura `fileListPath`o .	Não
modifiedDatetimeEnd	Mesmo que acima.	Não
enablePartitionDiscovery	Para arquivos 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.	Não
partitionRootPath	Quando a descoberta de partições estiver habilitada, especifique o caminho raiz absoluto para ler pastas particionadas como colunas de dados. Se não for especificado, por padrão, - Quando você usa o caminho do arquivo no conjunto de dados ou na lista de arquivos na origem, o caminho da raiz da partição é o caminho configurado no conjunto de dados. - Quando você usa o filtro de pasta curinga, o caminho da 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ê especificar o caminho raiz da partição como "root/folder/year=2020", a atividade de cópia gerará mais duas colunas e com o valor "08" e `day` "27", respectivamente, além das colunas `month` 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 para o armazenamento de dados durante a execução da atividade. Especifique um valor somente quando quiser limitar conexões simultâneas.	Não

Exemplo:

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

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.

balde	key	recursiva	Estrutura da pasta de origem e resultado do filtro (arquivos em negrito são recuperados)
balde	`Folder/`	false	balde PastaA Ficheiro1.csv Arquivo2.json Subpasta1 Ficheiro3.csv Arquivo4.json Ficheiro5.csv OutraPastaB Ficheiro6.csv
balde	`Folder/`	verdadeiro	balde PastaA Ficheiro1.csv Arquivo2.json Subpasta1 Ficheiro3.csv Arquivo4.json Ficheiro5.csv OutraPastaB Ficheiro6.csv
balde	`Folder/.csv`	false	balde PastaA Ficheiro1.csv Arquivo2.json Subpasta1 Ficheiro3.csv Arquivo4.json Ficheiro5.csv OutraPastaB Ficheiro6.csv
balde	`Folder/.csv`	verdadeiro	balde PastaA Ficheiro1.csv Arquivo2.json Subpasta1 Ficheiro3.csv Arquivo4.json Ficheiro5.csv OutraPastaB Ficheiro6.csv

Exemplos de lista de ficheiros

Esta seção descreve o comportamento resultante do uso de um caminho de lista de arquivos na fonte de atividade Copiar.

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

Estrutura de origem da amostra	Conteúdo em FileListToCopy.txt	Configuração
balde PastaA Ficheiro1.csv Arquivo2.json Subpasta1 Ficheiro3.csv Arquivo4.json Ficheiro5.csv Metadados FileListToCopy.txt	Ficheiro1.csv Subpasta1/Ficheiro3.csv Subpasta1/Ficheiro5.csv	No conjunto de dados: - Balde: `bucket` - Caminho da pasta: `FolderA` Na fonte da atividade de cópia: - 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 uma lista de arquivos que você deseja copiar, um arquivo por linha, com o caminho relativo para o caminho configurado no conjunto de dados.

Mapeando propriedades de fluxo de dados

Ao transformar dados em fluxos de dados de mapeamento, você pode ler arquivos do Google Cloud Storage nos seguintes formatos:

As configurações específicas do formato estão localizadas na documentação desse formato. Para obter mais informações, consulte Transformação de origem no mapeamento do fluxo de dados.

Transformação da fonte

Na transformação de origem, você pode ler a partir de um contêiner, pasta ou arquivo individual no Google Cloud Storage. Use a guia Opções de origem para gerenciar como os arquivos são lidos.

Screenshot of Source options.

Caminhos curinga: o uso de um padrão curinga instruirá o serviço a percorrer cada pasta e arquivo correspondentes em uma única transformação de origem. Esta é uma maneira eficaz de processar vários arquivos dentro de um único fluxo. Adicione vários padrões de correspondência de curinga com o sinal de adição que aparece quando você passa o mouse sobre o padrão curinga existente.

No contêiner de origem, escolha uma série de arquivos que correspondam a um padrão. Somente um contêiner pode ser especificado no conjunto de dados. Portanto, o caminho curinga também deve incluir o caminho da pasta raiz.

Exemplos de curingas:

* Representa qualquer conjunto de caracteres.
** Representa o aninhamento recursivo de diretórios.
? Substitui um caractere.
[] Corresponde a um ou mais caracteres entre parênteses.
/data/sales/**/*.csv Obtém todos os arquivos .csv em /data/sales.
/data/sales/20??/**/ Obtém todos os arquivos no século 20.
/data/sales/*/*/*.csv Obtém arquivos .csv dois níveis em /data/sales.
/data/sales/2004/*/12/[XY]1?.csv Obtém todos os arquivos .csv em dezembro de 2004, começando com X ou Y prefixados por um número de dois dígitos.

Caminho da raiz da partição: Se você tiver pastas particionadas em sua fonte de arquivos com um formato (por exemplo, year=2019), poderá atribuir o nível superior dessa árvore de pastas de partição a um key=value nome de coluna no fluxo de dados do seu fluxo de dados.

Primeiro, defina um curinga para incluir todos os caminhos que são as pastas particionadas mais os arquivos folha que você deseja ler.

Screenshot of partition source file settings.

Use a configuração Caminho raiz da partição para definir qual é o nível superior da estrutura de pastas. Quando visualizar o conteúdo dos seus dados através de uma pré-visualização de dados, verá que o serviço adicionará as partições resolvidas encontradas em cada um dos seus níveis de pasta.

Screenshot of partition root path.

Lista de ficheiros: Este é um conjunto de ficheiros. Crie um arquivo de texto que inclua uma lista de arquivos de caminho relativos a serem processados. Aponte para este ficheiro de texto.

Coluna para armazenar o nome do arquivo: armazene o nome do arquivo de origem em uma coluna em seus dados. Insira um novo nome de coluna aqui para armazenar a cadeia de caracteres de nome de arquivo.

Após a conclusão: escolha não fazer nada com o arquivo de origem depois que o fluxo de dados for executado, exclua o arquivo de origem ou mova o arquivo de origem. Os caminhos para a mudança são relativos.

Para mover os arquivos de origem para outro local pós-processamento, primeiro selecione "Mover" para a operação do arquivo. Em seguida, defina o diretório "from". Se você não estiver usando nenhum curinga para seu caminho, a configuração "de" será a mesma pasta que sua pasta de origem.

Se você tiver um caminho de origem com curinga, sua sintaxe terá esta aparência:

/data/sales/20??/**/*.csv

Você pode especificar "de" como:

/data/sales

E você pode especificar "para" como:

/backup/priorSales

Nesse caso, todos os arquivos que foram originados em /data/sales são movidos para /backup/priorSales.

Nota

As operações de arquivo são executadas somente quando você inicia o fluxo de dados de uma execução de pipeline (uma depuração de pipeline ou execução de execução) que usa a atividade Executar fluxo de dados em um pipeline. As operações de arquivo não são executadas no modo de depuração de fluxo de dados.

Filtrar por última modificação: você pode filtrar quais arquivos você processa especificando um intervalo de datas de quando eles foram modificados pela última vez. Todas as datas/hora estão em UTC.

Propriedades da atividade de pesquisa

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

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

Se você estava usando um conector do Amazon S3 para copiar dados do Google Cloud Storage, ele ainda é suportado, assim como para compatibilidade com versões anteriores. Sugerimos que utilize o novo modelo mencionado anteriormente. A interface do usuário de criação mudou para gerar o novo modelo.

Para obter uma lista de armazenamentos de dados que a atividade Copiar suporta como fontes e coletores, consulte Armazenamentos de dados suportados.