עבודה עם 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, צבע, שעה או תאריך ושעה. ערכים אלה מיוצגים כמחרוזת. אם תקצה ערך אובייקט JSON לא מסווג המכיל ישירות תאריך למאפיין טקסט, הטקסט המקורי של הן JSON ישמש. דבר זה עשוי להיות חשוב כאשר עוסקים באזורי זמן, פורמטים של תאריכים וכו'. במקרים כאלה עליך להמיר במפורש את הערכים באמצעות GUID(), ColorValue(), DateValue(), DateTimeValue(), וכו.

במקרה שבו שם שדה מורכב משם מזהה לא חוקי, למשל כאשר שמות השדות מתחילים במספר או מכילים תווים לא חוקיים כגון מקף, ניתן לשים את שמות השדות תוך גרשיים בודדים:

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

Power Fx לא יעריך את קיומו של השדה עד שהנוסחה תופעל. זה מאפשר גמישות ב- JSON הנכנס. למשל, ה- JSON הקודם עשוי להכיל לפעמים שדה נוסף שנקרא Discount. אבל בדוגמה הקודמת שלנו, השדה הזה לא קיים. כתיבת נוסחה המשתמשת בשדה Discount לא תגרום לשגיאות כלשהן, במהלך תהליך יצירת האפליקציה או כאשר משתמשים משתמשים באפליקציה. אם השדה חסר כאשר הנוסחה פועלת, הערך רק יגרום לערךBlank().

הערה

JSON תומך בערכי null עבור שדות. אלה גם יגרמו לערכי Blank(). נכון לעכשיו, אין הבדל ב- 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"

אם אחד מהשדות בביטוי סימון הנקודות אינו קיים, הערך Blank() יוחזר.

מערכים וטבלאות

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 ) );

אתה יכול לאחזר רשומות וערכים בודדים באמצעות הפונקציה Index(). לדוגמה, כדי לקבל את הרשומה השנייה בשדה OrderLines, עליך לגשת לשדה Quantity ולהמיר אותו לערך.

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

ניתן להמיר את מערך שורות ההזמנה ישירות לטבלה. פעולה זו תיצור טבלה בעלת עמודה אחת עם אובייקט לא מסווג שמייצג את הרשומה.

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

ל- 'orderLines' בטבלת עמודה בודדת יש כעת עמודת 'Value' שמייצגת את האובייקט הלא מסווג. כדי להשתמש בכל אחד מהשדות מתוך רשומה בטבלה זו, השתמש בסימון הנקודה כדי לגשת לשדה 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"]

אנו יכולים לאחזר אחד מהפריטים מהמערך באמצעות הפונקציה Index(), ולהמיר אותה לטקסט.

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