العمل مع 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 ) );

بشكل عام، من الجيد أن يتم تحويل قيمة كائن غير محدد بشكل واضح إلى نوع محدد. تعيين كائن غير مضبط كقيمة متغير يجعل المتغير كائنا غير مف الأساسية أيضا. وبالتالي، فإن تحويل هذه القيمة بشكل واضح عندما يكون الإعداد إلى متغير مطلوبا على النحو المرجح. ولكن في معظم الحالات، سيتم تحويل قيم الكائن غير المعينة إلى نوع محدد تلقائيا ("isolee") عند استخدامها كمعلمات وظيفة حيث يكون النوع بسيطا مثل النوع منطقي أو رقم أو نصي، ولا يكون لملف تعريف معلمة الوظيفة تحميلات زائدة متضاربة محتملة.

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' عمود 'قيمة' يمثل الكائن غير المصنف. لاستخدام أي من الحقول من سجل في هذا الجدول، استخدم التدوين النقطي للوصول إلى حقل 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"