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

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

UFX ประกอบด้วยสององค์ประกอบ: UFX bag และ UFX query

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

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

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

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

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

ใน 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 เอาต์พุตสามารถอนุกรมเป็น 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 ผ่านตัวแปร 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 จะเก็บข้อมูลเพิ่มเติมเหล่านี้ไว้เป็นข้อมูลเมตาที่แนบมากับค่าหลัก

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 Query สามารถดูข้อมูลในรูปแบบที่มีโครงสร้างและใช้ XPath เพื่อสํารวจข้อมูลและเลือกค่าจากข้อมูลนั้น

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

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

ประเภท UFX ทั้งหมดรองรับ ufx-type และ ufx-formatvalue ข้อมูลเมตา ข้อมูลเมตาเพิ่มเติมจะอธิบายไว้ถัดจากแต่ละประเภท

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

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

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

คําสั่ง UFX FetchXML

ฟังก์ชัน UFX XPath

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

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

• datetime(): ส่งกลับเวลาปัจจุบันเป็น UTC

รายการ ()

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

lookup-to-list()

• lookup-to-list(ค้นหา, ... [lookup]): ใช้ค่าจํานวนหนึ่งlookupแปลงแต่ละค่าเป็น a ที่มีbagชุดข้อมูลufx-idufx-logicalnameเมตาและแบนเป็นค่าเดียวlist

option-to-list()

• option-to-list(ตัวเลือก, ... [option]): ใช้ค่าจํานวนหนึ่ง option แปลงแต่ละค่าเป็น bag คุณสมบัติเดียว option และแบนเป็นค่าเดียว list

คําสั่ง ()

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

ไอเอฟ()

• iif(ใด ๆ ใด ๆ ใด ๆ ): ถ้าอาร์กิวเมนต์ 1 เป็นจริง จะส่งกลับอาร์กิวเมนต์ 2 มิฉะนั้นจะส่งคืนอาร์กิวเมนต์ 3

ตัวแปร UFX XPath

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

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