Universal FetchXML เพื่อขยาย Universal Resource Scheduling

Universal FetchXML (UFX) เป็นภาษาค้นหาขั้นสูงที่คุณสามารถใช้เพื่อค้นหาข้อมูลโดยใช้ FetchXML แบบไดนามิก มันจะกําหนดและเตรียมข้อมูลที่ได้เพื่อใช้โดยโซลูชัน Universal Resource Scheduling (URS) ภาษาคิวรีนี้ช่วยให้คุณสามารถสร้างคิวรีแบบกําหนดเองเพื่อปรับแต่งและขยายตัวกรองบอร์ดกําหนดการและตัวช่วยกําหนดการเพื่อตอบสนองความต้องการทางธุรกิจเฉพาะขององค์กร

UFX ประกอบด้วยสองส่วน คือ UFX bag และ UFX query

กระเป๋า UFX ที่เรียบง่าย

UFX bag จะมีข้อมูลที่จัดประเภทแบบคงที่ ในหน่วยความจําจะสร้างแบบจําลองพจนานุกรมด้วยคีย์และค่า คุณสามารถ serialize เป็น JSON และ XML ได้ เมื่อข้อมูลถูกพิมพ์ UFX Query สามารถสืบค้นข้อมูลจากข้อมูลนั้น และ UI ของลูกค้าสามารถผูกกับข้อมูลนั้นได้

เพื่อเหตุผลด้านการใช้งานและประสิทธิภาพ ถุงในหน่วยความจําจะถูกติดตั้งบนวัตถุ SDK Entity ของ Dynamics 365 apps

ถุงตัวอย่างที่มีสองค่า

ในหน่วยความจํา:

ใน JSON:

{
    "name": "John",
    "age": 36
}

ใน XML:

<bag>
    <name ufx-type="string">John</name>
    <age ufx-type="int">36</age>
</bag>

ประเภทที่รองรับ UFX

ถุง UFX สามารถบรรจุค่าได้หลายประเภท พวกมันถูกจัดประเภทออกเป็นสามประเภท:

ต่อไปนี้คือตัวอย่างกระเป๋า JSON ที่มีประเภทเพิ่มเติม

{
    "citizen": true,          // implicit bool
    
    "age": 36,                // explicit int
    "age@ufx-type": "int",

    "name": {                 // nested bag
        "first": "John",
        "last": "Doe"
    },

    "children": [             // list of bags
        { "name": "Sam" },
        { "name": "Judy" }
    ]
}

กระเป๋าใบเดียวกันใน XML:

<bag>
    <citizen ufx-type="bool">true</citizen>

    <age ufx-type="int">36</age>

    <name ufx-type="bag">
        <first ufx-type="string">John</first>
        <last ufx-type="string">Doe</last>
    </name>

    <children ufx-type="list">
        <bag>
            <name ufx-type="string">Sam</name>
        </bag>
        <bag>
            <name ufx-type="string">Judy</name>
        </bag>
    </children>
</bag>

การสืบค้น UFX

เขียนคําค้น UFX เป็น UFX Bags ที่ใช้ XML คุณสมบัติในกระเป๋าสามารถมี คําสั่ง UFX เพื่อสืบค้นข้อมูลแบบไดนามิก แบบสอบถาม UFX จะดําเนินการบนวัตถุในหน่วยความจํา ไม่ใช่ XML เฉพาะคําสั่งเท่านั้นที่เขียนใน XML คุณสามารถ serialize ผลลัพธ์เป็น JSON หรือ XML ได้

คิวรี UFX ต่อไปนี้กําหนด accounts คุณสมบัติในกระเป๋าด้วย source คําสั่ง UFX ด้วยเหตุนี้ Dynamics 365 จึงดําเนินการ FetchXML แบบอินไลน์ โดยเติมคุณสมบัติ accounts ด้วยรายการของถุง โดย EntityCollection ที่แต่ละถุงแสดงถึงเรกคอร์ดลูกค้าองค์กรแต่ละรายการจาก Dynamics 365

<bag xmlns:ufx="https://schemas.microsoft.com/dynamics/2017/universalfetchxml">
    <accounts ufx:source="fetch">
        <fetch top="10">
            <entity name="account" />
        </fetch>
    </accounts>
</bag>

คิวรี UFX ได้รับการประมวลผลตามลําดับและสามารถมีคิวรี FetchXML ได้หลายแบบ

นี่คือตัวอย่างของผลลัพธ์ของคิวรี UFX ก่อนหน้านี้ที่ซีเรียลเป็น XML บางค่ามีเมตาดาต้าที่อธิบายรายละเอียดเพิ่มเติม

<bag>
  <accounts ufx-type="list">
    <bag ufx-id="166e39dd-34a1-e611-8111-00155d652f01" ufx-logicalname="account">
      <accountid ufx-type="guid">166e39dd-34a1-e611-8111-00155d652f01</accountid>
      <accountnumber ufx-type="string">ABSS4G45</accountnumber>
      <name ufx-type="string">Fourth Coffee (sample)</name>
      <statecode ufx-type="option" ufx-formatvalue="Active">0</statecode>
      <websiteurl ufx-type="string">https://www.fourthcoffee.com/</websiteurl>
      <primarycontactid ufx-type="lookup" ufx-formatvalue="Yvonne McKay (sample)" ufx-logicalname="contact">7c6e39dd-34a1-e611-8111-00155d652f01</primarycontactid>
      ...
    </bag>
    <bag ufx-type="bag" ufx-id="186e39dd-34a1-e611-8111-00155d652f01" ufx-logicalname="account">
      <accountid ufx-type="guid">186e39dd-34a1-e611-8111-00155d652f01</accountid>
      <accountnumber ufx-type="string">ACTBBDC3</accountnumber>
      <name ufx-type="string">Litware, Inc. (sample)</name>
      <statecode ufx-type="option" ufx-formatvalue="Active">0</statecode>
      <websiteurl ufx-type="string">https://www.litwareinc.com/</websiteurl>
      <primarycontactid ufx-type="lookup" ufx-formatvalue="Susanna Stubberod (sample)" ufx-logicalname="contact">7e6e39dd-34a1-e611-8111-00155d652f01</primarycontactid>
      ...
    </bag>
    ...
  </accounts>
</bag>

selectคําสั่ง UFX ใช้นิพจน์ XPath ที่เลือกค่าจากถุงปัจจุบัน

<bag xmlns:ufx="https://schemas.microsoft.com/dynamics/2017/universalfetchxml">
    <accounts ufx:source="fetch">
        <fetch top="10">
            <entity name="account" />
        </fetch>
    </accounts>

    <first_account_name ufx:select="accounts/bag[1]/name" />

    <!-- null values remove properties from the bag -->
    <accounts ufx:select="$null" />
</bag>

ถุงผลลัพธ์ใน XML:

<bag>
    <first_account_name ufx-type="string">Fourth Coffee (sample)</first_acount_name>
</bag>

แน่นอนว่าแง่มุมที่ทรงพลังที่สุดของ UFX Query คือความสามารถในการสร้าง FetchXML แบบไดนามิกตามข้อมูลที่ป้อนเข้า

ในตัวอย่างต่อไปนี้ ค้นหาบัญชีโดยใช้ค่าที่ผู้ใช้ให้และสามารถรับเป็น UFX bag ผ่านตัวแปร XPath $input สังเกตคําสั่ง UFX if และ value บน condition องค์ประกอบ

<bag xmlns:ufx="https://schemas.microsoft.com/dynamics/2017/universalfetchxml">
    <accounts ufx:source="fetch">
        <fetch top="10">
            <entity name="account">
                <filter>
                    <condition attribute="name" operator="like" ufx:if="$input/NameFilter">
                        <ufx:value select="$input/NameFilter" attribute="value" />
                    </condition>
                </filter>
            </entity>
        </fetch>
    </accounts>
</bag>

ถ้าNameFilterคุณสมบัติในถุงอินพุตมี %city%เงื่อนไข FetchXML ที่รันโดย Dynamics 365 จะมีลักษณะดังนี้

<condition attribute="name" operator="like" value="%city%" />

คีย์ ค่า และข้อมูลเมตา

กระเป๋า UFX มีคีย์และค่า โดยที่ค่าบางค่ามีข้อมูลเมตาเพิ่มเติมเพื่ออธิบาย

ตัวอย่างอาจเป็นค่าของชนิด lookup (EntityReference). เมื่อคิวรีจาก Dynamics 365 ผ่าน FetchXML จะส่งกลับชื่อตรรกะของเอนทิตีและชื่อที่แสดงที่จัดรูปแบบของเรกคอร์ด UFX bag จะเก็บข้อมูลเพิ่มเติมนี้ไว้เป็นเมตาดาต้าที่แนบมากับค่าหลัก

Serialized เป็น JSON ที่มี lookup ข้อมูลเมตามีลักษณะดังนี้:

{
    "primarycontactid": "7e6e39dd-34a1-e611-8111-00155d652f01",
    "primarycontactid@ufx-type": "lookup",
    "primarycontactid@ufx-logicalname": "contact",
    "primarycontactid@ufx-formatvalue": "Susanna Stubberod (sample)"
}

ใน XML:

<primarycontactid ufx-type="lookup" ufx-formatvalue="Susanna Stubberod (sample)" ufx-logicalname="contact">7e6e39dd-34a1-e611-8111-00155d652f01</primarycontactid>

XPath ผ่านข้อมูล Dynamics 365

เมื่อคุณพิมพ์ข้อมูลในถุง UFX การค้นหา UFX สามารถเห็นข้อมูลในรูปแบบที่มีโครงสร้างและใช้ XPath เพื่อค้นหาข้อมูลและเลือกค่าต่าง ๆ

นิพจน์ XPath ที่ระบุในคําสั่ง UFX จะเห็นข้อมูลในถุงคล้ายกับโครงสร้างของกระเป๋าในรูปแบบ XML ที่ซีเรียลไดเรกซ์ อย่างไรก็ตาม ข้อมูลจะถูกเก็บไว้ในวัตถุ .NET ในหน่วยความจํา (ในอินสแตนซ์ของ Entity และ EntityCollection ชนิด) และไม่ใช่ในเอกสาร XML

การอ้างอิงประเภท UFX

UFX ทุกประเภทรองรับ ufx-type และ ufx-formatvalue metadata ตารางต่อไปนี้อธิบายเมตาดาต้าเพิ่มเติมสําหรับแต่ละประเภท

คําสั่งคิวรี UFX

ใช้คําสั่ง UFX กับคุณสมบัติของถุงและองค์ประกอบ XML ของคําสั่ง FetchXML

คําสั่งกระเป๋า UFX

คําสั่ง UFX FetchXML

ฟังก์ชัน UFX XPath

UFX เพิ่มฟังก์ชันใหม่มากมายนอกเหนือจากฟังก์ชันที่มีอยู่ใน XPath

วันที่เวลา()

• datetime(): คืนค่าเวลาปัจจุบันในหน่วย UTC

รายการ ()

• list(bag | list, ...[bag | list]): รับbagค่า or list จํานวนหนึ่งเป็นอินพุตและแบนค่าเหล่านั้นให้เป็นค่าเดียวกันlist

lookup-to-list()

• lookup-to-list(lookup, ...[lookup]): รับค่าหลายค่า lookup แปลงแต่ละค่าเป็น a bag ที่มี ufx-id ชุดเมตาดาต้า และ ufx-logicalname แล้วแบนให้เป็นค่าเดียวกัน list.

option-to-list()

• option-to-list(option, ...[option]): รับค่าหลายค่า option แปลงแต่ละค่าเป็น a bag ที่มีคุณสมบัติเดียว option และแบนค่าเหล่านั้นเป็นค่าเดียวกันlist

คําสั่ง ()

• order(list, string, bool): เรียงลําดับรายการตามคุณสมบัติในแต่ละ bag. ระบุคุณสมบัติในอาร์กิวเมนต์ที่สอง และระบุลําดับจากมากไปน้อยในอาร์กิวเมนต์ที่สาม
• order(list, list): จัดเรียงรายการตามลําดับการจัดเรียงหลายรายการที่ระบุเป็นรายการในอาร์กิวเมนต์ที่สอง แต่ละbagรายการในรายการที่สองสามารถมีคุณสมบัติ a name และdescending

ไอเอฟ()

• iif(any, any, any): หากอาร์กิวเมนต์แรกเป็นจริง จะคืนค่าอาร์กิวเมนต์ที่สอง มิฉะนั้น จะคืนค่าอาร์กิวเมนต์ที่สาม

ตัวแปร UFX XPath

แหล่งข้อมูลเพิ่มเติม

การทําความเข้าใจและการปรับแต่งการจับคู่ทรัพยากรใน Universal Resource Scheduling