Mapeamento de esquema e tipo de dados na atividade de cópia
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 a atividade de cópia do Azure Data Factory executa o mapeamento de esquema e o mapeamento de tipo de dados de origem para dados de coletor.
Mapeamento de esquema
Mapeamento padrão
Por padrão, copie os dados de origem dos mapas de atividade para o coletor por nomes de coluna de maneira que diferencie maiúsculas de minúsculas. Se o coletor não existir, por exemplo, gravando no(s) arquivo(s), os nomes dos campos de origem serão mantidos como nomes de coletores. 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 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 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:
- Lê os dados da origem e determina o esquema de origem.
- Aplica o mapeamento definido.
- Grava os dados no coletor.
Saiba mais sobre:
- Origem tabular para coletor tabular
- Origem hierárquica para coletor tabular
- Fonte tabular/hierárquica para coletor hierárquico
Você pode configurar o mapeamento na guia Authoring UI -> copy activity -> mapping ou especificar programaticamente o mapeamento na propriedade 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.
| Property | Descrição | Obrigatório |
|---|---|---|
| nome | Nome da coluna/campo de origem ou coletor. Solicite a fonte tabular e o coletor. | Sim |
| Ordinal | Índice da coluna. Comece a partir de 1. Aplicar e obrigatório ao usar texto delimitado sem linha de cabeçalho. |
Não |
| path | Expressão de caminho JSON para cada campo a ser extraído ou mapeado. Aplique para fonte hierárquica e coletor, por exemplo, conectores Azure Cosmos DB, MongoDB ou REST. Para campos sob o 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 array sem $. |
Não |
| tipo | Tipo de dados provisórios da coluna de origem ou coletor. Em geral, não é necessário especificar ou alterar essa propriedade. Saiba mais sobre o mapeamento de tipo de dados. | Não |
| cultura | Cultura da fonte ou coluna do lavatório. Aplique quando o tipo for Datetime ou Datetimeoffset. A predefinição é en-us.Em geral, não é necessário especificar ou alterar essa propriedade. Saiba mais sobre o mapeamento de tipo de dados. |
Não |
| format | Formatar cadeia de caracteres a ser usada quando o tipo é Datetime ou Datetimeoffset. Consulte Custom Date and Time Format Strings sobre como formatar datetime. Em geral, não é necessário especificar ou alterar essa propriedade. Saiba mais sobre o mapeamento de tipo de dados. |
Não |
As seguintes propriedades são suportadas em translator , além de mappings:
| Property | Descrição | Obrigatório |
|---|---|---|
| collectionReference | Aplique ao copiar dados de uma fonte hierárquica, como conectores Azure Cosmos DB, MongoDB ou REST. Se você quiser iterar e extrair dados dos objetos dentro de um campo de matriz com o mesmo padrão e converter para por linha por objeto, especifique o caminho JSON dessa matriz para fazer aplicação cruzada. |
Não |
Origem tabular para coletor tabular
Por exemplo, para copiar dados do Salesforce para o Banco de Dados SQL do Azure e mapear explicitamente três colunas:
Na guia Atividade de cópia -> mapeamento, clique no botão Importar esquemas para importar esquemas de origem e coletores.
Mapeie os campos necessários e exclua/exclua o restante.
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.
- Aplicação cruzada de vários objetos com o mesmo padrão de uma matriz, caso em que para converter um objeto JSON em vários registros 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):
| Número da encomenda | orderDate | order_pd | order_price | cidade |
|---|---|---|---|---|
| 01 | 20170122 | P1 | 23 | Porto |
| 01 | 20170122 | P2 | 13 | Porto |
| 01 | 20170122 | P3 | 231 | Porto |
Você pode definir esse mapeamento na interface do usuário de criação do Data Factory:
Na guia Atividade de cópia -> mapeamento, clique no botão Importar esquemas para importar esquemas de origem e coletores. À 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.
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.
Mapeie os campos necessários para afundar. O serviço determina automaticamente os caminhos JSON correspondentes para o lado hierárquico.
Nota
Para registros em que a matriz marcada como referência de coleção está vazia e a caixa de seleção está marcada, o registro inteiro é ignorado.
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.
O mesmo mapeamento pode ser configurado como o seguinte 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 usuário é semelhante à origem hierárquica ao coletor 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 coletor hierárquico, você também pode preservar toda a hierarquia da camada, selecionando o objeto/matriz e o mapa para dissipar sem tocar nos campos internos.
Para uma transformação de remodelação de dados mais avançada, você pode usar o Fluxo de Dados.
Parametrizar mapeamento
Se você quiser criar um pipeline templatizado 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 respetivos objetos.
Se o mapeamento explícito for necessário, você pode:
Defina um parâmetro com o tipo de objeto no nível do pipeline, por exemplo,
mapping.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" }, ... } }Construa o valor a ser passado para o parâmetro de mapeamento. Deve ser todo o objeto de
translatordefinição, consulte os exemplos na seção de mapeamento explícito. Por exemplo, para fonte tabular para 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 tipos de dados
A atividade de cópia executa tipos de origem para tipos de coletor mapeando com o seguinte fluxo:
- Converta de tipos de dados nativos de origem para tipos de dados provisórios usados pelos pipelines do Azure Data Factory e Synapse.
- Converta automaticamente o tipo de dados provisório conforme necessário para corresponder aos tipos de coletor correspondentes, aplicáveis tanto para mapeamento padrão quanto para mapeamento explícito.
- Converta de tipos de dados provisórios para tipos de dados nativos coletores.
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 coletor.
| Fonte\Sink | Boolean | Matriz de bytes | Data/Hora | Decimal | Ponto de flutuação | GUID | Número inteiro | String | TimeSpan |
|---|---|---|---|---|---|---|---|---|---|
| Boolean | ✓ | ✓ | ✓ | ✓ | |||||
| Matriz de bytes | ✓ | ✓ | |||||||
| Data/Hora | ✓ | ✓ | |||||||
| Decimal | ✓ | ✓ | ✓ | ✓ | |||||
| Ponto de flutuação | ✓ | ✓ | ✓ | ✓ | |||||
| GUID | ✓ | ✓ | |||||||
| Número inteiro | ✓ | ✓ | ✓ | ✓ | |||||
| String | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |
| TimeSpan | ✓ | ✓ |
(1) Data/Hora inclui DateTime e DateTimeOffset.
(2) O ponto flutuante inclui Single e Double.
(3) Inteiro inclui SByte, Byte, Int16, UInt16, Int32, UInt32, Int64 e UInt64.
Nota
- Atualmente, essa conversão de tipo de dados é suportada ao copiar entre dados tabulares. Não há suporte para fontes/coletores hierárquicos, o que significa que não há conversão de tipo de dados definido pelo sistema entre os tipos provisórios de origem e coletor.
- Este recurso funciona com o modelo de conjunto de dados mais recente. Se você não vir essa opção na interface do usuário, tente criar um novo conjunto de dados.
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):
| Property | Descrição | Obrigatório |
|---|---|---|
| tipoConversão | Habilite a nova experiência de conversão de tipo de dados. O valor padrão é false devido à compatibilidade com versões anteriores. Para novas atividades de cópia criadas por meio da interface do usuário de criação do Data Factory desde o final de junho de 2020, essa conversão de tipo de dados é habilitada por padrão para a melhor experiência, e você pode ver as seguintes configurações de conversão de tipo na guia Atividade de cópia -> mapeamento para cenários aplicáveis. Para criar pipeline programaticamente, você precisa definir typeConversion explicitamente a propriedade como true para habilitá-la.Para atividades de cópia existentes criadas antes do lançamento desse recurso, você não verá opções de conversão de 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 tipo. Aplique quando typeConversion estiver definido como true. As propriedades a seguir estão todas sob este grupo. |
Não |
Em typeConversionSettings |
||
| allowDataTruncation | Permita o truncamento de dados ao converter dados de origem em coletor com tipo diferente durante a cópia, por exemplo, de decimal para inteiro, de DatetimeOffset para Datetime. O valor predefinido é verdadeiro. |
Não |
| tratarBooleanAsNumber | Trate booleanos como números, por exemplo, verdadeiros como 1. O valor predefinido é falso. |
Não |
| dateTimeFormat | Formatar cadeia de caracteres ao converter entre datas sem deslocamento de fuso horário e cadeias de caracteres, por exemplo, 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 |
| dateTimeOffsetFormat | Formatar cadeia de caracteres ao converter entre datas com deslocamento de fuso horário e cadeias de caracteres, por exemplo, 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 |
| timeSpanFormat | Formatar cadeia de caracteres ao converter entre períodos de tempo e cadeias de caracteres, por exemplo, dd\.hh\:mm. Consulte Custom TimeSpan Format Strings para obter informações detalhadas. |
Não |
| cultura | Informações de cultura a serem usadas ao converter tipos, por exemplo, 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
Nota
Os modelos a seguir para mapear colunas/campos de origem para coletor ainda são suportados, assim como para compatibilidade com versões anteriores. Sugerimos que você use o novo modelo mencionado no mapeamento de esquema. A interface do usuário de criação mudou para gerar o novo modelo.
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 do coletor. 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.
- Menos colunas ou mais colunas na "estrutura" 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 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:
| Property | Descrição | Obrigatório |
|---|---|---|
| tipo | A propriedade type do tradutor de atividade de cópia deve ser definida como: TabularTranslator | Sim |
| schemaMapping | Uma coleção de pares chave-valor, que representa a relação de mapeamento do lado da origem para o lado do coletor. - 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 a pia. Para coletor tabular, especifique o nome da coluna conforme definido na estrutura do conjunto de dados; para coletor 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 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 você quiser iterar e extrair dados dos objetos dentro de um campo de matriz com o mesmo padrão e converter para por linha por objeto, especifique o caminho JSON dessa matriz para fazer aplicação cruzada. 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 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 cruzando com as informações de raiz comuns (número, data e cidade):
| Número da encomenda | orderDate | order_pd | order_price | cidade |
|---|---|---|---|---|
| 01 | 20170122 | P1 | 23 | Porto |
| 01 | 20170122 | P2 | 13 | Porto |
| 01 | 20170122 | P3 | 231 | Porto |
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údos relacionados
Veja os outros artigos da Atividade de cópia: