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.

Asignación de esquemas

Asignación predeterminada

De forma predeterminada, la actividad de copia asigna los datos de origen al receptor por nombres de columna con distinción de mayúsculas y minúsculas. Si el receptor no existe, por ejemplo, al escribir en los archivos, los nombres de los campos de origen se conservarán como nombres de receptor. Si el receptor ya existe, debe contener todas las columnas que se copien del origen. Esta asignación predeterminada admite esquemas flexibles y derivación de esquemas del origen al receptor de una ejecución a otra: todos los datos devueltos por el almacén de datos de origen se pueden copiar en el receptor.

Si el origen es un archivo de texto sin línea de encabezado, se requiere una asignación explícita, ya que el origen no contiene nombres de columna.

Asignación explícita

También puede especificar una asignación explícita para personalizar la asignación de columnas o campos del origen al receptor según sus necesidades. Con la asignación explícita, solo puede copiar parcialmente los datos de origen en el receptor o asignar los datos de origen al receptor con nombres diferentes, o incluso volver a conformar los datos tabulares y jerárquicos. Actividad de copia:

1. Lee los datos desde el origen y determina el esquema de origen.
2. Aplica la asignación definida.
3. Escribe los datos en el receptor.

Más información sobre:

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

Puede configurar la asignación en la interfaz de usuario de creación -> actividad de copia -> pestaña Asignación, o bien especificar mediante programación la asignación en la actividad de copia -> propiedad translator. Las siguientes propiedades se admiten en translator ->matriz mappings -> objetos ->source y sink, que apuntan a la columna o campo específico para asignar 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 pestaña actividad de copia -> asignación, haga clic en el botón Importar esquemas para importar los esquemas de origen y de receptor.

2. Asigne los campos necesarios y excluya o elimine los demás.

La misma asignación se puede configurar de la siguiente forma en la carga de la actividad de copia (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 datos de los archivos de texto delimitados sin una línea de encabezado, las columnas se representan mediante el índice, en lugar de los 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

Al copiar datos de un origen jerárquico a un receptor tabular, la actividad de copia admite las siguientes funcionalidades:

• 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 de datos jerárquicos a tabulares más avanzada, puede usar Data Flow.

Por ejemplo, si tiene un documento de origen 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 quiere copiarlo en un archivo de texto del formato siguiente con línea de encabezado, puede hacerlo mediante el acoplamiento de los datos dentro de la matriz (order_pd y order_price) y la combinación cruzada con la información raíz en común (número, fecha y ciudad) :

Puede definir dicha asignación en la interfaz de usuario de creación de Data Factory:

1. En la pestaña actividad de copia -> asignación, haga clic en el botón Importar esquemas para importar los esquemas de origen y de receptor. Ya que el servicio muestrea los objetos más importantes al importar el esquema, si no aparece algún campo, puede agregarlo a la capa correcta de la jerarquía; para ello, mantenga el puntero sobre un nombre de campo existente y elija la opción de agregar un nodo, un objeto o una matriz.

2. Seleccione la matriz en la que quiere iterar y extraer datos. Se cumplimentará automáticamente como una referencia de colecciones. Nota: Solo se admite una matriz única para esta operación.

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 puede cambiar al Editor avanzado, en cuyo caso puede ver y editar directamente las rutas de acceso JSON de los campos. Si decide agregar una nueva asignación en esta vista, especifique la ruta de acceso JSON.

La misma asignación se puede configurar de la siguiente forma en la carga de la actividad de copia (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']"
        }
    },
    ...
}

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 del origen tabular al receptor jerárquico, no se admite la escritura en una matriz dentro del objeto.

Al copiar datos de un origen jerárquico a un receptor jerárquico, también puede conservar la jerarquía de todo un nivel si selecciona el objeto o la matriz y lo asigna al receptor sin modificar los campos internos.

Para una transformación de conformación de datos más avanzada, puede usar Data Flow.

Parametrización de asignaciones

Si quiere crear una canalización en plantilla para copiar dinámicamente un gran número de objetos, determine si puede aprovechar la asignación predeterminada o si necesita definir una asignación explícita para los objetos respectivos.

Si se necesita una asignación explícita, puede:

1. Definir un parámetro con un tipo de objeto en el nivel de canalización; por ejemplo, mapping.

2. Parametrizar la asignación: en la actividad de copia -> pestaña Asignación, elija agregar contenido dinámico y seleccione el parámetro anterior. La carga de la actividad tendría un aspecto como el 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. Debe ser el objeto completo de la definición de translator; consulte los ejemplos de la sección asignación explícita. 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

La actividad de copia realiza la asignación de tipos de origen a tipos de receptores con el siguiente flujo:

1. Conversión de tipos de datos nativos de origen en tipos de datos provisionales usados por canalizaciones de Azure Data Factory y Synapse.
2. Convierta automáticamente el tipo de datos provisional según sea necesario para que coincida con los tipos de receptor correspondientes; se aplica para la asignación predeterminada y la asignación explícita.
3. Conversión de tipos de datos provisionales en tipos de datos nativos de receptor.

La actividad de copia actualmente admite los siguientes tipos de datos provisionales: booleano, byte, matriz de bytes, DateTime, DatetimeOffset, decimal, double, GUID, Int16, Int32, Int64, SByte, single, cadena, intervalo de tiempo, UInt16, UInt32, and UInt64.

Se admiten las siguientes conversiones de tipos de datos entre los tipos provisionales de origen a receptor.

(1) Los valores de fecha y hora incluyen a DateTime y DateTimeOffset.

(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.

Las siguientes propiedades son compatibles con la actividad de copia para la conversión de tipos de datos (en la sección translator para la creación mediante programación):

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)

Puede especificar actividad de copia ->translator ->columnMappings para realizar asignaciones de datos en forma tabular. En este caso, la sección "structure" es necesaria tanto para los conjuntos de datos de entrada como para los de salida. La asignación de columnas admite la asignación de todas las columnas o un subconjunto de ellas del conjunto de datos de origen "structure" a todas las columnas del conjunto de datos receptor "structure" . Las siguientes son las condiciones de error que tienen como resultado una excepción:

• El resultado de la consulta del almacén de datos de origen no tiene un nombre de columna que se especifique en la sección "structure" del conjunto de datos de entrada.
• El almacén de datos receptor (si está en el esquema predefinido) no tiene un nombre de columna que se especifique en la sección "structure" del conjunto de datos de salida.
• O bien menos columnas o más columnas en "structure" del conjunto de datos receptor de las que se especifican en la asignación.
• 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 del origen se asignan a columnas del receptor mediante la propiedad 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"
            }
        }
    }
}

Si estaba usando la sintaxis de "columnMappings": "UserId: MyUserId, Group: MyGroup, Name: MyName" para especificar una asignación de columnas, esta se sigue admitiendo tal cual.

Asignación de esquemas alternativa (modelo heredado)

Puede especificar actividad de copia ->translator ->schemaMapping para realizar la asignación de tablas de datos jerárquicos y datos tabulares. Por ejemplo, al copiar de MongoDB o REST a un archivo de texto, y al copiar de Oracle a Azure Cosmos DB for MongoDB. Se admiten las siguientes propiedades en la sección translator de la actividad de copia:

Ejemplo: copia de MongoDB a Oracle:

Por ejemplo, si tiene 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 desea copiarlo en una tabla de Azure SQL del formato siguiente, puede hacerlo mediante el acoplamiento de los datos dentro de la matriz (order_pd y order_price) y la combinación cruzada con la información de la raíz habitual (número, fecha y ciudad) :

Configure la regla de asignación de esquemas como el siguiente ejemplo 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 de la actividad de copia:

• Información general de la actividad de copia