Mapeamento de esquema e de 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 no Azure Data Factory realiza o mapeamento de esquema e o mapeamento de tipos de dados dos dados de origem para os dados de destino.

Mapeamento de esquema

Mapeamento padrão

Por padrão, a atividade de cópia mapeia os dados de origem para serem distribuídos por nomes de colunas de forma sensível a maiúsculas e minúsculas. Se o sink não existir, como ao escrever em arquivos, os nomes dos campos de origem se tornam os nomes dos sinks. Se o coletor já existir, ele deverá conter todas as colunas que estão sendo copiadas da origem. Esse mapeamento padrão suporta esquemas flexíveis e deriva do esquema da fonte para o sink, da execução à execução – todos os dados retornados pelo armazenamento de dados de origem podem ser copiados para o sink.

Se sua fonte for um arquivo de texto sem uma linha de cabeçalho, você precisa usar mapeamento explícito porque a fonte não contém nomes de colunas.

Mapeamento explícito

Especifique mapeamento explícito para personalizar o mapeamento de colunas e campos da fonte para o sumidor. Ao usar mapeamento explícito, você pode copiar apenas parte dos dados de origem para o sumidouro, mapear dados de origem para sumidores com nomes diferentes, ou reformular dados tabulares ou hierárquicos. A atividade de cópia:

1. Lê os dados da fonte e determina o esquema fonte.
2. Aplica seu mapeamento definido.
3. Grava os dados no piso.

Saiba mais sobre:

• De origem tabular para destino tabular
• Origem hierárquica para o coletor tabular
• Origem tabular/hierárquica para o coletor hierárquico

Configure o mapeamento na interface de autoria indo até a atividade de cópia e selecionando a aba de mapeamento . Ou, especificar programaticamente o mapeamento na atividade de cópia usando a translator propriedade. As seguintes propriedades são suportadas em translator ->mappings array -> objetos - e sink>source , que apontam para a coluna ou campo específico para mapear dados.

As propriedades a seguir têm suporte em translator além de mappings:

Origem tabular para o coletor tabular

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

1. Na atividade de cópia, selecione a aba de mapeamento e depois selecione Importar esquemas para importar tanto o esquema de origem quanto o do sink.

2. Mapeie os campos necessários e exclua ou exclua o restante.

Mapear tabelas para tabelas

Configure o mesmo mapeamento no payload de atividade de cópia (veja 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 uma linha de cabeçalho, represente as colunas 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 o coletor tabular

Quando você copia dados de uma fonte hierárquica para um sumidouro tabular, a atividade de cópia suporta as seguintes capacidades:

• Extrair dados de objetos e matrizes.
• A aplicação cruzada de vários objetos com o mesmo padrão de uma matriz, nesse caso, para converter um objeto JSON em vários registros em resultado tabular.

Para transformações hierárquicas para tabulares mais avançadas, use o Fluxo de Dados.

Por exemplo, se você tem um documento fonte Azure DocumentDB ou 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" } ]
}

Para copiar os dados em um arquivo de texto, use o seguinte formato com uma linha de cabeçalho. Achatar os dados dentro dos arrays (order_pd e order_price) e usar uma junção cruzada com a informação raiz comum (número, data e cidade):

Defina esse mapeamento na interface de autoria do Data Factory:

1. Na atividade de cópia, vá na aba Mapeamento e selecione Importar esquemas para importar tanto os esquemas de origem quanto o de dissipador. À medida que o serviço amostra os poucos objetos principais ao importar o esquema, se nenhum campo aparecer, adicione-o à camada correta da hierarquia – passe o mouse sobre um nome de campo existente e escolha adicionar um nó, um objeto ou um array.

2. Selecione a matriz da qual você deseja iterar e extrair dados. A interface preenche automaticamente a referência da Coleção. Note que essa operação suporta apenas um único array.

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

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

Você pode configurar o mesmo mapeamento no payload de atividade de cópia (veja 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']"
        }
    },
    ...
}

Origem tabular/hierárquica para o coletor hierárquico

O fluxo de experiência do usuário é semelhante ao Coletor hierárquico de origem para tabular.

Ao copiar dados de uma fonte tabular para um sumidouro hierárquico, o serviço não suporta a escrita em um array dentro de um objeto.

Ao copiar dados de uma fonte hierárquica para um sumidouro hierárquico, você pode preservar toda a hierarquia de uma camada selecionando o objeto ou array e mapeando para o sink sem tocar nos campos internos.

Para transformações de reformulação de dados mais avançadas, use o Fluxo de Dados.

Parametrizar mapeamento

Para criar um pipeline templastizado que copie dinamicamente um grande número de objetos, primeiro determine se você pode usar o mapeamento padrão ou se precisa definir o mapeamento explícito para cada objeto.

Se você precisar de mapeamento explícito, siga estes passos:

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

2. Parametrize o mapeamento: Na atividade de cópia, vá até a aba de mapeamento, escolha adicionar conteúdo dinâmico e selecione o parâmetro que você criou. A carga útil da atividade é a seguinte:

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

3. Construir o valor a ser passado para o parâmetro de mapeamento. Deve ser o objetivo principal da translator definição. Para exemplos, veja a seção de mapeamento explícito . Por exemplo, para a origem tabular para a cópia de coletor 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 tipo de dados

atividade Copy mapeia tipos de fonte para tipos de submersão usando o seguinte fluxo:

1. Converter de tipos de dados nativos da fonte para tipos de dados provisórios usados pelos pipelines do Azure Data Factory e Synapse.
2. Converta automaticamente o tipo de dado intermediário conforme necessário para corresponder aos tipos de sumidouro correspondentes. Essa etapa se aplica tanto ao mapeamento padrão quanto ao mapeamento explícito.
3. Converter tipos de dados intermediários em tipos de dados nativos do sink.

atividade Copy atualmente dá suporte aos 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 têm suporte entre os tipos provisórios da origem para o coletor.

(1) Data/Hora inclui DataHora, DataTempoOffset, Data e Hora.

(2) Ponto flutuante inclui Single e Double.

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

atividade Copy suporta as seguintes propriedades para conversão de tipos de dados (na translator seção para autoria programática):

| Propriedade | Descrição | Obrigatório | | -------------------------------- | ------------------------------------------------------------ | -------- | | typeConversão | Ative a nova experiência de conversão de tipo de dados. O valor padrão é falso devido à compatibilidade retroativa.

Para novas atividades de cópia criadas pela interface de autoria do Data Factory desde o final de junho de 2020, essa conversão de tipo de dado é ativada por padrão para a melhor experiência. Você pode ver as seguintes configurações de conversão de tipos na Copy Activity -> aba de mapeamento para cenários aplicáveis. Para criar o pipeline programaticamente, você precisa definir explicitamente a typeConversion propriedade como true para habilitá-la. Para as atividades de cópia existentes criadas antes do lançamento desse recurso, você não verá opções de conversão do tipo na interface do usuário de criação para compatibilidade com versões anteriores. | Não | | typeConversionSettings | Um grupo de configurações de conversão de tipos. Use quando typeConversion estiver definido como true. As propriedades a seguir estão todas neste grupo. | Não | | Sob typeConversionSettings | | | | allowDataTruncation | Permita truncamento de dados ao converter dados de origem para sink com tipos diferentes durante a cópia, por exemplo, de decimal para inteiro, de TempoTempo Offset para Hora.
O valor padrão é true. | Não | | treatBooleanAsNumber | Trate booleanos como números, por exemplo, verdadeiros como 1.
O valor padrão é false. | Não | | dataFormato | Formate uma string ao converter entre datas e strings, como yyyy-MM-dd. Consulte Cadeias de caracteres de formato de data e hora personalizadas para obter informações detalhadas. | Não | | dataDataTempo | Formate uma string ao converter entre datas sem deslocamento de fuso horário e strings, como yyyy-MM-dd HH:mm:ss.fff. Consulte Cadeias de caracteres de formato de data e hora personalizadas para obter informações detalhadas. | Não | | dataTempoOffsetFormato | Formate a string ao converter entre datas com deslocamento de fuso horário e strings, como yyyy-MM-dd HH:mm:ss.fff zzz. Consulte Cadeias de caracteres de formato de data e hora personalizadas para obter informações detalhadas. | Não | | tempoFormatoIntervalo | Formate a string ao converter entre períodos de tempo e strings, como dd\.hh\:mm. Consulte Cadeias de caracteres de formato TimeSpan personalizadas para obter informações detalhadas. | Não | | timeFormat | Formate a cadeia ao converter entre tempo e cadeias, como HH:mm:ss.fff. Consulte Cadeias de caracteres de formato de data e hora personalizadas para obter informações detalhadas. | Não | | Cultura | Informações de cultura para usar ao converter tipos, como en-us ou fr-fr. | Não |

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 herdados

Mapeamento de coluna alternativa (modelo legado)

Para mapear entre dados em formato tabular, especifique copy activity -> translator -> columnMappings. Neste caso, tanto os conjuntos de dados de entrada quanto de saída requerem a seção de estrutura . O mapeamento de colunas suporta o mapeamento de todas ou um subconjunto de colunas na estrutura do conjunto de dados de origem para todas as colunas da estrutura do conjunto de dados de reserva. As seguintes condições de erro resultam em uma exceção:

• O resultado da consulta do armazenamento de dados de origem não tem um nome de coluna que você especificou na seção de estrutura do conjunto de dados de entrada.
• O armazenamento de dados do sink (se tiver esquema predefinido) não tem um nome de coluna que você especificou na seção de estrutura do conjunto de dados de saída.
• Ou menos colunas ou mais colunas na estrutura do conjunto de dados do sumidouro do que o especificado no mapeamento.
• Mapeamento duplicado.

No exemplo a seguir, o conjunto de dados de entrada tem uma estrutura e ele 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"
        }
    }
}

Nessa amostra, 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 fonte mapeiam para colunas em sumidouro usando a propriedade tradutor ->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ê usar a sintaxe "columnMappings": "UserId: MyUserId, Group: MyGroup, Name: MyName" para especificar o mapeamento de colunas, ainda é suportado as-is.

Mapeamento alternativo de esquemas (modelo legado)

Você pode especificar a atividade de cópia ->translator ->schemaMapping para mapear entre dados em forma hierárquica e dados em forma de taula. Por exemplo, você pode copiar do MongoDB ou REST para um arquivo de texto, e copiar do Oracle para o Azure Cosmos DB para MongoDB ou Azure DocumentDB (com compatibilidade com MongoDB). A seção de atividade translator de cópia suporta as seguintes propriedades:

• Chave: representa a fonte. Para fonte tabular, especifique o nome da coluna conforme definido na estrutura do conjunto de dados. Para fonte hierárquica, especifique a expressão de caminho JSON para cada campo a ser extraído e mapeado.
• Valor: representa o sumido. Para o sumidouro tabular, especifique o nome da coluna conforme definido na estrutura do conjunto de dados. Para sumidouro hierárquico, especifique a expressão de caminho JSON para cada campo a ser extraído e mapeado. No caso de dados hierárquicos, para campos no objeto raiz, o caminho JSON começa com a raiz $; e para campos dentro da matriz escolhidos pela propriedade collectionReference, o caminho JSON começa a partir do elemento da matriz. | Sim | | coleçãoReferência | Se você quiser iterar e extrair dados dos objetos dentro de um campo de array com o mesmo padrão e converter para por linha por objeto, especifique o caminho JSON desse array para fazer cross-application. Essa propriedade só terá suporte quando os dados hierárquicos forem a origem. | Não |

Exemplo: copiar do MongoDB para o Oracle:

Por exemplo, se você tem um documento do 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ê quer copiá-lo para uma tabela SQL do Azure no seguinte formato, achatando os dados dentro do array (order_pd e order_price) e fazendo cross join com a raiz comum (número, data e cidade):

Configure a regra de mapeamento de esquemas como o seguinte exemplo de 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údo relacionado

Consulte os outros artigos sobre atividade de cópia:

• Visão geral da atividade de cópia