Asignación de esquemas y tipos de datos en la actividad de copia

SE APLICA A: Azure Data Factory Azure Synapse Analytics

En este artículo se describe cómo la actividad de copia de Azure Data Factory realiza la asignación de esquemas y la asignación de tipos de datos de los datos de origen a los datos receptores.

Mapeo de esquemas

Asignación predeterminada

Por defecto, la actividad de copia mapea los datos fuente para que se hundan por nombres de columnas de forma sensible a mayúsculas y minúsculas. Si el sumidero no existe, como al escribir en archivos, los nombres de los campos fuente se convierten en los nombres del sumidero. Si el receptor ya existe, debe contener todas las columnas que se copien del origen. Este mapeo por defecto permite esquemas flexibles y deriva del esquema desde el origen hasta el sumidero, desde la ejecución hasta la ejecución: todos los datos devueltos por el almacenamiento de datos fuente pueden copiarse al sumidero.

Si tu código fuente es un archivo de texto sin línea de cabecera, necesitas usar mapeo explícito porque la fuente no contiene nombres de columnas.

Asignación explícita

Especifica mapeo explícito para personalizar el mapeo de columnas y campos desde el origen hasta el sumidero. Al usar mapeo explícito, solo puedes copiar parte de los datos fuente al sumidero, mapear datos fuente a sumideros con diferentes nombres, o reformular datos tabulares o jerárquicos. La actividad de copias:

1. Lee los datos de la fuente y determina el esquema fuente.
2. Aplica tu mapeo definido.
3. Escribe los datos en el sumidero.

Más información sobre:

• De origen tabular a receptor tabular
• De origen jerárquico a receptor tabular
• De origen tabular/jerárquico a receptor jerárquico

Configura el mapeo en la interfaz de autoría yendo a la actividad de copiar y seleccionando la pestaña de mapeo . O bien especificar programáticamente el mapeo en la actividad de copia usando la translator propiedad. Las siguientes propiedades están soportadas en translator ->mappings array -> objetos - y sink>source , que apuntan a la columna o campo específico para mapear datos.

Se admiten las siguientes propiedades en translator además de mappings:

Origen tabular a un receptor tabular

Por ejemplo, para copiar datos de Salesforce a Azure SQL Database y asignar explícitamente tres columnas:

1. En la actividad de copia, selecciona la pestaña de mapeo y luego selecciona Importar esquemas para importar tanto el esquema de origen como el de sumidero.

2. Mapea los campos necesarios y excluye o elimina el resto.

Configura el mismo mapeo en la carga útil de actividad de copia (véase 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 datos de archivos de texto delimitados sin una línea de encabezado, representa las columnas por ordinales en lugar de nombres.

{
    "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" }
                }
            ]
        }
    },
    ...
}

Origen jerárquico a un receptor tabular

Cuando copias datos de una fuente jerárquica a un sumidero tabular, la actividad de copia soporta las siguientes capacidades:

• Extraer datos de objetos y matrices.
• Usar CROSS APPLY en varios objetos con el mismo patrón de una matriz, en cuyo caso se convierte un objeto JSON en varios registros del resultado tabular.

Para una transformación jerárquica a tabular más avanzada, utiliza Data Flow.

Por ejemplo, si tienes un documento fuente de Azure DocumentDB o MongoDB con el siguiente contenido:

{
    "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 los datos en un archivo de texto, utiliza el siguiente formato con una línea de cabecera. Aplana los datos dentro de los arrays (order_pd y order_price) y usa una unión cruzada con la información raíz común (número, fecha y ciudad):

Define esta correspondencia en la interfaz de autoría de Data Factory:

1. En la actividad de copiar, ve a la pestaña de mapeo y selecciona Importar esquemas para importar tanto el esquema de origen como el de sumidero. A medida que el servicio muestrea los pocos objetos principales al importar el esquema, si no aparece ningún campo, añádelo a la capa correcta de la jerarquía: pasa el cursor por un nombre de campo existente y elige añadir un nodo, un objeto o un array.

2. Seleccione la matriz en la que quiere iterar y extraer datos. La interfaz rellena automáticamente la referencia de la Colección. Ten en cuenta que esta operación solo soporta un único array.

3. Asigne los campos necesarios al receptor. El servicio determina automáticamente las rutas de acceso JSON correspondientes para el lado jerárquico.

También puedes cambiar a editor avanzado. Puedes ver y editar directamente las rutas JSON de los campos. Si decide agregar una nueva asignación en esta vista, especifique la ruta de acceso JSON.

Puedes configurar el mismo mapeo en la carga útil de actividad de copia (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']"
        }
    },
    ...
}

Origen tabular o jerárquico a un receptor jerárquico

El flujo de la experiencia del usuario es similar a el de Origen jerárquico a receptor tabular.

Al copiar datos de una fuente tabular a un sumidero jerárquico, el servicio no soporta escribir en un array dentro de un objeto.

Al copiar datos de una fuente jerárquica a un sumidero jerárquico, puedes preservar toda la jerarquía de una capa seleccionando el objeto o array y mapeando a sink sin tocar los campos internos.

Para una transformación de remodelación de datos más avanzada, utiliza Data Flow.

Parametrizar mapeo

Para crear una tubería templatizada que copie dinámicamente un gran número de objetos, primero determina si puedes usar el mapeo por defecto o si necesitas definir un mapeo explícito para cada objeto.

Si necesitas mapeo explícito, sigue estos pasos:

1. Definamos un parámetro con un tipo de objeto a nivel de pipeline, como mapping.

2. Parametriza el mapeo: En la actividad de copiar, ve a la pestaña de mapeo, elige añadir contenido dinámico y selecciona el parámetro que has creado. La carga útil de actividad es la siguiente:

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

3. Construir el valor que se va a pasar al parámetro de asignación. Debería ser el objetivo principal de la translator definición. Para ejemplos, véase la sección de mapeo explícito . Por ejemplo, para copiar de un origen tabular a un receptor tabular, el valor debe ser {"type":"TabularTranslator","mappings":[{"source":{"name":"Id"},"sink":{"name":"CustomerID"}},{"source":{"name":"Name"},"sink":{"name":"LastName"}},{"source":{"name":"LastModifiedDate"},"sink":{"name":"ModifiedDate"}}]}.

Asignación de tipos de datos

actividad de copia mapea los tipos fuente a los tipos de sumidero usando el siguiente flujo:

1. Convierta de tipos de datos nativos de origen a tipos de datos intermedios usados por las canalizaciones de Azure Data Factory y Synapse.
2. Convierte automáticamente el tipo de dato intermedio según sea necesario para que coincida con los tipos de sumidero correspondientes. Este paso se aplica tanto al mapeo por defecto como al mapeo explícito.
3. Conversión de tipos de datos provisionales en tipos de datos nativos de receptor.

actividad de copia admite actualmente los siguientes tipos de datos provisionales: Boolean, Byte, Byte array, Datetime, DatetimeOffset, Decimal, Double, GUID, Int16, Int32, Int64, SByte, Single, String, Timespan, UInt16, UInt32 y UInt64.

Se admiten las siguientes conversiones de tipos de datos entre los tipos provisionales desde el origen hasta el destino.

(1) Fecha/Hora incluye FechaHora, FechaTiempoDesplazamiento, Fecha y Hora.

(2) Los valores con punto flotante incluyen a Single y Double.

(3) Los valores enteros incluyen a SByte, Byte, Int16, UInt16, Int32, UInt32, Int64 y UInt64.

actividad de copia soporta las siguientes propiedades para la conversión de tipos de datos (en la translator sección de autoría programática):

| Propiedad | Descripción | Obligatorio | | -------------------------------- | ------------------------------------------------------------ | -------- | | typeConversión | Activa la nueva experiencia de conversión de tipo de datos. El valor predeterminado es false debido a la compatibilidad con versiones anteriores.

Para nuevas actividades de copia creadas a través de la interfaz de creación de Data Factory desde finales de junio de 2020, esta conversión de tipo de dato está habilitada por defecto para la mejor experiencia. Puedes ver la siguiente configuración de conversión de tipos en la pestaña de actividad> de copia - mapeo para los escenarios aplicables. Para crear una canalización mediante programación, debe establecer explícitamente la propiedad typeConversion en true para habilitarla. En el caso de las actividades de copia existentes creadas antes de la publicación de esta característica, no se ven las opciones de conversión de tipos en la interfaz de usuario de creación para la compatibilidad con versiones anteriores. | No | | tipoConversionConfiguración | Un conjunto de ajustes de conversión de tipos. Se aplica cuando typeConversion está establecido en true. Todas las propiedades siguientes se encuentran en este grupo. | No | | Bajo typeConversionSettings | | | | allowDataTruncation | Permite el truncamiento de datos al convertir datos fuente a sink con un tipo diferente durante la copia, por ejemplo, de decimal a entero, de DatetimeOffset a Datetime.
El valor predeterminado es true. | No | | treatBooleanAsNumber | Trata a los booleanos como números, por ejemplo, verdaderos como 1.
El valor predeterminado es False. | No | | fechaFormato | Formatea cadena al convertir entre fechas y cadenas, como yyyy-MM-dd. Consulte Cadenas con formato de fecha y hora personalizado para obtener información detallada. | No | | fechaTiempoFormato | Formatea cadena al convertir entre fechas sin desplazamiento de zona horaria ni cadenas, como yyyy-MM-dd HH:mm:ss.fff. Consulte Cadenas con formato de fecha y hora personalizado para obtener información detallada. | No | | fechaTiempoOffsetFormato | Formatea la cadena al convertir entre fechas con desplazamiento de zona horaria y cadenas, como yyyy-MM-dd HH:mm:ss.fff zzz. Consulte Cadenas con formato de fecha y hora personalizado para obtener información detallada. | No | | tiempoFormatoIntervalo | Formatea cadena al convertir entre periodos de tiempo y cadenas, como dd\.hh\:mm. Consulte Cadenas con formato de intervalo de tiempo personalizado para obtener información detallada. | No | | timeFormat | Formatea la cadena al convertir entre tiempo y cadenas, como HH:mm:ss.fff. Consulte Cadenas con formato de fecha y hora personalizado para obtener información detallada. | No | | Cultura | Información de cultura para usar al convertir tipos, como en-us o fr-fr. | No |

Ejemplo:

{
    "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 heredados

Asignación de columnas alternativa (modelo heredado)

Para mapear entre datos en forma de tabular, especifique copy activity -> translator -> columnMappings. En este caso, tanto los conjuntos de datos de entrada como de salida requieren la sección de estructura . El mapeo de columnas permite mapear todas o un subconjunto de columnas en la estructura del conjunto de datos fuente a todas las columnas de la estructura del conjunto de datos sumidero. Las siguientes condiciones de error resultan en una excepción:

• El resultado de la consulta del almacén de datos fuente no tiene un nombre de columna que especificaste en la sección de estructura del conjunto de datos de entrada.
• El almacenamiento de datos del sumidero (si tiene un esquema predefinido) no tiene un nombre de columna que hayas especificado en la sección de estructura del conjunto de datos de salida.
• O bien menos columnas o más columnas en la estructura del conjunto de datos sumidero de las especificadas en el mapeo.
• Asignación duplicada.

En el siguiente ejemplo, el conjunto de datos de entrada tiene una estructura y apunta a una tabla en una base de datos de Oracle local.

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

En este ejemplo, el conjunto de datos de salida tiene una estructura y apunta a una tabla en Salesforce.

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

El siguiente fragmento JSON define una actividad de copia en una canalización. Las columnas de la fuente se mapean a columnas en el sumidero usando la propiedad traductora ->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"
            }
        }
    }
}

Si usas la sintaxis "columnMappings": "UserId: MyUserId, Group: MyGroup, Name: MyName" para especificar el mapeo de columnas, sigue siendo soportada as-is.

Mapeo alternativo de esquemas (modelo heredado)

Puedes especificar actividad de copia para>translator>schemaMapping mapear entre datos con forma jerárquica y datos en forma de tabular. Por ejemplo, puedes copiar desde MongoDB o REST a un archivo de texto, y copiar de Oracle a Azure Cosmos DB para MongoDB o Azure DocumentDB (con compatibilidad con MongoDB). La sección de actividad translator de copia soporta las siguientes propiedades:

• Clave: representa la fuente. Para la fuente tabular, especifica el nombre de la columna tal y como se define en la estructura del conjunto de datos. Para el código fuente jerárquico, especifica la expresión de ruta JSON para cada campo a extraer y mapear.
• Valor: representa el susurro. Para el sumidero tabular, especifica el nombre de la columna tal como se define en la estructura del conjunto de datos. Para sumidero jerárquico, especifica la expresión de ruta JSON para cada campo a extraer y mapear. En el caso de los datos jerárquicos, para los campos en el objeto raíz, la ruta de acceso JSON comienza con root $; para los campos dentro de la matriz elegida mediante la propiedad collectionReference, la ruta de acceso JSON empieza desde el elemento de matriz. | Sí | | Colección Referencia | Si quieres iterar y extraer datos de los objetos dentro de un campo de array con el mismo patrón y convertirlos por fila por objeto, especifica la ruta JSON de ese array para hacer cross-applic. Esta propiedad solo se admite si el origen son datos jerárquicos. | No |

Ejemplo: copia de MongoDB a Oracle:

Por ejemplo, si tienes un documento de MongoDB con el siguiente contenido:

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

Y quieres copiarlo en una tabla Azure SQL en el siguiente formato aplanando los datos dentro del array (order_pd y order_price) y cruzando con la raíz común (número, fecha y ciudad):

Configura la regla de mapeo de esquemas como el siguiente ejemplo de JSON de actividad de copia:

{
    "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"
        }
    }
}

Contenido relacionado

Consulte los otros artículos sobre la Actividad de Copia:

• Información general de la actividad de copia