Mapeamento de esquema e tipo de dados na atividade de cópia

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Este artigo descreve como a atividade de cópia do Azure Data Factory executa o mapeamento de esquema e o mapeamento de tipos de dados desde os dados de origem até os dados de destino.

Mapeamento de esquema

Mapeamento padrão

Por padrão, a atividade de cópia mapeia os dados de origem para o destino por nomes de coluna de forma sensível a maiúsculas e minúsculas. Se o destino não existir, por exemplo, ao gravar em ficheiro(s), os nomes dos campos de origem serão mantidos como nomes de destino. Se o coletor já existir, ele deve conter todas as colunas que estão sendo copiadas da fonte. Esse mapeamento padrão suporta esquemas flexíveis e desvio de esquema da origem para o destino ao longo das execuções - todos os dados retornados pelo armazenamento de dados de origem podem ser copiados para o destino.

Se a fonte for um arquivo de texto sem linha de cabeçalho, o mapeamento explícito será necessário, pois a fonte não contém nomes de coluna.

Mapeamento explícito

Você também pode especificar o mapeamento explícito para personalizar o mapeamento de coluna/campo da origem para o coletor com base em sua necessidade. Com o mapeamento explícito, você pode copiar apenas dados de origem parciais para coletor, mapear dados de origem para coletor com nomes diferentes ou remodelar dados tabulares/hierárquicos. Atividade de cópia:

1. Lê os dados da origem e determina o esquema de origem.
2. Aplica o mapeamento definido.
3. Grava os dados no coletor.

Saiba mais sobre:

• Origem tabular para destino tabular
• Origem hierárquica para coletor tabular
• Fonte tabular/hierárquica para coletor hierárquico

Você pode configurar o mapeamento na tabulação de mapeamento da Authoring UI -> copy activity ->, ou especificar programaticamente o mapeamento na propriedade da copy activity ->translator. As propriedades a seguir são suportadas em translator ->mappings array -> objects ->source e sink, que aponta para a coluna/campo específico para mapear dados.

As seguintes propriedades são suportadas em translator , além de mappings:

Origem tabular para destino tabular

Por exemplo, para copiar dados do Salesforce para o Banco de Dados SQL do Azure e mapear explicitamente três colunas:

1. Na aba de mapeamento da Atividade de cópia ->, clique no botão Importar esquemas para importar esquemas tanto de origem quanto de destino.

2. Mapeie os campos necessários e exclua o resto.

O mesmo mapeamento pode ser configurado como o seguinte na carga útil da atividade de cópia (consulte translator):

{
    "name": "CopyActivityTabularToTabular",
    "type": "Copy",
    "typeProperties": {
        "source": { "type": "SalesforceSource" },
        "sink": { "type": "SqlSink" },
        "translator": {
            "type": "TabularTranslator",
            "mappings": [
                {
                    "source": { "name": "Id" },
                    "sink": { "name": "CustomerID" }
                },
                {
                    "source": { "name": "Name" },
                    "sink": { "name": "LastName" }
                },
                {
                    "source": { "name": "LastModifiedDate" },
                    "sink": { "name": "ModifiedDate" }
                }
            ]
        }
    },
    ...
}

Para copiar dados de arquivos de texto delimitados sem linha de cabeçalho, as colunas são representadas por ordinal em vez de nomes.

{
    "name": "CopyActivityTabularToTabular",
    "type": "Copy",
    "typeProperties": {
        "source": { "type": "DelimitedTextSource" },
        "sink": { "type": "SqlSink" },
        "translator": {
            "type": "TabularTranslator",
            "mappings": [
                {
                    "source": { "ordinal": "1" },
                    "sink": { "name": "CustomerID" }
                }, 
                {
                    "source": { "ordinal": "2" },
                    "sink": { "name": "LastName" }
                }, 
                {
                    "source": { "ordinal": "3" },
                    "sink": { "name": "ModifiedDate" }
                }
            ]
        }
    },
    ...
}

Origem hierárquica para coletor tabular

Ao copiar dados da origem hierárquica para o coletor tabular, a atividade de cópia oferece suporte aos seguintes recursos:

• Extraia dados de objetos e matrizes.
• Aplicar cruzadamente múltiplos objetos com o mesmo padrão a partir de um array, no caso de converter um objeto JSON em vários registos no resultado tabular.

Para uma transformação hierárquica em tabular mais avançada, você pode usar o Fluxo de Dados.

Por exemplo, se você tiver um documento MongoDB de origem com o seguinte conteúdo:

{
    "id": {
        "$oid": "592e07800000000000000000"
    },
    "number": "01",
    "date": "20170122",
    "orders": [
        {
            "prod": "p1",
            "price": 23
        },
        {
            "prod": "p2",
            "price": 13
        },
        {
            "prod": "p3",
            "price": 231
        }
    ],
    "city": [ { "name": "Seattle" } ]
}

E você deseja copiá-lo para um arquivo de texto no seguinte formato com linha de cabeçalho, nivelando os dados dentro da matriz (order_pd e order_price) e cruzando com as informações de raiz comuns (número, data e cidade):

Você pode definir esse mapeamento na interface do usuário de criação do Data Factory:

1. Na aba Atividade de cópia -> mapeamento, clique no botão Importar esquemas para importar esquemas de origem e de destino. À medida que o serviço obtém amostras dos principais objetos ao importar o esquema, se algum campo não aparecer, você poderá adicioná-lo à camada correta na hierarquia - passe o mouse sobre um nome de campo existente e escolha adicionar um nó, um objeto ou uma matriz.

2. Selecione a matriz da qual deseja iterar e extrair dados. Ele será preenchido automaticamente como referência de coleção. Observe que apenas uma única matriz é suportada para essa operação.

3. Mapeie os campos necessários para afundar. O serviço determina automaticamente os caminhos JSON correspondentes para o lado hierárquico.

Você também pode alternar para o editor Avançado, caso em que você pode ver e editar diretamente os caminhos JSON dos campos. Se você optar por adicionar um novo mapeamento nessa exibição, especifique o caminho JSON.

Converter estrutura hierárquica em tabular usando editor avançado

O mesmo mapeamento pode ser configurado da seguinte forma na carga útil da atividade de cópia (consulte translator):

{
    "name": "CopyActivityHierarchicalToTabular",
    "type": "Copy",
    "typeProperties": {
        "source": { "type": "MongoDbV2Source" },
        "sink": { "type": "DelimitedTextSink" },
        "translator": {
            "type": "TabularTranslator",
            "mappings": [
                {
                    "source": { "path": "$['number']" },
                    "sink": { "name": "orderNumber" }
                },
                {
                    "source": { "path": "$['date']" },
                    "sink": { "name": "orderDate" }
                },
                {
                    "source": { "path": "['prod']" },
                    "sink": { "name": "order_pd" }
                },
                {
                    "source": { "path": "['price']" },
                    "sink": { "name": "order_price" }
                },
                {
                    "source": { "path": "$['city'][0]['name']" },
                    "sink": { "name": "city" }
                }
            ],
            "collectionReference": "$['orders']"
        }
    },
    ...
}

Fonte tabular/hierárquica para coletor hierárquico

O fluxo da experiência do utilizador é semelhante à origem hierárquica para destino tabular.

Ao copiar dados da fonte tabular para o coletor hierárquico, não há suporte para gravação na matriz dentro do objeto.

Ao copiar dados da fonte hierárquica para o destino hierárquico, você também pode preservar toda a hierarquia da camada, selecionando o objeto/array e mapeando para o destino sem alterar os campos internos.

Para uma transformação de remodelação de dados mais avançada, você pode usar o Fluxo de Dados.

Parametrizar mapeamento

Se quiser criar um pipeline templatizado para copiar dinamicamente um grande número de objetos, determine se pode aproveitar o mapeamento padrão ou se precisa definir o mapeamento explícito para os respetivos objetos.

Se o mapeamento explícito for necessário, você pode:

1. Defina um parâmetro com o tipo de objeto no nível do pipeline, por exemplo, mapping.

2. Parametrizar o mapeamento: na guia copiar atividade -> mapeamento, escolha adicionar conteúdo dinâmico e selecione o parâmetro acima. A carga útil da atividade seria a seguinte:

   {
       "name": "CopyActivityHierarchicalToTabular",
       "type": "Copy",
       "typeProperties": {
           "source": {...},
           "sink": {...},
           "translator": {
               "value": "@pipeline().parameters.mapping",
               "type": "Expression"
           },
           ...
       }
   }
   

3. Construa o valor a ser passado para o parâmetro de mapeamento. Deve ser o objeto inteiro da definição de translator, consulte os exemplos na seção de mapeamento explícito. Por exemplo, para cópia de fonte tabular para destino tabular, o valor deve ser {"type":"TabularTranslator","mappings":[{"source":{"name":"Id"},"sink":{"name":"CustomerID"}},{"source":{"name":"Name"},"sink":{"name":"LastName"}},{"source":{"name":"LastModifiedDate"},"sink":{"name":"ModifiedDate"}}]}.

Mapeamento de tipos de dados

A atividade de cópia executa o mapeamento de tipos de origem para tipos de destino com o seguinte fluxo:

1. Converta de tipos de dados nativos de origem para tipos de dados provisórios usados pelos pipelines do Azure Data Factory e Synapse.
2. Converta automaticamente o tipo de dados intermediário conforme necessário para corresponder aos tipos de destino correspondentes, aplicável tanto para mapeamento padrão como para mapeamento explícito.
3. Converta tipos de dados provisórios para tipos de dados nativos de destino.

Atualmente, a atividade de cópia suporta os seguintes tipos de dados provisórios: Boolean, Byte, Byte array, Datetime, DatetimeOffset, Decimal, Double, GUID, Int16, Int32, Int64, SByte, Single, String, Timespan, UInt16, UInt32 e UInt64.

As conversões de tipo de dados a seguir são suportadas entre os tipos provisórios da origem para o destino.

(1) Data/Hora inclui DateTime, DateTimeOffset, Date e Time.

(2) Ponto flutuante inclui "Single" e "Double".

(3) O tipo Inteiro inclui SByte, Byte, Int16, UInt16, Int32, UInt32, Int64 e UInt64.

As seguintes propriedades são suportadas na atividade de cópia para conversão de tipo de dados (na translator seção para criação programática):

Exemplo:

{
    "name": "CopyActivity",
    "type": "Copy",
    "typeProperties": {
        "source": {
        	"type": "ParquetSource"
        },
        "sink": {
            "type": "SqlSink"
        },
        "translator": {
            "type": "TabularTranslator",
            "typeConversion": true,
            "typeConversionSettings": {
                "allowDataTruncation": true,
                "treatBooleanAsNumber": true,
                "dateTimeFormat": "yyyy-MM-dd HH:mm:ss.fff",
                "dateTimeOffsetFormat": "yyyy-MM-dd HH:mm:ss.fff zzz",
                "timeSpanFormat": "dd\.hh\:mm",
                "culture": "en-gb"
            }
        }
	},
    ...
}

Modelos antigos

Mapeamento alternativo de colunas (modelo herdado)

Você pode especificar a atividade de cópia ->translator ->columnMappings para mapear entre dados em forma de tabela. Neste caso, a seção "estrutura" é necessária para conjuntos de dados de entrada e saída. O mapeamento de colunas suporta o mapeamento de todas ou subconjuntos de colunas na "estrutura" do conjunto de dados de origem para todas as colunas na "estrutura" do conjunto de dados de destino. A seguir estão as condições de erro que resultam em uma exceção:

• O resultado da consulta do armazenamento de dados de origem não tem um nome de coluna especificado na seção "estrutura" do conjunto de dados de entrada.
• O armazenamento de dados do coletor (se estiver com esquema predefinido) não tem um nome de coluna especificado na seção "estrutura" do conjunto de dados de saída.
• Existem menos ou mais colunas na "estrutura" do conjunto de dados de destino do que as especificadas no mapeamento.
• Mapeamento duplicado.

No exemplo a seguir, o conjunto de dados de entrada tem uma estrutura e aponta para uma tabela em um banco de dados Oracle local.

{
    "name": "OracleDataset",
    "properties": {
        "structure":
         [
            { "name": "UserId"},
            { "name": "Name"},
            { "name": "Group"}
         ],
        "type": "OracleTable",
        "linkedServiceName": {
            "referenceName": "OracleLinkedService",
            "type": "LinkedServiceReference"
        },
        "typeProperties": {
            "tableName": "SourceTable"
        }
    }
}

Neste exemplo, o conjunto de dados de saída tem uma estrutura e aponta para uma tabela no Salesforce.

{
    "name": "SalesforceDataset",
    "properties": {
        "structure":
        [
            { "name": "MyUserId"},
            { "name": "MyName" },
            { "name": "MyGroup"}
        ],
        "type": "SalesforceObject",
        "linkedServiceName": {
            "referenceName": "SalesforceLinkedService",
            "type": "LinkedServiceReference"
        },
        "typeProperties": {
            "tableName": "SinkTable"
        }
    }
}

O JSON a seguir define uma atividade de cópia em um pipeline. As colunas da origem mapeadas para colunas no coletor usando a propriedade translator ->columnMappings .

{
    "name": "CopyActivity",
    "type": "Copy",
    "inputs": [
        {
            "referenceName": "OracleDataset",
            "type": "DatasetReference"
        }
    ],
    "outputs": [
        {
            "referenceName": "SalesforceDataset",
            "type": "DatasetReference"
        }
    ],
    "typeProperties":    {
        "source": { "type": "OracleSource" },
        "sink": { "type": "SalesforceSink" },
        "translator":
        {
            "type": "TabularTranslator",
            "columnMappings":
            {
                "UserId": "MyUserId",
                "Group": "MyGroup",
                "Name": "MyName"
            }
        }
    }
}

Se você estiver usando a sintaxe de para especificar o mapeamento de coluna, ela ainda será suportada "columnMappings": "UserId: MyUserId, Group: MyGroup, Name: MyName" no estado em que se encontra.

Mapeamento de esquema alternativo (modelo herdado)

Você pode especificar a atividade de cópia ->translator ->schemaMapping para mapear entre dados em forma hierárquica e dados em forma de tabela, por exemplo, copiar do MongoDB/REST para o arquivo de texto e copiar do Oracle para o Azure Cosmos DB para MongoDB. As seguintes propriedades são suportadas na seção de atividade translator de cópia:

Exemplo: cópia do MongoDB para o Oracle:

Por exemplo, se você tiver um documento MongoDB com o seguinte conteúdo:

{
    "id": {
        "$oid": "592e07800000000000000000"
    },
    "number": "01",
    "date": "20170122",
    "orders": [
        {
            "prod": "p1",
            "price": 23
        },
        {
            "prod": "p2",
            "price": 13
        },
        {
            "prod": "p3",
            "price": 231
        }
    ],
    "city": [ { "name": "Seattle" } ]
}

e você deseja copiá-lo para uma tabela SQL do Azure no seguinte formato, nivelando os dados dentro da matriz (order_pd e order_price) e realizando um cruzamento com as informações comuns de raiz (número, data e cidade):

Configure a regra de mapeamento de esquema utilizando o seguinte exemplo JSON de uma atividade de cópia.

{
    "name": "CopyFromMongoDBToOracle",
    "type": "Copy",
    "typeProperties": {
        "source": {
            "type": "MongoDbV2Source"
        },
        "sink": {
            "type": "OracleSink"
        },
        "translator": {
            "type": "TabularTranslator",
            "schemaMapping": {
                "$.number": "orderNumber",
                "$.date": "orderDate",
                "prod": "order_pd",
                "price": "order_price",
                "$.city[0].name": "city"
            },
            "collectionReference":  "$.orders"
        }
    }
}

Conteúdos relacionados

Veja os outros artigos da Atividade de cópia:

• Copiar visão geral da atividade