Trabalhar com JSON no Power Fx

O Power Fx permite que os criadores leiam o JSON em um Objeto sem tipo usando a função ParseJSON.

Ler e converter valores

ParseJSON converterá a seguinte cadeia de caracteres de registro JSON em um Objeto sem tipo com os campos ItemName, Quantity, ReleaseDate e AvailableForPreOrder.

{
  "ItemName" : "Widget 1",
  "Quantity" : 46,
  "ReleaseDate" : "2022-09-01",
  "AvailableForPreOrder" : true
}

Cada um dos campos pode ser acessado usando a notação de ponto no valor de Objeto sem tipo retornado de ParseJSON.

Set( untyped, ParseJSON( jsonStringVariable ) );

Set( item, Text ( untyped.ItemName ) );
Set( quantity, Value ( untyped.Quantity ) );
Set( release, DateValue ( untyped.ReleaseDate ) );
Set( preorder, Boolean ( untyped.AvailableForPreOrder ) );

Geralmente, é uma boa ideia converter explicitamente o valor de um objeto sem tipo em um tipo específico. Definir um objeto sem tipo como um valor de variável torna a variável um Objeto sem tipo também. Portanto, é provável que seja necessário converter esse valor explicitamente ao definir como uma variável. Mas, na maioria dos casos, os valores de objeto sem tipo serão convertidos em um tipo específico automaticamente ("forçar") quando usados como parâmetros de função em que o tipo for um tipo simples, como booliano, número ou texto, e o perfil de parâmetro da função não tiver sobrecargas potencialmente conflitantes.

Left( untyped.ItemName, 1 ); // "W"
Radians( untyped.Quantity ); // 0.80285146
If (untyped.AvailableForPreOrder, "Available", "Not Available" ); // "Available"

Além de converter automaticamente o tipo em chamadas de função, os objetos sem tipo também serão convertidos quando atribuídos a propriedades de controle, sempre que possível.

Label1.Text: untyped.Quantity
InputText1.Default: untyped.ItemName

E por fim, ao usar operadores como & ou +, um Objeto sem tipo será forçado se não houver nenhuma ambiguidade no tipo esperado.

untyped.Quantity + 1 // result is a number
untyped.ItemName & " (preorder)" // result is text
untyped.Quantity + untyped.Quantity // result is a number
untyped.Quantity & untyped.ItemName // result is text

Observação

O JSON não tem um tipo GUID, Cor, Hora ou DateTime. Esses valores são representados como uma cadeia de caracteres. Se você atribuir um valor de objeto sem tipo do JSON contendo uma data para uma propriedade de texto diretamente, o texto original do JSON será usado. Isso pode ser importante ao lidar com fusos horários, formatos de data, etc. Nesses casos, você deve converter explicitamente os valores usando GUID(), ColorValue(), DateValue(), DateTimeValue(), etc

Caso um nome de campo consista em um nome de identificador inválido, por exemplo, quando os nomes dos campos começam com um número ou contêm caracteres inválidos, como um hífen, você pode colocar os nomes dos campos entre aspas simples:

untyped.'01'
untyped.'my-field'

O Power Fx não avaliará a existência do campo até que a fórmula seja executada. Isso permite flexibilidade no JSON de entrada. Por exemplo, o JSON anterior às vezes pode conter um campo extra chamado Discount. Mas em nosso exemplo anterior, esse campo não está presente. Escrever uma fórmula que use o campo Discount não resultará em nenhum erro durante o processo de criação do aplicativo ou quando os usuários utilizarem o aplicativo. Se o campo estiver ausente quando a fórmula for executada, o valor resultará apenas em um valor Blank().

Nota

O JSON oferece suporte a valores null para campos. Esses também resultarão em valores Blank(). Atualmente, não há distinção no Power Fx entre um campo ausente ou um campo que tem o valor null.

Como o acesso a campos em Objetos sem tipo não é avaliado ao escrever a fórmula, também não há Intellisense disponível. O JSON e o Power Fx diferenciam maiúsculas de minúsculas, portanto, tome cuidado extra ao escrever os nomes dos campos.

Os valores de JSON não precisam estar em uma notação de estilo de registro. Um JSON válido pode ser apenas um valor, como "text value", true ou 123.456. Nesse caso, o Objeto sem tipo que ParseJSON retorna é o próprio valor e a notação de ponto não é usada.

Set( myText, Boolean( ParseJSON( "true" ) ) );

Set( myNumber, Value( ParseJSON( "123.456" ) ) );

Por fim, o JSON oferece suporte a registros aninhados. Converter esse JSON em Objeto sem tipo resulta em objetos aninhados e a notação de ponto pode ser usada para percorrer a hierarquia.

{
  "Version" : 1,
  "RootElement" : {
    "Parent" : {
      "Name" : "This is the parent",
      "Child" : {
        "Name" : "This is the child"
      }
    }
  }
}

Ao converter essa cadeia de caracteres JSON em uma variável de Objeto sem tipo denominada jsonObject, os campos poderão ser acessados usando a notação de ponto.

Set( jsonObject, ParseJSON( jsonStringVariable ) );

Set( parentName, Text( jsonObject.RootElement.Parent.Name ) ); // "This is the parent"

Set( childName, Text( jsonObject.RootElement.Parent.Child.Name ) ); // "This is the child"

Se algum dos campos na expressão da notação de ponto não existir, Blank() será retornado.

Matrizes e tabelas

O JSON pode conter matrizes de valores ou registros. Essas matrizes podem ser acessadas diretamente ou convertidas em tabelas do Power Fx.

{
  "OrderNumber" : "SO000010",
  "CustomerID" : "CUST0126",
  "OrderLines" : [
    {
      "Item" : "Widget 1",
      "Quantity" : 3
    },
    {
      "Item" : "Widget 2",
      "Quantity" : 5
    }
  ]
}

Esse JSON contém um registro com um campo chamado OrderLines que contém uma matriz de registros. Cada registro possui dois campos: Item e Quantity. Se o JSON for convertido em um Objeto sem tipo usando a função ParseJSON e definido como uma variável chamada jsonOrder, poderemos acessar as linhas da ordem individuais de várias maneiras.

Set( jsonOrder, ParseJSON( jsonStringVariable ) );

Você pode recuperar registros e valores individuais usando a função Index(). Por exemplo, para obter o segundo registro no campo OrderLines e, em seguida, acessar o campo Quantity e convertê-lo em um valor.

Set( line2Quantity, Value( Index( jsonOrder.OrderLines, 2 ).Quantity ); // 5

Você pode converter a matriz de linhas da ordem diretamente em uma tabela. Isso criará uma tabela de coluna única com um Objeto sem tipo representando o registro.

Set( orderLines, Table( jsonOrder.OrderLines ) );

A tabela de coluna única 'orderLines' agora tem uma coluna 'Value' que representa o Objeto sem tipo. Para usar qualquer um dos campos de um registro nesta tabela, use a notação de ponto para acessar o campo JSON específico no Objeto sem tipo na coluna Value.

Set( jsonRecord, Index( orderLines, 2 ) ); // Get the second record in the table

Set( line2Item, Text( jsonRecord.Value.Item ) ); // "Widget 2"

Para tornar o uso dos registros de linha da ordem mais fácil e direto em outras partes do seu aplicativo, você pode converter todo o Objeto sem tipo em um registro totalmente classificado usando a função ForAll(). Fornecer o Objeto sem tipo diretamente para a função ForAll() significa que você pode acessar os campos de objeto diretamente em vez de usar o campo de coluna únicaValue.

Set( typedOrderLines, ForAll( jsonOrder.OrderLines, { Item : Text( ThisRecord.Item ), Quantity : Value( ThisRecord.Quantity ) } ) );

A nova variável typedOrderLines agora é uma tabela do Power Fx totalmente classificada com as seguintes colunas e valores:

Item	Quantidade
"Widget 1"	3
"Widget 2"	5

Os exemplos anteriores usam matrizes de registros, mas o JSON também pode conter matrizes de apenas valores. Considere o seguinte exemplo que é uma cadeia de caracteres JSON válida contendo uma matriz de três cadeias de caracteres.

[ "First Item", "Second Item", "Third Item"]

Podemos recuperar um dos itens da matriz usando a função Index() e convertê-lo em texto.

Text( Index( ParseJSON( jsonStringVariable ), 2 ) ) // "Second Item"