Trabalhar com JSON no Power Fx

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

Ler e converter valores

ParseJSON converterá a seguinte cadeia de caracteres de registro JSON em um registro dinâmico com campos ItemNamee QuantityReleaseDateAvailableForPreOrder.

{
  "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 dinâmico 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 também torna a variável um valor dinâmico. Portanto, é provável que seja necessário converter esse valor explicitamente ao definir como uma variável. Mas, na maioria dos casos, os valores dinâmicos serão convertidos em um tipo específico automaticamente ("coerce") quando usados como parâmetros de função em que o tipo é um tipo simples, como booliano, 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

Por fim, 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 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:

dynamic.'01'
dynamic.'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().

Como o acesso a campos de um valor dinâmico não é avaliado ao escrever a fórmula, também não há nenhum 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 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 valor dinâmico retornado por ParseJSON é o valor em si 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 um valor dinâmico 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 dinâmica nomeada 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 algum dos campos na expressão da notação de ponto não existir, Blank() será retornado.

Matrizes e tabelas

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 valor dinâmico usando a função ParseJSON e definido como uma variável nomeada jsonOrder, poderemos acessar as linhas de 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 valor dinâmico que representa o registro.

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

A tabela de coluna única 'orderLines' agora tem uma coluna 'Value' que representa o valor dinâmico . 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 pedido mais fácil e simples em outras partes do seu aplicativo, você pode converter todo o valor dinâmico em um registro totalmente tipado usando a função ForAll( ). Fornecer o valor dinâmico 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 do Power Fx totalmente classificada com as seguintes colunas e valores:

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"