Работа с JSON в Power Fx
Power Fx позволяет создателям считывать JSON в нетипизированный объект с использованием функции ParseJSON.
Чтение и преобразование значений
ParseJSON преобразует следующую строку записи JSON в нетипизированный объект с полями ItemName, Quantity, ReleaseDate и AvailableForPreOrder.
{
"ItemName" : "Widget 1",
"Quantity" : 46,
"ReleaseDate" : "2022-09-01",
"AvailableForPreOrder" : true
}
Доступ к каждому из полей можно получить с помощью точечной нотации для значения Нетипизированный объект, возвращенного из 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 ) );
Обычно желательно явным образом преобразовывать значение нетипизированного объекта в определенный тип. Установка нетипизированного объекта в качестве значения переменной также превращает переменную в Нетипизированный объект. Следовательно, при использовании такого значения для присвоения переменной его, вероятно, также потребуется явным образом преобразовать. Однако в большинстве случаев значения нетипизированных объектов преобразовываются в определенный тип автоматически («приводятся») при использовании в качестве параметров функций, когда тип представляет собой простой тип, такой как логическое значение, число или текст, а профиль параметров функции не содержит потенциально конфликтующих перегрузок.
Left( untyped.ItemName, 1 ); // "W"
Radians( untyped.Quantity ); // 0.80285146
If (untyped.AvailableForPreOrder, "Available", "Not Available" ); // "Available"
Помимо автоматического преобразования типа в вызовах функций нетипизированные объекты также преобразовываются при присвоении свойствам элемента управления, где это возможно.
Label1.Text: untyped.Quantity
InputText1.Default: untyped.ItemName
И, наконец, при использовании операторов, таких как & или +, Нетипизированный объект будет приведен в соответствие с типом, если в ожидаемом типе нет двусмысленности.
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
Заметка
JSON не имеет типа GUID, Color, Time или DateTime . Эти значения представляются в виде строк. Если вы присвоите содержащее дату значение нетипизированого объекта JSON текстовому свойству напрямую, будет использоваться оригинальный текст JSON. Это может быть важно при работе с часовыми поясами, форматами даты и т. д. В таких случаях вы должны явно преобразовать значения, используя GUID(), ColorValue(), DateValue(), DateTimeValue() и т. д.
Если имя поля состоит из недопустимого имени идентификатора, например когда имена полей начинаются с цифры или содержат недопустимые символы, такие как дефис, вы можете поместить имена полей в одинарные кавычки:
untyped.'01'
untyped.'my-field'
Power Fx не будет оценивать существование поля, пока формула не будет запущена. Это обеспечивает гибкость во входящем JSON. Например, предыдущий JSON иногда может содержать дополнительное поле с именем Discount. Но в нашем предыдущем примере этого поля нет. Написание формулы, в которой используется поле Discount не приведет к каким-либо ошибкам в процессе создания приложения или при использовании приложения пользователями. Если поле отсутствует при выполнении формулы, значение просто будет Пустым().
Заметка
JSON поддерживает null значения для полей. Это также приведет к Пустым() значениям. В настоящее время нет различий в Power Fx между отсутствующим полем или полем со значением null.
Так как доступ к полям на Нетипизированных объектах не оценивается при написании формулы, то также отсутствует Intellisense. Как JSON, так и Power Fx чувствительны к регистру, поэтому будьте особенно внимательны при написании имен полей.
Значения JSON не обязательно должны быть представлены в виде записи. Действительный JSON может быть просто значением, например "text value", true или 123.456. В таком случае Нетипизированный объект, который ParseJSON возвращает – это само значение, а точечная нотация не используется.
Set( myText, Boolean( ParseJSON( "true" ) ) );
Set( myNumber, Value( ParseJSON( "123.456" ) ) );
Наконец, JSON поддерживает вложенные записи. Преобразование таких JSON в Нетипизированный объект приводит к вложенным объектам, а точечная нотация может использоваться для обхода иерархии.
{
"Version" : 1,
"RootElement" : {
"Parent" : {
"Name" : "This is the parent",
"Child" : {
"Name" : "This is the child"
}
}
}
}
При преобразовании этой строки JSON в переменную Нетипизированный объект с именем jsonObject, доступ к полям можно получить с помощью точечной нотации.
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"
Если какое-либо из полей в выражении точечной нотации не существует, возвращается значение Пусто().
Таблицы и массивы
JSON может содержать массивы значений или записей. К этим массивам можно получить доступ напрямую или их можно преобразовать в таблицы Power Fx.
{
"OrderNumber" : "SO000010",
"CustomerID" : "CUST0126",
"OrderLines" : [
{
"Item" : "Widget 1",
"Quantity" : 3
},
{
"Item" : "Widget 2",
"Quantity" : 5
}
]
}
Этот JSON содержит запись с полем с именем OrderLines, которое содержит массив записей. Каждая запись имеет два поля: Item и Quantity. Если JSON преобразуется в Нетипизированный объект с использованием функции ParseJSON и для него задается переменная с именем jsonOrder, мы можем получить доступ к отдельным строкам заказа несколькими способами.
Set( jsonOrder, ParseJSON( jsonStringVariable ) );
Вы можете получить отдельные записи и значения, используя функцию Указатель(). Например, чтобы получить вторую запись в поле OrderLines, перейдите к полю Quantity и преобразуйте его в значение.
Set( line2Quantity, Value( Index( jsonOrder.OrderLines, 2 ).Quantity ); // 5
Вы можете преобразовать массив строк заказа непосредственно в таблицу. Это создаст таблицу с одним столбцом с Нетипизированным объектом, представляющим запись.
Set( orderLines, Table( jsonOrder.OrderLines ) );
Таблица с одним столбцом "orderLines" теперь имеет столбец "Значение", который представляет Нетипизированный объект. Чтобы использовать любое из полей записи в этой таблице, используйте точечную нотацию для доступа к конкретному полю JSON на Нетипизированном объекте в столбце Value.
Set( jsonRecord, Index( orderLines, 2 ) ); // Get the second record in the table
Set( line2Item, Text( jsonRecord.Value.Item ) ); // "Widget 2"
Чтобы упростить использование записей строки заказа в других частях вашего приложения, вы можете преобразовать весь Нетипизированный объект в полностью типизированную запись с помощью функции ForAll(). Передача нетипизированного объекта непосредственно функции ForAll() означает, что вы можете получить доступ к полям объекта напрямую, а не путем использования поля Value одностолбцовой таблицы.
Set( typedOrderLines, ForAll( jsonOrder.OrderLines, { Item : Text( ThisRecord.Item ), Quantity : Value( ThisRecord.Quantity ) } ) );
Новая переменная typedOrderLines теперь является полностью типизированной таблицей Power Fx со следующими столбцами и значениями:
| Позиция | Количество |
|---|---|
| "Мини-приложение 1" | 3 |
| "Мини-приложение 2" | 5 |
В предыдущих примерах используются массивы записей, но JSON также может содержать массивы только значений. Рассмотрите следующий пример, который является допустимой строкой JSON, содержащей массив из трех строк.
[ "First Item", "Second Item", "Third Item"]
Мы можем получить один из элементов массива с помощью функции Указатель() и преобразовать ее в текст.
Text( Index( ParseJSON( jsonStringVariable ), 2 ) ) // "Second Item"