A Universal Resource Scheduling kibővítése a Universal FetchXML használatával

Cikk
03/10/2022
6 perc alatt elolvasható

Az UFX egy speciális lekérdezési nyelv, amely lehetővé teszi, hogy lekérdezzen adatokat dinamikus FetchXML használatával, és az eredményül kapott adatok előkészítse a Universal Resource Scheduling (URS) megoldás általi felhasználásra. A lekérdezési nyelv lehetővé teszi, hogy létre hozza egyéni lekérdezések testreszabását és bővítése az ütemezési táblát és az ütemezési segéd szűrőket a szervezet egyedi üzleti igényei szerint.

Az UFX összetevőből áll, UFX Bag és UFX Query.

Egyszerű UFX Bag

Egy UFX Bag statikus beírt adatokat tartalmaz. Memóriában kulcsok és értékek szótáraként jelenik meg. Szerializálható: JSON és XML. A beírt adatok lehetővé teszi, hogy egy UFX Query lekérdezzen adatokat és az ügyfél felhasználói felület kapcsolódjon.

A memóriában levő zsák megvalósítása a Dynamics 365 apps SDK Entity objektumon van gyakorlati és a teljesítmény okokból.

Példa zsák két értékkel.

Memóriában levő:

kulcs	érték	típus
Név	John	karakterlánc
kor	36	egész

A JSON-ban:

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

XML-ben:

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

UFX támogatott típusok

Egy UFX Bag különféle értéket tartalmazhat. Kategorizálva vannak három típusosztályba:

Kategória	Érték
Egyszerű típusok	`bool (Boolean)`, `int (Int32)`, `long (Int64)`, `double (Double)`, `decimal (Decimal)`, `datetime (DateTime)`, `guid (Guid)`, `string (String)` Dynamics 365 specifikus egyszerű típusok: `money (Money)`, `option (OptionSet)`, `lookup (EntityReference)`
Egyéb zsákok	`bag (Entity)`
Zsákok listája	`list (EntityCollection)`

Íme egy példa JSON zsák további típusokat tartalmazó:

{
    "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" }
    ]
}

Az XML-ben ugyanaz a zsák:

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

A UFX Queries bemutatása

Az UFX Queries XML alapú UFX zsákokként vannak megírva. A zsákokban a tulajdonságok tartalmazhatnak UFX irányelveket az adatok dinamikus lekérdezéséhez. Az UFX Query végrehajtása a memóriában tárolt objektumokon, nem XML-en történik. Csak az irányelvek készülnek XML-ben. A kimenete szerializálható JSON vagy XML formátumba.

A következő UFX Query határozza meg az accounts tulajdonságot a zsákban a source UFX utasítással. Ennek eredményeként a Dynamics 365-ben végrehajtódik a beágyazott FetchXML és az accounts tulajdonság zsákok listája lesz vagy EntityCollection, ahol mindegyik zsák a Dynamics 365 egy partnerbejegyzésének egy példánya.

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

UFX Query egymás után következő feldolgozású, és sok FetchXML-lekérdezéset tartalmazhat.

Íme egy szövegminta az előző XML-be szerializált UFX lekérdezés eredményéből. Tekintse meg, hogy néhány értéket további metaadatok írnak le.

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

A select UFX irányelv veszi egy XPath kifejezést, amely értékeket jelöli ki a jelenlegi zsákból.

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

Az eredmény zsák XML-ben:

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

Az UFX lekérdezés egyértelműen leghatékonyabb eleme, az a képesség, hogy a bevitt adatok alapján FetchXML-t dinamikusan létrehoz.

Az alábbi példában keresésünk partnereket a felhasználó által megadott érték alapján az XPath keresztül egy UFX zsákokban formájában érhetők el $input változó. Figyelje meg a UFX ha és érték irányelveket a condition elemen.

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

Ha a NameFilter tulajdonság a bemeneti zsákban tartalmazza a %city% elemet, a Dynamics 365 által végrehajtott gyártott FetchXML feltétel így néz ki.

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

Kulcsok, értékek és metaadatok

Egy UFX Bag kulcsokat és értékeket tartalmaz, és néhány értékek rendelkezik további, az értéket leíró metaadatokkal.

Példa lehet egy lookup (EntityReference) típusú érték. Amikor a Dynamics 365 alkalmazásból FetchXML-en keresztül lekérdezik, az entitás logikai nevét, valamint formázott megjelenítendő nevét adja vissza bejegyzésként. A UFX Bag megőrzi a kiegészítő információkat az elsődleges értékhez csatolt metaadatokként.

Szerializálva JSON-be, egy lookup metaadatokkal így néz ki:

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

XML-ben:

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

XPath a Dynamics 365 adatok felett

Azáltal, hogy az adatok egy UFX zsákokban vannak típussal ellátva, a UFX Query strukturált formátumban látja őket, és az XPath bejárja az adatokat, és kiválasztja belőlük az értékeket.

A UFX irányelvben megadott XPath kifejezés hasonlóan látja a zsákban az adatokat a zsák szerkezetéhez XML-szerializált formában. Azonban az adatokat a memóriában .NET objektumokként tárolja (Entity és EntityCollection típusok példányaiban), és nem az XML-dokumentumokban.

A. függelék: UFX-típus referenica

Megjegyzés: Minden UFX-típus támogatja a ufx-type és ufx-formatvalue metaadatokat. További metaadat-típusok az alábbi táblázatban ismertetettek a típusok mellett.

UFX-név	Attribútumtípus kódja	.NET-név	UFX-metaadat
bool	Logikai	Logikai
egész	Egész	Int32
long	BigInt	Int64
double	Dupla	Dupla
tizedesjegy	Tizedes	Tizedes
dátumidő	DátumIdő	DátumIdő
guid	Uniqueidentifier	Guid
karakterlánc	Feljegyzés	Karakterlánc
pénznem	Pénz	Pénz
option	Választási lista	OptionSetValue
keresés	Keresés	EntityReference	`ufx-logicalname`
bag	n.a.	Entitás	`ufx-id` `ufx-logicalname`
lista	n.a.	EntityCollection
n.a.	n.a.	AliasedValue	`ufx-aliasentity` `ufx-aliasattribute`

B. függelék: UFX lekérdezési irányelvek

Az UFX-irányelvek használhatók a zsákoktulajdonságokon és a FetchXML-lekérdezés XML-elemein.

UFX Bag irányelvek

Attribútum	Value	Leírás
`ufx:if`	XPath	XPath kifejezés tesztelése, és csak akkor dolgozza fel a tulajdonságot, ha a teszt eredménye igaz
`ufx:source`	`fetch`	Végrehajtja a beágyazott `<fetch>` XML-elemet, és hozzárendeli az eredményt a tulajdonsághoz
`ufx:select`	XPath	Végrehajtja a beágyazott XPath kifejezést, és hozzárendeli az eredményt a tulajdonsághoz Lekérdezésekor egy `bag` vagy `list` esetén egy választható alárendelt `bag` XML-ben lehet megadni az XPath kifejezés eredményének átalakításához

UFX FetchXML irányelvek

Elem	Attribútum	Value	Leírás
Minden elem	`ufx:if`	XPath	Az XPath kifejezésen teszteket végez, és csak a tesztek sikere esetén bocsátja ki az XML-elemet.
`ufx:apply`	`select`	XPath	Átnézi az XPath kifejezés által visszaadott nodesetet, és exportálja az alárendelt XML-elemeket egyszer mindegyik csomópontjára vonatkozóan
`ufx:value`	`select`	XPath	Végrehajtja az XPath kifejezést, és exportálja az eredményeket az aktuális XML-elembe
`ufx:value`	`attribute`	attribútumnév	XPath kifejezés eredményét hozzárendeli a megadott attribútum nevét az aktuális XML-elemen

C függelék: UFX XPath függvények

Az UFX felvesz számos új függvényt az XPath natív függvénykészlete mellé.

datetime()

datetime(): UTC-ben adja meg az aktuális időt

list()

list(bag | list, ...[bag | list]): Vesz több bag vagy list bemeneti értéket, és egyetlen list értékbe olvasztja össze őket

lookup-to-list()

lookup-to-list(lookup, ...[lookup]): vesz számos lookup értékeket, konvertálja mindet egy bag értékbe beállított ufx-id és ufx-logicalname metaadatokkal, és egyetlen list értékbe olvasztja össze őket

option-to-list()

option-to-list(option, ...[option]): vesz számos option értékeket, konvertálja mindet egy bag értékbe egyetlen option tulajdonsággal, és egyetlen list értékbe olvasztja össze őket

order()

order(list, string, bool): listájá rendez a zsákokban tulajdonság szerint. A tulajdonság 2. argumentumban van megadva, a csökkenő argumentum a 3. argumentumban van megadva.
order(list, list): lista rendezése több rendezési szempont szerint, amelyek a 2. argumentumban listaként vannak megadva. Minden egyes bag a második listában rendelkezhet name és descending tulajdonsággal

iif()

iif(any, any, any): az 1. argumentum teljesülésekor a 2. argumentumot adja eredményül, egyébként visszaadja a 3. argumentumot

D. függelék: UFX XPath változók

Név	Leírás
$input	Egy `bag` elérhető el a UFX lekérdezésben bemeneti értékekkel
$null	Null állandó. A `$null` kijelölése egy tulajdonságon eltávolítja a tulajdonságot a zsákokból
$current	Az aktuális zsákra hivatkozás, amelyet az UFX lekérdezés feldolgozott

Kapcsolódó információk

Az erőforrás-egyeztetés megértése és testreszabása a Universal Resource Scheduling alkalmazásban

Universal Resource Scheduling bővíthetőség kibocsátási megjegyzések

Megjegyzés

Megosztja velünk a dokumentációja nyelvi preferenciáit? Rövid felmérés elvégzése. (ne feledje, hogy ez a felmérés angol nyelvű)

A felmérés elvégzése körülbelül hét percet vesz igénybe. Semmilyen személyes adatot nem gyűjtünk (adatvédelmi nyilatkozat).