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 realiza o mapeamento de esquemas e de tipos de dados dos dados de origem para os dados de destino.

Mapeamento de esquema

Mapeamento padrão

Por defeito, 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 sumidouro não existir, como ao escrever em ficheiros, os nomes dos campos de origem tornam-se os nomes dos sumidouros. Se o coletor já existir, ele deve conter todas as colunas que estão sendo copiadas da fonte. Este mapeamento por defeito suporta esquemas flexíveis e deriva do esquema da fonte para o sink, da execução à execução – todos os dados devolvidos pelo armazenamento de dados de origem podem ser copiados para o sink.

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

Mapeamento explícito

Especifique o mapeamento explícito para personalizar o mapeamento de colunas e campos da origem para o sumidor. Ao usar mapeamento explícito, pode copiar apenas parte dos dados de origem para o sumidouro, mapear dados de origem para sumidoiros 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 de origem.
2. Aplica o mapeamento definido.
3. Escreve os dados no lava-loiça.

Saiba mais sobre:

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

Configure o mapeamento na Interface de Autoria indo à atividade de cópia e selecionando o separador 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 a mapear dados.

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

Origem tabular para destino tabular

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

1. Na atividade de cópia, selecione o separador de mapeamento e depois selecione Importar esquemas para importar tanto os esquemas de origem como os de sumidor.

2. Mapeie os campos necessários e exclua ou elimine os restantes.

Configure o mesmo mapeamento na carga útil de atividade de cópia (ver 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 ficheiros 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 coletor tabular

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

• 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 para tabular mais avançada, utilize o Fluxo de Dados.

Por exemplo, se tiver 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 para um ficheiro 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 este mapeamento na interface de autoria do Data Factory:

1. Na atividade de cópia, vai ao separador Mapeamento e seleciona Importar esquemas para importar tanto os esquemas de origem como o do sink. À medida que o serviço amostra os poucos objetos principais ao importar o esquema, se nenhum campo aparecer, adicione-o à camada correta na hierarquia – passe o rato por um nome de campo existente e escolha adicionar um nó, um objeto ou um array.

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

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

Também podes mudar para o editor Avançado. 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

Pode configurar o mesmo mapeamento no payload de atividade de cópia (ver 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 de uma fonte tabular para um sumidouro hierárquico, o serviço não suporta a escrita para um array dentro de um objeto.

Ao copiar dados de uma fonte hierárquica para um sumidouro hierárquico, podes preservar toda a hierarquia de uma camada selecionando o objeto ou array e mapeando para o sumidouro 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 templatizado que copie dinamicamente um grande número de objetos, primeiro determine se pode usar o mapeamento padrão ou se precisa de definir um mapeamento explícito para cada objeto.

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

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

2. Parametrize o mapeamento: Na atividade de cópia, vá ao separador de mapeamento, escolha adicionar conteúdo dinâmico e selecione o parâmetro que criou. A carga útil da atividade é 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 principal da translator definição. Para exemplos, consulte a secçã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

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

1. Converter dos tipos de dados nativos de origem para os tipos de dados intermédios usados pelos pipelines Azure Data Factory e Synapse.
2. Converter automaticamente o tipo de dado intermediário conforme necessário para corresponder aos tipos de sumidouros correspondentes. Este passo aplica-se tanto ao mapeamento padrão como ao mapeamento explícito.
3. Converta tipos de dados provisórios para tipos de dados nativos de destino.

atividade Copy suporta atualmente os seguintes tipos de dados intermédios: Booleano, 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 DataHora, DataTempoOffset, Data e Hora.

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

(3) O tipo 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 secçã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, considerando a compatibilidade retroativa.

Para novas atividades de cópia criadas através da interface de autoria do Data Factory desde o final de junho de 2020, esta conversão de tipo de dado está ativada por defeito para a melhor experiência. Pode ver as seguintes definições de conversão de tipos na atividade de cópia -> separador de mapeamento para cenários aplicáveis. Para criar um pipeline programaticamente, deve definir explicitamente a propriedade typeConversion como "true" para a habilitar. Para atividades de cópia já existentes criadas antes do lançamento deste recurso, você não verá opções de conversão de tipo na interface de edição de modo a manter a compatibilidade com versões anteriores. | Não | | tipoConversãoDefinições | Um conjunto de definições de conversão de tipos. Aplique quando typeConversion estiver definido como true. As propriedades a seguir estão todas sob este grupo. | Não | | Sob typeConversionSettings | | | | allowDataTruncation | Permitir truncamento de dados ao converter dados de origem para sink com tipos diferentes durante a cópia, por exemplo, de decimal para inteiro, de DatetimeOffset para Datetime.
O valor predefinido é verdadeiro. | Não | | treatBooleanAsNumber | Trate os booleanos como números, por exemplo, verdadeiros como 1.
O valor predefinido é falso. | Não | | dataFormato | Formate uma cadeia ao converter entre datas e cadeias, 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 cadeia ao converter entre datas sem deslocamento de fuso horário e cadeias, 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 uma cadeia ao converter entre datas com deslocamento de fuso horário e cadeias de caracteres, 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 cadeia ao converter entre períodos de tempo e cadeias, como dd\.hh\:mm. Consulte Custom TimeSpan Format Strings 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ção de cultura a 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 antigos

Mapeamento alternativo de colunas (modelo herdado)

Para mapear entre dados em forma tabular, especifique copy activity -> translator -> columnMappings. Neste caso, tanto os conjuntos de dados de entrada como de saída requerem a secçã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 sink. As seguintes condições de erro resultam numa exceção:

• O resultado da consulta do armazenamento de dados de origem não tem um nome de coluna que especificaste na secção de estrutura do conjunto de dados de entrada.
• O armazenamento de dados do sink (se tiver esquema pré-definido) não tem o nome de coluna que especificaste na secçã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 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 fonte mapeiam para colunas em sink usando a propriedade do 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 usares 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)

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

• Chave: representa a fonte. Para a fonte tabular, especifique o nome da coluna conforme definido na estrutura do conjunto de dados. Para a fonte hierárquica, especifique a expressão do caminho JSON para cada campo a extrair e mapear.
• Valor: representa o sumido. Para o sumidouro tabular, especifique o nome da coluna conforme definido na estrutura do conjunto de dados. Para sumidouros hierárquicos, especifique a expressão de caminho JSON para cada campo a extrair e mapear. No caso de dados hierárquicos, para campos sob objeto raiz, o caminho JSON começa com root $; para campos dentro da matriz escolhida pela collectionReference propriedade, o caminho JSON começa a partir do elemento da matriz. | Sim | | collectionReference | Se quiseres iterar e extrair dados dos objetos dentro de um campo de array com o mesmo padrão e converter para por linha por objeto, especifica o caminho JSON desse array para fazer cross-application. Essa propriedade é suportada somente quando os dados hierárquicos são de origem. | Não |

Exemplo: cópia do MongoDB para o Oracle:

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

Configure a regra de mapeamento de esquemas como o seguinte exemplo de JSON 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údos relacionados

Veja os outros artigos da Atividade de cópia:

• Visão geral da atividade de cópia