Formato JSON en Azure Data Factory y Azure Synapse Analytics

Artículo
05/15/2024

SE APLICA A: Azure Data Factory Azure Synapse Analytics

Sugerencia

Pruebe Data Factory en Microsoft Fabric, una solución de análisis todo en uno para empresas. Microsoft Fabric abarca todo, desde el movimiento de datos hasta la ciencia de datos, el análisis en tiempo real, la inteligencia empresarial y los informes. ¡Obtenga más información sobre cómo iniciar una nueva evaluación gratuita!

Siga este artículo cuando quiera analizar los archivos JSON o escribir los datos en formato JSON.

El formato JSON es compatible con los conectores siguientes:

Propiedades del conjunto de datos

Si desea ver una lista completa de las secciones y propiedades disponibles para definir conjuntos de datos, consulte el artículo sobre conjuntos de datos. En esta sección se proporciona una lista de las propiedades compatibles con el conjunto de datos de JSON.

Propiedad	Descripción	Obligatorio
type	La propiedad type del conjunto de datos debe establecerse en Json.	Sí
ubicación	Configuración de ubicación de los archivos. Cada conector basado en archivos tiene su propio tipo de ubicación y propiedades compatibles en `location`. Consulte los detalles en el artículo de conectores -> sección de propiedades del conjunto de datos.	Sí
encodingName	El tipo de codificación usado para leer y escribir archivos de prueba. Estos son los valores permitidos: "UTF-8","UTF-8 sin BOM", "UTF-16", "UTF-16BE", "UTF-32", "UTF-32BE", "US-ASCII", "UTF-7", "BIG5", "EUC-JP", "EUC-KR", "GB2312", "GB18030", "JOHAB", "SHIFT-JIS", "CP875", "CP866", "IBM00858", "IBM037", "IBM273", "IBM437", "IBM500", "IBM737", "IBM775", "IBM850", "IBM852", "IBM855", "IBM857", "IBM860", "IBM861", "IBM863", "IBM864", "IBM865", "IBM869", "IBM870", "IBM01140", "IBM01141", "IBM01142", "IBM01143", "IBM01144", "IBM01145", "IBM01146", "IBM01147", "IBM01148", "IBM01149", "ISO-2022-JP", "ISO-2022-KR", "ISO-8859-1", "ISO-8859-2", "ISO-8859-3", "ISO-8859-4", "ISO-8859-5", "ISO-8859-6", "ISO-8859-7", "ISO-8859-8", "ISO-8859-9", "ISO-8859-13", "ISO-8859-15", "WINDOWS-874", "WINDOWS-1250", "WINDOWS-1251", "WINDOWS-1252", "WINDOWS-1253", "WINDOWS-1254", "WINDOWS-1255", "WINDOWS-1256", "WINDOWS-1257", "WINDOWS-1258".	No
compression	Grupo de propiedades para configurar la compresión de archivo. Configure esta sección si desea realizar la compresión o descompresión durante la ejecución de la actividad.	No
type (en `compression` )	El códec de compresión usado para leer y escribir archivos JSON. Los valores permitidos son bzip2, gzip, deflate, ZipDeflate, TarGzip, Tar, snappy o Iz4. La opción predeterminada no se comprime. Tenga en cuenta que actualmente la actividad de copia no admite "snappy" ni "lz4", y que el flujo de datos de asignación no admite "ZipDeflate", "TarGzip" ni "Tar". Tenga en cuenta que, cuando se utiliza la actividad de copia para descomprimir archivos ZipDeflate/TarGzip/Tar y escribir en el almacén de datos receptor basado en archivos, los archivos se extraen de manera predeterminada en la carpeta: `<path specified in dataset>/<folder named as source compressed file>/`. Use `preserveZipFileNameAsFolder`/`preserveCompressionFileNameAsFolder` en el origen de la actividad de copia para controlar si se debe conservar el nombre de los archivos comprimidos como una estructura de carpetas.	No.
level (en `compression` )	La razón de compresión. Los valores permitidos son Optimal o Fastest. - Fastest: la operación de compresión debe completarse tan pronto como sea posible, incluso si el archivo resultante no se comprime de forma óptima. - Optimal: la operación de compresión se debe comprimir óptimamente, incluso si tarda más tiempo en completarse. Para más información, consulte el tema Nivel de compresión .	No

A continuación, se muestra un ejemplo de un conjunto de datos de JSON en Azure Blob Storage:

{
    "name": "JSONDataset",
    "properties": {
        "type": "Json",
        "linkedServiceName": {
            "referenceName": "<Azure Blob Storage linked service name>",
            "type": "LinkedServiceReference"
        },
        "schema": [ < physical schema, optional, retrievable during authoring > ],
        "typeProperties": {
            "location": {
                "type": "AzureBlobStorageLocation",
                "container": "containername",
                "folderPath": "folder/subfolder",
            },
            "compression": {
                "type": "gzip"
            }
        }
    }
}

Propiedades de la actividad de copia

Si desea ver una lista completa de las secciones y propiedades disponibles para definir actividades, consulte el artículo sobre canalizaciones. En esta sección se proporciona una lista de las propiedades compatibles con el receptor y el origen de JSON.

Obtenga información sobre cómo extraer datos de archivos JSON y asignarlos a un formato o almacén de datos receptor, o viceversa, desde asignación de esquemas.

JSON como origen

En la sección *source* de la actividad de copia se admiten las siguientes propiedades.

Propiedad	Descripción	Obligatorio
type	La propiedad type del origen de la actividad de copia debe establecerse en: JSONSource.	Sí
formatSettings	Un grupo de propiedades. Consulte la tabla Configuración de lectura de JSON a continuación.	No
storeSettings	Un grupo de propiedades sobre cómo leer datos de un almacén de datos. Cada conector basado en archivos tiene su propia configuración de lectura admitida en `storeSettings`. Consulte los detalles en el artículo de conectores -> sección de propiedades de la actividad de copia.	No

Configuración de lectura de JSON admitida en formatSettings:

Propiedad	Descripción	Obligatorio
type	El tipo de formatSettings debe establecerse en JsonReadSettings.	Sí
compressionProperties	Un grupo de propiedades sobre cómo descomprimir datos para un códec de compresión determinado.	No
preserveZipFileNameAsFolder (en `compressionProperties`->`type` como `ZipDeflateReadSettings`)	Se aplica cuando el conjunto de datos de entrada se configura con compresión ZipDeflate. Indica si se debe conservar el nombre del archivo ZIP de origen como estructura de carpetas durante la copia. - Cuando se establece en true (valor predeterminado) , el servicio escribe los archivos descomprimidos en `<path specified in dataset>/<folder named as source zip file>/`. - Cuando se establece en false, el servicio escribe los archivos descomprimidos directamente en `<path specified in dataset>`. Asegúrese de que no tenga nombres de archivo duplicados en distintos archivos ZIP de origen para evitar comportamientos acelerados o inesperados.	No
preserveCompressionFileNameAsFolder (en `compressionProperties`->`type` como `TarGZipReadSettings` o `TarReadSettings`)	Se aplica cuando el conjunto de datos de entrada está configurado con la compresión TarGzip/Tar. Indica si se debe conservar el nombre del archivo de origen comprimido como estructura de carpetas durante la copia. - Cuando se establece en true (valor predeterminado) , el servicio escribe los archivos descomprimidos en `<path specified in dataset>/<folder named as source compressed file>/`. - Cuando se establece en false, el servicio escribe los archivos descomprimidos directamente en `<path specified in dataset>`. Asegúrese de que no haya nombres de archivo duplicados en distintos archivos de origen para evitar comportamientos acelerados o inesperados.	No

JSON como receptor

En la sección *sink* de la actividad de copia se admiten las siguientes propiedades.

Propiedad	Descripción	Obligatorio
type	La propiedad type del origen de la actividad de copia debe establecerse en JSONSink.	Sí
formatSettings	Un grupo de propiedades. Consulte la tabla Configuración de escritura de JSON a continuación.	No
storeSettings	Un grupo de propiedades sobre cómo escribir datos en un almacén de datos. Cada conector basado en archivos tiene su propia configuración de escritura admitida en `storeSettings`. Consulte los detalles en el artículo de conectores -> sección de propiedades de la actividad de copia.	No

Configuración de escritura de JSON compatible en formatSettings:

Propiedad	Descripción	Obligatorio
type	La propiedad type de formatSettings debe establecerse en JsonWriteSettings.	Sí
filePattern	Indica el patrón de los datos almacenados en cada archivo JSON. Estos son los valores permitidos: setOfObjects (líneas JSON) y arrayOfObjects. El valor predeterminado es setOfObjects. Consulte la sección patrones de archivo JSON para obtener más información acerca de estos patrones.	No

Patrones de archivo JSON

Al copiar datos de archivos JSON, dicha actividad de copia puede detectar y analizar automáticamente los siguientes patrones de los archivos JSON. Al escribir datos en archivos JSON, puede configurar el patrón de archivo en el receptor de la actividad de copia.

Tipo I: setOfObjects

Cada archivo contiene un solo objeto, líneas JSON u objetos concatenados.

ejemplo de JSON de objeto único

{
    "time": "2015-04-29T07:12:20.9100000Z",
    "callingimsi": "466920403025604",
    "callingnum1": "678948008",
    "callingnum2": "567834760",
    "switch1": "China",
    "switch2": "Germany"
}

Líneas JSON (valor predeterminado para el receptor)

{"time":"2015-04-29T07:12:20.9100000Z","callingimsi":"466920403025604","callingnum1":"678948008","callingnum2":"567834760","switch1":"China","switch2":"Germany"}
{"time":"2015-04-29T07:13:21.0220000Z","callingimsi":"466922202613463","callingnum1":"123436380","callingnum2":"789037573","switch1":"US","switch2":"UK"}
{"time":"2015-04-29T07:13:21.4370000Z","callingimsi":"466923101048691","callingnum1":"678901578","callingnum2":"345626404","switch1":"Germany","switch2":"UK"}

ejemplo de JSON concatenado

{
    "time": "2015-04-29T07:12:20.9100000Z",
    "callingimsi": "466920403025604",
    "callingnum1": "678948008",
    "callingnum2": "567834760",
    "switch1": "China",
    "switch2": "Germany"
}
{
    "time": "2015-04-29T07:13:21.0220000Z",
    "callingimsi": "466922202613463",
    "callingnum1": "123436380",
    "callingnum2": "789037573",
    "switch1": "US",
    "switch2": "UK"
}
{
    "time": "2015-04-29T07:13:21.4370000Z",
    "callingimsi": "466923101048691",
    "callingnum1": "678901578",
    "callingnum2": "345626404",
    "switch1": "Germany",
    "switch2": "UK"
}

Tipo II: arrayOfObjects

Cada archivo contiene una matriz de objetos.

[
    {
        "time": "2015-04-29T07:12:20.9100000Z",
        "callingimsi": "466920403025604",
        "callingnum1": "678948008",
        "callingnum2": "567834760",
        "switch1": "China",
        "switch2": "Germany"
    },
    {
        "time": "2015-04-29T07:13:21.0220000Z",
        "callingimsi": "466922202613463",
        "callingnum1": "123436380",
        "callingnum2": "789037573",
        "switch1": "US",
        "switch2": "UK"
    },
    {
        "time": "2015-04-29T07:13:21.4370000Z",
        "callingimsi": "466923101048691",
        "callingnum1": "678901578",
        "callingnum2": "345626404",
        "switch1": "Germany",
        "switch2": "UK"
    }
]

Propiedades de Asignación de instancias de Data Flow

En los flujos de datos de asignación, puede leer y escribir en formato JSON en los siguientes almacenes de datos: Azure Blob Storage, Azure Data Lake Storage Gen1, Azure Data Lake Storage Gen2 y SFTP y puede leer el formato JSON de Amazon S3.

Propiedades de origen

En la tabla siguiente se enumeran las propiedades que admite un origen JSON. Puede editar estas propiedades en la pestaña Source options (Opciones del origen).

Nombre	Descripción	Obligatorio	Valores permitidos	Propiedad de script de flujo de datos
Rutas de acceso comodín	Se procesarán todos los archivos que coincidan con la ruta de acceso comodín. Reemplaza a la carpeta y la ruta de acceso del archivo establecidas en el conjunto de datos.	no	String[]	wildcardPaths
Ruta de acceso raíz de la partición	En el caso de datos de archivos con particiones, puede especificar una ruta de acceso raíz de la partición para leer las carpetas con particiones como columnas.	no	String	partitionRootPath
Lista de archivos	Si el origen apunta a un archivo de texto que enumera los archivos que se van a procesar.	no	`true` o `false`	fileList
Columna para almacenar el nombre de archivo	Se crea una nueva columna con el nombre y la ruta de acceso del archivo de origen.	no	String	rowUrlColumn
Después de finalizar	Se eliminan o mueven los archivos después del procesamiento. La ruta de acceso del archivo comienza en la raíz del contenedor.	no	Borrar: `true` o `false` Mover: `['<from>', '<to>']`	purgeFiles moveFiles
Filtrar por última modificación	Elija si desea filtrar los archivos en función de cuándo se modificaron por última vez.	no	Marca de tiempo	modifiedAfter modifiedBefore
Documento único	Los flujos de datos de asignación leen un documento JSON de cada archivo.	no	`true` o `false`	singleDocument
Nombres de columnas sin comillas	Si se selecciona Nombres de columnas sin comillas, los flujos de datos de asignación leen columnas JSON que no están entre comillas.	no	`true` o `false`	unquotedColumnNames
Tiene comentarios	Seleccione Tiene comentarios si los datos JSON tienen comentarios de estilo C o C++.	no	`true` o `false`	asComments
Con comillas simples	Lee las columnas JSON que no están entrecomilladas.	no	`true` o `false`	singleQuoted
Barra diagonal inversa con escape	Seleccione Barra diagonal inversa con escape si se usan barras diagonales inversas como caracteres de escape en los datos JSON.	no	`true` o `false`	backslashEscape
No permitir que se encuentren archivos	Si es true, no se devuelve un error si no se encuentra ningún archivo.	no	`true` o `false`	ignoreNoFilesFound

Conjunto de datos insertado

Los flujos de datos de asignación admiten "conjuntos de datos insertados" como opción para definir el origen y el receptor. Un conjunto de datos JSON insertado se define directamente dentro de las transformaciones de origen y receptor y no se comparte fuera del flujo de datos definido. Resulta útil para parametrizar las propiedades del conjunto de datos directamente dentro del flujo de datos y puede beneficiarse de un rendimiento mejorado sobre los conjuntos de datos de ADF compartidos.

Al leer un gran número de carpetas y archivos de origen, puede mejorar el rendimiento de la detección de archivos de flujo de datos estableciendo la opción "Esquema proyectado por el usuario" dentro del Cuadro de diálogo Proyección | Opciones de esquema. Esta opción desactiva la detección automática de esquemas predeterminada de ADF y mejorará considerablemente el rendimiento de la detección de archivos. Antes de establecer esta opción, asegúrese de importar la proyección JSON para que ADF tenga un esquema existente para la proyección. Esta opción no funciona con el desfase de esquema.

Opciones de formato de origen

El uso de un conjunto de datos JSON como origen en el flujo de datos le permite establecer cinco opciones de configuración adicionales. Esta configuración se puede encontrar en el acordeón Configuración de JSON en la pestaña Opciones de origen. Para el valor Document Form (Formulario de documento), puede elegir entre los tipos Documento único, Document per line (Documento por línea) y Array of documents (Matriz de documentos).

Configuración de JSON

Valor predeterminado

De forma predeterminada, los datos JSON se leen en el formato siguiente.

{ "json": "record 1" }
{ "json": "record 2" }
{ "json": "record 3" }

Documento único

Si se selecciona Documento único, los flujos de datos de asignación leen un documento JSON de cada archivo.

File1.json
{
    "json": "record 1"
}
File2.json
{
    "json": "record 2"
}
File3.json
{
    "json": "record 3"
}

Si se selecciona Document per line (Documento por línea), los flujos de datos de asignación leen un documento JSON de cada línea de un archivo.

File1.json
{"json": "record 1"}

File2.json
 {"time":"2015-04-29T07:12:20.9100000Z","callingimsi":"466920403025604","callingnum1":"678948008","callingnum2":"567834760","switch1":"China","switch2":"Germany"}
 {"time":"2015-04-29T07:13:21.0220000Z","callingimsi":"466922202613463","callingnum1":"123436380","callingnum2":"789037573","switch1":"US","switch2":"UK"}

File3.json
 {"time":"2015-04-29T07:12:20.9100000Z","callingimsi":"466920403025604","callingnum1":"678948008","callingnum2":"567834760","switch1":"China","switch2":"Germany"}
 {"time":"2015-04-29T07:13:21.0220000Z","callingimsi":"466922202613463","callingnum1":"123436380","callingnum2":"789037573","switch1":"US","switch2":"UK"}
 {"time":"2015-04-29T07:13:21.4370000Z","callingimsi":"466923101048691","callingnum1":"678901578","callingnum2":"345626404","switch1":"Germany","switch2":"UK"}

Si se selecciona Array of documents (Matriz de documentos), los flujos de datos de asignación leen una matriz de documentos de un archivo.

File.json
[
        {
            "time": "2015-04-29T07:12:20.9100000Z",
            "callingimsi": "466920403025604",
            "callingnum1": "678948008",
            "callingnum2": "567834760",
            "switch1": "China",
            "switch2": "Germany"
        },
        {
            "time": "2015-04-29T07:13:21.0220000Z",
            "callingimsi": "466922202613463",
            "callingnum1": "123436380",
            "callingnum2": "789037573",
            "switch1": "US",
            "switch2": "UK"
        },
        {
            "time": "2015-04-29T07:13:21.4370000Z",
            "callingimsi": "466923101048691",
            "callingnum1": "678901578",
            "callingnum2": "345626404",
            "switch1": "Germany",
            "switch2": "UK"
        }
    ]

Nota:

Si los flujos de datos producen un error que indica "corrupt_record" al obtener una vista previa de los datos JSON, es probable que los datos contengan un único documento en el archivo JSON. Si establece la opción "Documento único", debería desaparecer ese error.

Nombres de columnas sin comillas

Si se selecciona Nombres de columnas sin comillas, los flujos de datos de asignación leen columnas JSON que no están entre comillas.

{ json: "record 1" }
{ json: "record 2" }
{ json: "record 3" }

Tiene comentarios

Seleccione Tiene comentarios si los datos JSON tienen comentarios de estilo C o C++.

{ "json": /** comment **/ "record 1" }
{ "json": "record 2" }
{ /** comment **/ "json": "record 3" }

Con comillas simples

Seleccione Con comillas simples si los valores y campos JSON usan comillas simples en lugar de comillas dobles.

{ 'json': 'record 1' }
{ 'json': 'record 2' }
{ 'json': 'record 3' }

Barra diagonal inversa con escape

Seleccione Barra diagonal inversa con escape si se usan barras diagonales inversas como caracteres de escape en los datos JSON.

{ "json": "record 1" }
{ "json": "\} \" \' \\ \n \\n record 2" }
{ "json": "record 3" }

Propiedades del receptor

En la tabla siguiente se enumeran las propiedades que admite un receptor JSON. Puede editar estas propiedades en la pestaña Configuración.

Nombre	Descripción	Obligatorio	Valores permitidos	Propiedad de script de flujo de datos
Borrar la carpeta	Si la carpeta de destino se borra antes de escribir.	no	`true` o `false`	truncate
Opción de nombre de archivo	El formato de nombre de los datos escritos. De forma predeterminada, un archivo por partición en formato `part-#####-tid-<guid>`.	no	Patrón: Cadena Por partición: Cadena[] Como datos de columna: Cadena Salida en un solo archivo: `['<fileName>']`	filePattern partitionFileNames rowUrlColumn partitionFileNames

Creación de estructuras JSON en una columna derivada

Puede agregar una columna compleja al flujo de datos mediante el generador de expresiones de columna derivada. En la transformación de columna derivada, agregue una nueva columna y abra el generador de expresiones haciendo clic en el cuadro azul. Para que una columna sea compleja, puede escribir la estructura JSON manualmente o usar la experiencia de usuario para agregar subcolumnas de forma interactiva.

Uso de la experiencia de usuario del generador de expresiones

En el panel lateral del esquema de salida, mantenga el puntero sobre una columna y haga clic en el icono de signo más. Seleccione Agregar subcolumna para convertir la columna en un tipo complejo.

Add subcolumn (Agregar subcolumna)

Puede agregar columnas y subcolumnas adicionales de la misma manera. Para cada campo no complejo, se puede agregar una expresión en el editor de expresiones a la derecha.

Agregar columna compleja

Introducción manual de la estructura JSON

Para agregar manualmente una estructura JSON, agregue una nueva columna y escriba la expresión en el editor. La expresión tiene el siguiente formato general:

@(
    field1=0,
    field2=@(
        field1=0
    )
)

Si esta expresión se especificara para una columna denominada "complexColumn", se escribiría en el receptor como el siguiente JSON:

{
    "complexColumn": {
        "field1": 0,
        "field2": {
            "field1": 0
        }
    }
}

Script manual de ejemplo para una definición jerárquica completa

@(
    title=Title,
    firstName=FirstName,
    middleName=MiddleName,
    lastName=LastName,
    suffix=Suffix,
    contactDetails=@(
        email=EmailAddress,
        phone=Phone
    ),
    address=@(
        line1=AddressLine1,
        line2=AddressLine2,
        city=City,
        state=StateProvince,
        country=CountryRegion,
        postCode=PostalCode
    ),
    ids=[
        toString(CustomerID), toString(AddressID), rowguid
    ]
)

Estos son algunos conectores y formatos comunes relacionados con el formato JSON:

Compartir a través de

Formato JSON en Azure Data Factory y Azure Synapse Analytics

Propiedades del conjunto de datos

Propiedades de la actividad de copia

JSON como origen

JSON como receptor

Patrones de archivo JSON

Propiedades de Asignación de instancias de Data Flow

Propiedades de origen

Conjunto de datos insertado

Opciones de formato de origen

Valor predeterminado

Documento único

Nombres de columnas sin comillas

Tiene comentarios

Con comillas simples

Barra diagonal inversa con escape

Propiedades del receptor

Creación de estructuras JSON en una columna derivada

Uso de la experiencia de usuario del generador de expresiones

Introducción manual de la estructura JSON

Script manual de ejemplo para una definición jerárquica completa

Comentarios

Recursos adicionales

Compartir a través de

Formato JSON en Azure Data Factory y Azure Synapse Analytics

Propiedades del conjunto de datos

Propiedades de la actividad de copia

JSON como origen

JSON como receptor

Patrones de archivo JSON

Propiedades de Asignación de instancias de Data Flow

Propiedades de origen

Conjunto de datos insertado

Opciones de formato de origen

Valor predeterminado

Documento único

Nombres de columnas sin comillas

Tiene comentarios

Con comillas simples

Barra diagonal inversa con escape

Propiedades del receptor

Creación de estructuras JSON en una columna derivada

Uso de la experiencia de usuario del generador de expresiones

Introducción manual de la estructura JSON

Script manual de ejemplo para una definición jerárquica completa

Conectores y formatos relacionados

Contenido relacionado

Comentarios

Recursos adicionales