Trabalhar com JSON no Power Fx

Power Fx permite que os fabricantes leiam JSON em um valor dinâmico usando a função ParseJSON .

Ler e converter valores

O ParseJSON converterá a seguinte cadeia de caracteres de registro JSON em um registro dinâmico com campos ItemName, QuantityReleaseDate 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 Dynamic retornado de ParseJSON.

Set( dynvalue, ParseJSON( jsonStringVariable ) );

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

Geralmente, é uma boa ideia converter explicitamente um valor dinâmico em um tipo específico. Definir uma dinâmica como um valor variável torna a variável um valor dinâmico também. Assim, é provável que seja necessário converter esse valor explicitamente ao definir para uma variável. Mas, na maioria dos casos, os valores dinâmicos serão convertidos para um tipo específico automaticamente ("coerção") quando usados como parâmetros de função, onde o tipo é um tipo simples como booleano, número ou texto, e o perfil de parâmetro da função não tem sobrecargas conflitantes potenciais.

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

Além de converter automaticamente o tipo em chamadas de função, os valores dinâmicos também serão convertidos quando atribuídos às propriedades de controle, sempre que possível.

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

E, finalmente, ao usar operadores como & ou +, um valor dinâmico será coagido se não houver ambiguidade no tipo esperado.

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

Caso um nome de campo seja composto por um nome de identificador inválido, por exemplo, quando os nomes de campo começam por um número ou contêm carateres inválidos, como um hífen, pode colocar os nomes de campo entre plicas:

dynamic.'01'
dynamic.'my-field'

O Power Fx não avaliará a existência do campo até que a fórmula seja executada. Isto permite flexibilidade no JSON a receber. Por exemplo, o JSON anterior pode, por vezes, conter um campo adicional denominado Discount. No entanto, no nosso exemplo anterior, este campo não está presente. A escrita de uma fórmula que utilize o campo Discount não resultará em erros, durante o processo de criação da aplicação ou quando os utilizadores utilizam a aplicação. Se o campo estiver em falta quando a fórmula for executada, o valor irá apenas resultar num valor Blank().

Como o acesso a campos de um valor dinâmico não é avaliado ao escrever a fórmula, também não há Intellisense disponível. Tanto o JSON como o Power Fx são sensível às maiúsculas e minúsculas, por isso, tenha especial cuidado ao escrever nomes de campos.

Os valores JSON não precisam estar em uma notação de estilo de registro. O JSON válido pode ser apenas um valor, tal como "text value", true ou 123.456. Nesse caso, o valor dinâmico 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 suporta registos aninhados. A conversão desse JSON em um valor Dynamic resulta em objetos aninhados, e a notação de pontos 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 dinâmica chamada jsonObject, os campos podem 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 qualquer um dos campos na expressão de notação de ponto não existir, será obtido Blank().

Matrizes e tabelas

JSON pode conter matrizes de valores ou registros. Estas matrizes podem ser acedidas diretamente ou convertidas em tabelas do Power Fx.

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

Este JSON contém um registo com um campo denominado OrderLines que contém uma matriz de registos. Cada registo tem dois campos: Item e Quantity. Se o JSON for convertido em um valor dinâmico usando a função ParseJSON e definido como uma variável chamada jsonOrder, poderemos acessar as linhas de ordem individuais de várias maneiras.

Set( jsonOrder, ParseJSON( jsonStringVariable ) );

Pode obter registos e valores individuais utilizando a função Index(). Por exemplo, para obter o segundo registo no campo OrderLines, aceda ao campo Quantity e converta-o num valor.

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

É possível converter a matriz de linhas de encomenda diretamente numa tabela. Isso criará uma tabela de coluna única com um valor Dynamic representando o registro.

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

A tabela de coluna única 'orderLines' agora tem uma coluna 'Value' que representa o valor Dynamic . 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 valor Dinâmico na Value coluna.

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 de ordem mais fácil e direto em outras partes do seu aplicativo, você pode converter todo o valor Dynamic em um registro totalmente digitado usando a função ForAll( ). Fornecer o valor Dynamic diretamente para ForAll() significa que você pode acessar os campos de objeto diretamente em vez de usar o campo de coluna Value única.

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

A nova variável typedOrderLines agora é uma tabela Power Fx com tipo total com as seguintes colunas e valores:

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

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

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

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