Formato JSON no Azure Data Factory e no Azure Synapse Analytics

Artigo
07/17/2023

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Dica

Experimente o Data Factory no Microsoft Fabric, uma solução de análise tudo-em-um para empresas. O Microsoft Fabric abrange desde movimentação de dados até ciência de dados, análise em tempo real, business intelligence e relatórios. Saiba como iniciar uma avaliação gratuita!

Siga este artigo quando desejar analisar os arquivos JSON ou gravar os dados no formato JSON.

Há suporte para o formato JSON para os seguintes conectores:

Propriedades do conjunto de dados

Para obter uma lista completa das seções e propriedades disponíveis para definir os conjuntos de dados, confira o artigo sobre Conjuntos de Dados. Esta seção fornece uma lista das propriedades com suporte pelo conjunto de dados JSON.

Propriedade	Descrição	Obrigatório
type	A propriedade type do conjunto de dados deve ser definida como JSON.	Sim
local	Configurações de local dos arquivos. Cada conector baseado em arquivo tem seu próprio tipo de local e propriedades com suporte em `location`. Veja os detalhes na seção do artigo sobre o conector –> Propriedades do conjunto de dados.	Sim
encodingName	O tipo de codificação usado para ler/gravar arquivos de teste. Os valores permitidos são os seguintes: "UTF-8","UTF-8 without 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".	Não
compactação	Grupo de propriedades para configurar a compactação de arquivo. Configure esta seção quando desejar fazer compactação/descompactação durante a execução da atividade.	Não
type (em `compression` )	O codec de compactação utilizado para ler/gravar arquivos JSON. Os valores permitidos são bzip2, gzip, deflate, ZipDeflate, TarGzip, Tar, snappy ou lz4. O padrão é não compactado. Observação a atividade Copy atualmente não é compatível com “snappy” e “lz4”, e o fluxo de dados de mapeamento não é compatível com “ZipDeflate”, “TarGzip” e “Tar”. Observação ao usar a atividade Copy para descompactar arquivos ZipDeflate/TarGzip/Tar e gravar no armazenamento de dados de coletor baseado em arquivo, por padrão os arquivos são extraídos para a pasta:`<path specified in dataset>/<folder named as source compressed file>/`, use `preserveZipFileNameAsFolder`/`preserveCompressionFileNameAsFolder` na origem da atividade de cópia para controlar se deseja preservar o nome dos arquivos compactados como estrutura de pastas.	Não.
nível (em `compression` )	A taxa de compactação. Os valores permitidos são Ideal ou Mais rápida. - Mais rápida: a operação de compactação deve ser concluída o mais rápido possível, mesmo se o arquivo resultante não for compactado da maneira ideal. - Ideal: a operação de compactação deve ser concluída da maneira ideal, mesmo se a operação demorar mais tempo para ser concluída. Para saber mais, veja o tópico Nível de compactação .	Não

Veja abaixo um exemplo de conjunto de dados JSON no Armazenamento de blobs do Azure:

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

Propriedades da atividade de cópia

Para obter uma lista completa das seções e propriedades disponíveis para definir atividades, confia o artigo Pipelines. Esta seção fornece uma lista das propriedades com suporte pela fonte e pelo coletor JSON.

Saiba mais sobre como extrair dados de arquivos JSON e mapear para o formato/armazenamento de dado do coletor ou vice-versa a partir do mapeamento de esquema.

JSON como fonte

As propriedades a seguir têm suporte na seção de *origem* da atividade de cópia.

Propriedade	Descrição	Obrigatório
type	A propriedade type da fonte da atividade de cópia deve ser definida como JSONSource.	Sim
formatSettings	Um grupo de propriedades. Consulte a tabela de configurações de leitura JSON abaixo.	Não
storeSettings	Um grupo de propriedades sobre como ler dados de um armazenamento de dados. Cada conector baseado em arquivo tem suas próprias configurações de leitura com suporte em `storeSettings`. Veja os detalhes na seção do artigo sobre o conector –> Propriedades da atividade Copy.	Não

Configurações de leitura JSON com suporte em formatSettings:

Propriedade	Descrição	Obrigatório
type	O tipo de formatSettings deve ser definido como JsonReadSettings.	Sim
compressionProperties	Um grupo de propriedades sobre como descompactar dados para um determinado codec de compactação.	Não
preserveZipFileNameAsFolder (em `compressionProperties`->`type` como `ZipDeflateReadSettings`)	Aplica-se quando o conjunto de dados de entrada é configurado com compactação ZipDeflate. Indica se o nome do arquivo zip de origem deve ser preservado como estrutura de pastas durante a cópia. • Quando definido como verdadeiro (padrão) , o serviço grava arquivos descompactados em `<path specified in dataset>/<folder named as source zip file>/`. • Quando definido como falso, o serviço grava arquivos descompactados diretamente em `<path specified in dataset>`. Verifique se não há nomes de arquivo duplicados nos arquivos zip de origem diferentes para evitar a corrida ou comportamento inesperado.	Não
preserveCompressionFileNameAsFolder (em `compressionProperties`->`type` como `TarGZipReadSettings` ou `TarReadSettings`)	Aplica-se quando o conjunto de dados de entrada é configurado com compactação TarGzip/Tar. Indica se o nome do arquivo zip de origem deve ser preservado como estrutura de pastas durante a cópia. • Quando definido como verdadeiro (padrão) , o serviço grava arquivos descompactados em `<path specified in dataset>/<folder named as source compressed file>/`. • Quando definido como falso, o serviço grava arquivos descompactados diretamente em `<path specified in dataset>`. Verifique se não há nomes de arquivo duplicados nos arquivos de origem diferentes para evitar a corrida ou comportamento inesperado.	Não

JSON como coletor

As propriedades a seguir têm suporte na seção do *coletor* da atividade de cópia.

Propriedade	Descrição	Obrigatório
type	A propriedade type da fonte da atividade de cópia deve ser definida como JSONSink.	Sim
formatSettings	Um grupo de propriedades. Veja a tabela Configurações de gravação do JSON abaixo.	Não
storeSettings	Um grupo de propriedades sobre como gravar dados em um armazenamento de dados. Cada conector baseado em arquivo tem suas próprias configurações de gravação com suporte em `storeSettings`. Veja os detalhes na seção do artigo sobre o conector –> Propriedades da atividade Copy.	Não

Configurações de gravação do JSON compatíveis em formatSettings:

Propriedade	Descrição	Obrigatório
type	O tipo de formatSettings deve ser definido como JsonWriteSettings.	Yes
filePattern	Indique o padrão de dados armazenados em cada arquivo JSON. Os valores permitidos são: setOfObjects (JSON Lines) e arrayOfObjects. O valor padrão é setOfObjects. Veja a seção Padrões de arquivo JSON para obter detalhes sobre esses padrões.	Não

Padrões de arquivo JSON

Ao copiar dados de arquivos JSON, a atividade de cópia pode detectar e analisar automaticamente os padrões de arquivos JSON a seguir. Ao gravar dados em arquivos JSON, você pode configurar o padrão de arquivo no sink da atividade copy.

Tipo I: setOfObjects

Cada arquivo contém um objeto único, linhas JSON ou objetos concatenados.

Exemplo de JSON de objeto único

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

Linhas JSON (padrão para o coletor)

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

Exemplo 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 arquivo contém uma 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"
    }
]

Propriedades do fluxo de dados de mapeamento

Nos fluxos de dados de mapeamento, você pode fazer leituras e gravações em formato JSON nos seguintes armazenamentos de dados: Armazenamento de Blobs do Azure, Azure Data Lake Storage Gen1 e Azure Data Lake Storage Gen2 e SFTP. Além disso, você pode ler o formato JSON no Amazon S3.

Propriedades da Origem

A tabela abaixo lista as propriedades com suporte por uma fonte json. Você pode editar essas propriedades na guia Opções de origem.

Nome	Descrição	Obrigatório	Valores permitidos	Propriedade do script do Fluxo de Dados
Caminhos curinga	Todos os arquivos correspondentes ao caminho curinga serão processados. Substitui a pasta e o caminho do arquivo definido no conjunto de dados.	não	String[]	wildcardPaths
Caminho raiz da partição	Para dados de arquivo particionados, é possível inserir um caminho raiz de partição para ler pastas particionadas como colunas	não	String	partitionRootPath
Lista de arquivos	Se sua fonte estiver apontando para um arquivo de texto que lista os arquivos a serem processados	não	`true` ou `false`	fileList
Coluna para armazenar o nome do arquivo	Criar uma nova coluna com o nome e o caminho do arquivo de origem	não	String	rowUrlColumn
Após a conclusão	Exclua ou mova os arquivos após o processamento. O caminho do arquivo inicia a partir da raiz do contêiner	não	Excluir: `true` ou `false` Mover`['<from>', '<to>']`	purgeFiles moveFiles
Filtrar pela última modificação	Escolher filtrar arquivos com base na última alteração	não	Carimbo de data/hora	modifiedAfter modifiedBefore
Documento único	Os fluxos de dados de mapeamento leem um documento JSON de cada arquivo	não	`true` ou `false`	singleDocument
Nomes de coluna sem aspas	Se for selecionado Nomes de coluna sem aspas, os fluxos de dados de mapeamento lerão colunas JSON que não estejam entre aspas.	não	`true` ou `false`	unquotedColumnNames
Possui comentários	Selecione Tem comentários se os dados JSON tiverem comentários no estilo C ou C++	não	`true` ou `false`	asComments
Entre aspas simples	Lê colunas JSON que não estão entre aspas	não	`true` ou `false`	singleQuoted
Escape com barra invertida	Selecione Escape com barra invertida se forem utilizadas barras invertidas para o escape de caracteres nos dados de JSON	não	`true` ou `false`	backslashEscape
Permitir nenhum arquivo encontrado	Se for true, um erro não será gerado caso nenhum arquivo seja encontrado	não	`true` ou `false`	ignoreNoFilesFound

Conjunto de dados embutido

Os fluxos de dados de mapeamento dão suporte a "conjuntos de dados embutidos" como uma opção para definir a origem e o coletor. Um conjunto de dados JSON embutido é definido diretamente dentro de suas transformações de origem e coletor e não é compartilhado fora do fluxo de dados definido. Ele é útil para parametrizar as propriedades do conjunto de dados diretamente dentro do fluxo de dados e pode se beneficiar de um melhor desempenho em relação aos conjuntos de dados compartilhados do ADF.

Ao ler um grande número de pastas e arquivos de origem, você pode melhorar o desempenho da descoberta de arquivos de fluxo de dados definindo a opção "Esquema projetado pelo usuário" dentro da Projeção | Caixa de diálogo opções de esquema. Essa opção desativa a descoberta automática de esquema padrão do ADF e melhora muito o desempenho da descoberta de arquivos. Antes de definir essa opção, importe a projeção JSON para que o ADF tenha um esquema existente para projeção. Essa opção não funciona com descompasso de esquema.

Opções de formato de origem

O uso de um conjunto de dados JSON como origem em seu fluxo de dados permite definir cinco configurações adicionais. Essas configurações podem ser encontradas sob o acordeão Configurações JSON na guia Opções de origem. Para a configuração Formulário de documento, você pode selecionar um dos tipos: Documento único, Documento por linha e Matriz de documentos.

JSON Settings

Padrão

Por padrão, os dados JSON são lidos no formato a seguir.

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

Documento único

Se for selecionado Documento único, os fluxos de dados de mapeamento lerão um documento JSON de cada arquivo.

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

Se for selecionado Documento por linha, os fluxos de dados de mapeamento lerão um documento JSON de cada linha em um arquivo.

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

Se for selecionado Matriz de documentos, os fluxos de dados de mapeamento lerão uma matriz de documentos de um arquivo.

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

Observação

Se os fluxos de dados lançarem um erro informando "corrupt_record" ao pré-visualizar seus dados JSON, é provável que seus dados contenham um único documento no seu arquivo JSON. A configuração como "documento único" eliminará esse erro.

Nomes de coluna sem aspas

Se for selecionado Nomes de coluna sem aspas, os fluxos de dados de mapeamento lerão colunas JSON que não estejam entre aspas.

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

Possui comentários

Selecione Tem comentários se os dados JSON tiverem comentários no estilo C ou C++.

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

Entre aspas simples

Selecione Aspas simples se os campos e valores de JSON usarem aspas simples em vez de aspas duplas.

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

Escape com barra invertida

Selecione Escape com barra invertida se forem utilizadas barras invertidas para o escape de caracteres nos dados de JSON.

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

Propriedades do coletor

A tabela abaixo lista as propriedades suportadas por um coletor json. Você pode editar essas propriedades na guia Configurações.

Nome	Descrição	Obrigatório	Valores permitidos	Propriedade do script do Fluxo de Dados
Limpe a pasta	Se a pasta de destino for limpa antes da gravação	não	`true` ou `false`	truncate
Opção do nome do arquivo	O formato de nomenclatura dos dados gravados. Por padrão, um arquivo por partição no formato `part-#####-tid-<guid>`	não	Padrão: cadeia de caracteres Por partição: cadeia de caracteres [] Como dados na coluna: cadeia de caracteres Saída para arquivo único: `['<fileName>']`	filePattern partitionFileNames rowUrlColumn partitionFileNames

Criar estruturas JSON em uma coluna derivada

Você pode adicionar uma coluna complexa ao fluxo de dados por meio do construtor de expressões de coluna derivada. Na transformação de coluna derivada, adicione uma nova coluna e abra o construtor de expressões, clicando na caixa azul. Para tornar uma coluna complexa, você pode inserir a estrutura de JSON manualmente ou usar a UX para adicionar subcolunas interativamente.

Usando a UX do construtor de expressões

No painel lateral do esquema de saída, passe o mouse sobre uma coluna e clique no ícone de mais. Selecione Adicionar subcoluna para transformar a coluna num tipo complexo.

Add subcolumn

Você pode adicionar colunas e subcolunas adicionais da mesma maneira. Para cada campo não complexo, pode ser adicionada uma expressão no editor de expressão à direita.

Add complex column

Inserir a estrutura JSON manualmente

Para adicionar uma estrutura JSON manualmente, adicione uma nova coluna e insira a expressão no editor. A expressão segue o seguinte formato geral:

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

Se essa expressão fosse inserida para uma coluna chamada "complexColumn", ela seria gravada no coletor como o seguinte JSON:

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

Exemplo de script manual para definição hierá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
    ]
)

Aqui estão alguns conectores e formatos comuns relacionados ao formato JSON:

Armazenamento de Blobs do Azure (connector-azure-blob-storage.md)
Formato de texto delimitado (format-delimited-text.md)
Conector OData (conector-odata.md)
Formato Parquet (format-parquet.md)