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 do Azure Data Factory executa o mapeamento do esquema e o mapeamento do tipo de dados dos dados de origem para os dados do coletor.

Mapeamento de esquema

Mapeamento padrão

Por padrão, a atividade de cópia mapeia os dados de origem para coletor por nomes de coluna de maneira que diferencia maiúsculas de minúsculas. Se o coletor não existir, por exemplo, a gravação em arquivo(s), os nomes de campo de origem serão persistentes como nomes de coletor. Se o coletor já existir, ele deverá conter todas as colunas que estão sendo copiadas da origem. Esse mapeamento padrão dá suporte a esquemas flexíveis e descompasso de esquema da origem para o coletor da execução para a execução – todos os dados retornados pelo armazenamento de dados de origem podem ser copiados para o coletor.

Se sua origem for um arquivo de texto sem linha de cabeçalho, o mapeamento explícito será necessário, pois a origem 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 o coletor ou mapear dados de origem para o coletor com nomes diferentes ou remodelar dados tabular/hierárquicos. Atividade de cópia:

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

Saiba mais sobre:

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

Você pode configurar o mapeamento na interface do usuário de criação -> atividade de cópia -> guia de mapeamento ou especificar de forma programática o mapeamento na atividade de cópia ->translator propriedade. As seguintes propriedades são suportadas em translator ->mappings matriz -> objetos ->source e sink, quais pontos para a coluna/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 o banco de dados SQL do Azure e mapear explicitamente três colunas:

1. Na guia atividade de cópia -> guia de mapeamento, clique no botão Importar esquemas para importar os esquemas de origem e de coletor.

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

O mesmo mapeamento pode ser configurado como o seguinte na carga 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 arquivo(s) de texto delimitado(s) 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 o coletor tabular

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

• 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 uma transformação hierárquica para tabular mais avançada, você pode usar Fluxo de Dados.

Por exemplo, se você tiver o 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 um arquivo de texto no formato a seguir com linha de cabeçalho, ao nivelar os dados de dentro da matriz (order_pd e order_price) e fazer uma união cruzada 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 guia atividade de cópia -> guia de mapeamento, clique no botão Importar esquemas para importar os esquemas de origem e de coletor. Como o serviço toma amostras dos principais objetos ao importar o esquema, se qualquer campo não aparecer, você poderá adicioná-lo à camada correta na hierarquia – passe o cursor sobre um nome de campo existente e opte por adicionar um nó, um objeto ou uma matriz.

2. Selecione a matriz da qual você deseja iterar e extrair dados. Ela será preenchida automaticamente como Referência de coleção. Observe que há suporte apenas para uma única matriz para essa operação.

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 alternar para Editor avançado. Nesse caso, 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.

O mesmo mapeamento pode ser configurado como o seguinte na carga 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']"
        }
    },
    ...
}

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 da origem tabular para coletor hierárquico, não há suporte para gravar na matriz dentro do objeto.

Ao copiar dados da origem hierárquica para o coletor hierárquico, você também pode preservar a hierarquia inteira da camada, selecionando o objeto/matriz e mapeando para o coletor sem tocar nos campos internos.

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

Parametrizar mapeamento

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

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

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

2. Parametrizar o mapeamento: na guia atividade de cópia -> mapeamento, escolha adicionar conteúdo dinâmico e selecione o parâmetro acima. A carga da atividade seria 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 objeto inteiro de translator definição, consulte a seção exemplos na seção 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

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

1. Converter tipos de dados nativos de origem em tipos de dados provisórios usados pelos pipelines do Azure Data Factory e do Synapse.
2. Converter automaticamente o tipo de dados provisórios conforme necessário para corresponder aos tipos de coletor correspondentes, aplicáveis ao mapeamento padrão e ao mapeamento explícito.
3. Converter tipos de dados provisórios em tipos de dados nativos do coletor.

Atualmente, a atividade de cópia dá suporte aos seguintes tipos de dados provisórios: Boolean, Byte, Matriz de bytes, 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 DateTime e DateTimeOffset.

(2) Ponto flutuante inclui Single e Double.

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

As propriedades a seguir têm suporte na atividade de cópia para conversão de tipo de dados (na seção translator para a autorizaçã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 herdados

Coluna alternativa - mapeamento (modelo herdado)

Você pode especificar a atividade de cópia ->translator ->columnMappings para mapear entre dados com formato tabular. Nesse caso, a seção "structure" é necessária para os conjuntos de dados de entrada e de saída. O mapeamento de coluna dá suporte ao mapeamento de todas as colunas ou de um subconjunto de colunas na “structure” do conjunto de dados de origem para todas as colunas na “structure” do conjunto de dados do coletor. Veja a seguir 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 “structure” do conjunto de dados de entrada.
• O armazenamento de dados do coletor (se estiver com o esquema predefinido) não tem um nome de coluna especificado na seção “structure” do conjunto de dados de saída.
• Menos colunas ou mais colunas na seção "structure" do conjunto de dados do coletor 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 origem são mapeadas na origem para colunas no coletor 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ê está utilizando a sintaxe de "columnMappings": "UserId: MyUserId, Group: MyGroup, Name: MyName" para especificar o mapeamento de coluna, ainda há suporte no estado em que se encontra.

Esquema alternativo – mapeamento (modelo herdado)

Você pode especificar a atividade de cópia – >translator – >schemaMapping para mapear entre dados em formato hierárquico e dados em forma de tabela, por exemplo, copie do MongoDB/REST para o arquivo de texto e copie do Oracle para o Azure Cosmos DB for MongoDB. As propriedades a seguir têm suporte na seção translator da atividade de cópia:

Exemplo: copiar do MongoDB para o Oracle:

Por exemplo, se você tiver o 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ê deseja copiá-lo para uma tabela do Azure SQL no formato a seguir, ao nivelar os dados de dentro da matriz (order_pd e order_price) e fazer uma união cruzada com as informações de raiz comuns (número, data e cidade):

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

Consulte os outros artigos sobre atividade de cópia:

• Visão geral da atividade de cópia