Função JSON

Artigo
05/06/2024

Aplica-se a: Aplicativos de tela Aplicativos baseados em modelo

Gera uma cadeia de caracteres de texto JSON para uma tabela, um registro ou um valor.

Descrição

A função JSON retorna a representação JavaScript Object Notation (JSON) de uma estrutura de dados como texto, para que seja adequada para armazenar ou transmitir através de uma rede. [ECMA-404](https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf e IETF RFC 8259 descrevem o formato, que é muito usado por JavaScript e outras linguagens de programação.

Os aplicativos de tela suportam os tipos de dados que esta tabela lista com detalhes sobre sua representação de texto:

Tipo de dados	Descrição	Exemplo de resultado
Booleano	true ou false.	`true`
Cor	Cadeia de caracteres que contém a representação hexadecimal de 8 dígitos para a cor. Essa representação assume o formato #rrggbbaa, onde rr é o componente vermelho, gg é verde, bb é azul e aa é o canal alfa. Para o canal alfa, 00 é totalmente transparente e ff é totalmente opaco. Você pode passar a cadeia de caracteres para a função ColorValue.	`"#102030ff"`
Moeda	Número que usa o separador decimal apropriado para o idioma do usuário. A notação científica é usada, se necessário.	`1.345`
Data	Cadeia de caracteres que contém a data no formato aaaa-mm-dd ISO 8601.	`"2019-03-31"`
DateTime	Cadeia de caracteres que contém uma data/hora ISO 8601. Os valores de data/hora estão em UTC, como indica o "Z" final.	`"2019-03-31T22:32:06.822Z"`
GUID	Cadeira de caracteres que contém o valor GUID. As letras são minúsculas.	`"751b58ac-380e-4a04-a925-9f375995cc40"`
Imagem, Mídia	Se JSONFormat.IncludeBinaryData for especificado, os arquivos de mídia serão codificados em uma cadeia de caracteres. As referências da Web que usam o esquema de URL http: ou https: não são modificadas. As referências a dados binários na memória são codificadas com o formato "data:mimetype;base64,...". Os dados na memória incluem imagens que os usuários capturam usando o controle Camera e outras referências com os esquemas appres: e blob: URL.	`"data:image/jpeg;base64,/9j/4AA..."`
Número:	Número que usa o separador decimal apropriado para o idioma do usuário. A notação científica é usada, se necessário.	`1.345`
Conjunto de opções	Valor numérico da opção, não o rótulo usado para exibição. O valor numérico é usado porque é independente do idioma.	`1001`
Hora	Cadeia de caracteres que contém um formato hh:mm:ss.fff ISO 8601.	`"23:12:49.000"`
Registro	Lista delimitada por vírgula, entre { e }, de campos e seus valores. Essa notação se assemelha à dos registros nos aplicativos de tela, mas o nome está sempre entre aspas duplas. Este formato não suporta registros baseados em relacionamentos muitos para um.	`{ "First Name": "Fred", "Age": 21 }`
Table	Lista delimitada por vírgula, entre [e], de registros. Este formato não suporta tabelas baseadas em relacionamentos um para muitos. Use a opção JSONFormat.FlattenValueTables para remover o registro das tabelas de coluna única com a coluna chamada Valor.	`[ { "First Name": "Fred", "Age": 21 }, { "First Name": "Jean", "Age": 20 } ]`
Two option	Valor booleano das duas opções, true ou false, não o rótulo usado para exibição. O valor booliano é usado porque é independente do idioma.	`false`
Hiperlink, Texto	Cadeia de caracteres entre aspas duplas. A função escapa das marcas de aspas duplas incorporadas com uma barra invertida, substitui novas linhas por "\n" e faz outras substituições padrão do JavaScript.	`"This is a string."`

Especifique o controle Format opcional para controlar o quão legível é o resultado e como os tipos de dados binários e não suportados são tratados. Por padrão, a saída é o mais compacta possível, sem espaços desnecessários ou novas linhas, e tipos de dados não suportados e dados binários não são permitidos. Você pode combinar vários formatos se especificar o operador &.

Enumeração JSONFormat	Description
JSONFormat.Compact	Padrão. A saída é o mais compacta possível, sem espaços adicionais ou novas linhas.
JSONFormat.FlattenValueTables	Como uma tabela Valor, a notação `[1,2,3]` acarreta uma tabela contendo registros nos quais cada registro tem uma única coluna Valor. Em JSON, essa mesma notação representa uma matriz de três números. Para facilitar a interoperabilidade entre os dois, essa opção nivela uma tabela Valor do Power Fx com uma matriz JSON amigável, em vez de uma matriz de registros.
JSONFormat.IndentFour	Para melhorar a legibilidade, a saída contém uma nova linha para cada coluna e nível de aninhamento e usa quatro espaços para cada nível de indentação.
JSONFormat.IncludeBinaryData	O resultado inclui colunas de imagem, vídeo e clipe de áudio. Esse formato pode aumentar drasticamente o tamanho do resultado e prejudicar o desempenho do seu aplicativo.
JSONFormat.IgnoreBinaryData	O resultado não inclui colunas de imagem, vídeo ou clipe de áudio. Se você não especificar JSONFormat.IncludeBinaryData nem JSONFormat.IgnoreBinaryData, a função produz um erro se encontrar dados binários.
JSONFormat.IgnoreUnsupportedTypes	Tipos de dados não suportados são permitidos, mas o resultado não os incluirá. Por padrão, os tipos de dados não suportados produzem um erro.

Use as funções ShowColumns e DropColumns para controlar quais dados o resultado inclui e remover tipos de dados não suportados.

Como JSON pode ser intensivo em memória e computação, você pode usar esta função apenas em funções comportamentais. Você pode capturar o resultado de JSON dentro da variável, que você pode usar no fluxo de dados.

Se uma coluna tiver um nome para exibição e um nome lógico, o resultado conterá o nome lógico. Os nomes de exibição refletem o idioma do usuário do aplicativo e, portanto, são inadequados para a transferência de dados de um serviço comum.

Sintaxe

JSON( DataStructure [, Format ] )

DataStructure - obrigatório. A estrutura de dados a ser convertida em JSON. Tabelas, registros e valores primitivos são suportados, aninhados arbitrariamente.
Format - opcional. Valor de enumeração JSONFormat. O valor padrão é JSONFormat.Compact, que não adiciona novas linhas ou espaços e bloqueia dados binários e colunas não suportadas.

Exemplos

Dados hierárquicos

Insira um controle Button e defina sua propriedade OnSelect para esta fórmula.

ClearCollect( CityPopulations,
    { City: "London",    Country: "United Kingdom", Population: 8615000 },
    { City: "Berlin",    Country: "Germany",        Population: 3562000 },
    { City: "Madrid",    Country: "Spain",          Population: 3165000 },
    { City: "Hamburg",   Country: "Germany",        Population: 1760000 },
    { City: "Barcelona", Country: "Spain",          Population: 1602000 },
    { City: "Munich",    Country: "Germany",        Population: 1494000 }
);
ClearCollect( CitiesByCountry, GroupBy( CityPopulations, "Country", "Cities" ) )

Selecione o botão enquanto mantém pressionado a tecla Alt.

A coleção CitiesByCountry é criada com essa estrutura de dados, que você pode mostrar selecionando Coleções no menu Arquivo e, em seguida, selecionando o nome da coleção.

Você também pode mostrar esta coleção selecionando Configurações>Recursos futuros>Habilitar exibição de resultados da barra de fórmulas, selecionando o nome da coleção na barra de fórmulas e, em seguida, selecionando a seta para baixo ao lado do nome da coleção na barra de fórmulas.
Insira outro botão, e defina sua propriedade OnSelect para esta fórmula:
```
Set( CitiesByCountryJSON, JSON( CitiesByCountry ) )
```
Esta fórmula define a variável global CitiesByCountryJSON para a representação JSON para CitiesByCountry.
Selecione o botão enquanto mantém pressionado a tecla Alt.

Insira um controle Label e defina a propriedade Text com essa variável.

CitiesByCountryJSON

O rótulo mostra esse resultado, tudo em uma única linha sem espaços, adequado para transmissão em uma rede:

[
  {
    "Cities": [{ "City": "London", "Population": 8615000 }],
    "Country": "United Kingdom"
  },
  {
    "Cities": [
      { "City": "Berlin", "Population": 3562000 },
      { "City": "Hamburg", "Population": 1760000 },
      { "City": "Munich", "Population": 1494000 }
    ],
    "Country": "Germany"
  },
  {
    "Cities": [
      { "City": "Madrid", "Population": 3165000 },
      { "City": "Barcelona", "Population": 1602000 }
    ],
    "Country": "Spain"
  }
]

Altere a fórmula do segundo botão para tornar a saída mais legível.

Set( CitiesByCountryJSON, JSON(CitiesByCountry, JSONFormat.IndentFour ))

Selecione o segundo botão enquanto mantém pressionado a tecla Alt.

O rótulo mostra o resultado mais legível.

[
  {
    "Cities": [
      {
        "City": "London",
        "Population": 8615000
      }
    ],
    "Country": "United Kingdom"
  },
  {
    "Cities": [
      {
        "City": "Berlin",
        "Population": 3562000
      },
      {
        "City": "Hamburg",
        "Population": 1760000
      },
      {
        "City": "Munich",
        "Population": 1494000
      }
    ],
    "Country": "Germany"
  },
  {
    "Cities": [
      {
        "City": "Madrid",
        "Population": 3165000
      },
      {
        "City": "Barcelona",
        "Population": 1602000
      }
    ],
    "Country": "Spain"
  }
]

Imagens e mídia em base64

Adicione um controle Image.

Esse controle traz SampleImage com isso.
Adicione um controle Button e defina sua propriedade OnSelect para esta fórmula.
```
Set( ImageJSON, JSON( SampleImage, JSONFormat.IncludeBinaryData ) )
```
Selecione o botão enquanto mantém pressionado a tecla Alt.
Adicione um rótulo e defina sua propriedade Text como esta variável.
```
ImageJSON
```

Redimensione o controle e reduza o tamanho da fonte conforme necessário para mostrar a maior parte do resultado.

O rótulo mostra a sequência de texto que a função JSON capturou.

"data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4NCjxzdmcgdmVyc2lvbj0iMS4xIg0KCSB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiB4bWxuczphPSJodHRwOi8vbnMuYWRvYmUuY29tL0Fkb2JlU1ZHVmlld2VyRXh0ZW5zaW9ucy8zLjAvIg0KCSB4PSIwcHgiIHk9IjBweCIgd2lkdGg9IjI3MHB4IiBoZWlnaHQ9IjI3MHB4IiBlbmFibGUtYmFja2dyb3VuZD0ibmV3IDAgMCAyNzAgMjcwIiB4bWw6c3BhY2U9InByZXNlcnZlIj4NCgk8ZyBjbGFzcz0ic3QwIj4NCgkJPHJlY3QgeT0iMC43IiBmaWxsPSIjRTlFOUU5IiB3aWR0aD0iMjY5IiBoZWlnaHQ9IjI2OS4zIi8+DQoJCTxwb2x5Z29uIGZpbGw9IiNDQkNCQ0EiIHBvaW50cz0iMjc3LjksMTg3LjEgMjQ1LDE0My40IDE4OC42LDIwMi44IDc1LDgwLjUgLTQuMSwxNjUuMyAtNC4xLDI3MiAyNzcuOSwyNzIiLz4NCgkJPGVsbGlwc2UgZmlsbD0iI0NCQ0JDQSIgY3g9IjIwMi40IiBjeT0iODQuMSIgcng9IjI0LjQiIHJ5PSIyNC4zIi8+DQoJPC9nPg0KPC9zdmc+"

Tabelas de valores

Esta fórmula:

JSON( [1,2,3] )

produz a cadeia de caracteres de texto [{"Valor":1},{"Valor":2},{"Valor":3}].

A mesma fórmula com a opção JSONFormat.FlattenValueTables:

JSON( [1,2,3], JSONFormat.FlattenValueTables )

produz a cadeia de caracteres de texto [1,2,3].

A opção FlattenValueTables não tem impacto durante o uso de JSON com as coleções CityPopulations ou CitiesByCountry porque essas tabelas não são tabelas Valor. Uma tabela Valor tem uma única coluna e deve ser chamada de "Valor".

Compartilhar via