Laajenna Universal Resource Schedulingia yleisellä FetchXML-kielellä

Artikkeli
06/06/2024

UFX on tarkennut kyselykieli, jolla voi tehdä tietokyselyjä dynaamisella FetchXML-kielillä sekä muokata ja valmistella tulokseksi saatuja tietoja Universal Resource Scheduling (URS) -ratkaisun käyttöön. Tällä kyselykielellä voi luoda mukautettuja kyselyjä, joilla aikataulutaulukko- ja ajoitusavustajasuodattimet voidaan muokata ja laajentaa vastaamaan organisaation yksilöllisiä liiketoimintatarpeita.

UFX sisältää kaksi osaa: UFX-säilön ja UFX-kyselyn.

Yksinkertainen UFX-säilö

UFX-säilö sisältää staattista kirjoitettua tietoa. Muistissa on esiintyy avaimia ja arvoja sisältävänä sanastona. Se voidaan sarjoittaa JSON:hon ja XML:ään. Kun tiedot on kirjoitettu, UFX-kysely voi tehdä siinä tietokyselyn ja asiakkaan käyttöliittymä voidaan sitoa siihen.

Käytännön syistä ja suorituskyvyn vuoksi muistisäilö toteutetaan Dynamics 365 -sovellusten SDK Entity -objektien pohjalta.

Näytesäilössä on kaksi arvoa.

Muistissa:

key	arvo	tyyppi
nimi	John	merkkijono
ikä	36	kokonaisluku

JSON:

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

XML:

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

UFX-tuetut tyypit

UFX-säilössä voi olla monien tyyppien arvoja. Ne luokitellaan kolmeen tyyppiluokkaan:

Luokka	Arvo
Yksinkertaiset tyypit	`bool (Boolean)`, `int (Int32)`, `long (Int64)`, `double (Double)`, `decimal (Decimal)`, `datetime (DateTime)`, `guid (Guid)`, `string (String)` Dynamics 365 -kohtaiset yksinkertaiset tyypit: `money (Money)`, `option (OptionSet)`, `lookup (EntityReference)`
Muut säilöt	`bag (Entity)`
Säilöluettelo	`list (EntityCollection)`

Lisää tyyppejä sisältävä JSON-näytesäilö:

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

Sama XML-muotoinen säilö:

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

UFX-kyselyt kirjoitetaan XML-pohjaisina UFX-säilöinä. Säilön ominaisuudet voivat sisältää UFX-direktiivejä tietojen dynaamista kyselyä varten. UFX-kysely suoritetaan muistiobjektissa, ei XML-muotoisena. Vain direktiivit kirjoitetaan XML-muotoisena. Sen tulos voidaan sarjoittaa JSON- tai XML-muotoon.

Seuraava UFX-kysely määrittää säilön accounts-ominaisuuden source-UFX-direktiivillä. Tuloksena on sidottu FetchXML-kieli, jonka Dynamics 365 suorittaa, ja accounts-ominaisuus, josta tulee säilöluettelo tai EntityCollection. Jokainen säilö on Dynamics 365:n asiakastietueen esiintymä.

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

UFX-kysely käsitellään peräkkäin, ja se voi sisältää useita FetchXML-kyselyjä.

Tämä on koodikatkelma edellisen UFX-kyselyn XML-muotoon sarjoitetusta tuloksesta. Huomaa, että joillakin on niitä kuvaavia metatietoja.

<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-direktiivi käyttää XPath-lauseketta, joka valitsee arvot nykyisestä säilöstä.

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

Tuloksena XML-muotoinen säilö:

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

UFX-kyselyn tärkein tekijä on sen mahdollisuus muodostaa dynaamisesti FetchXML-kieltä syötetiedon perusteella.

Seuraavassa näytteessä asiakkaita etsitään käyttäjän antamalla arvolla, joka on käytettävissä UFX-säilönä XPathin $input-muuttujana. Huomaa condition-elementin UFX:n jos- ja arvo-direktiivit.

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

Jos syötesäilön NameFilter-ominaisuuteen sisältyi %city%, Dynamics 365:n suorittama tuotettu FetchXML-ehto olisi seuraavanlainen.

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

Avaimet, arvot ja metatiedot

UFX-säilö sisältää avaimet ja arvot, ja joissakin arvoissa on lisäksi niitä kuvaavia metatietoja.

Esimerkki on esimerkiksi tyypin lookup (EntityReference) arvo. Kun Dynamics 365 -kysely tehdään FetchXML-kielen avulla, se palauttaa entiteetin loogisen nimen ja tietueen muotoillun näyttönimen. UFX-säilö säilyttää nämä lisätiedot ensisijaiseen arvoon liitettyinä metatietoina.

JSON-muotoon sarjoitettu metatietoja sisältävä lookup on seuraavanlainen:

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

Dynamics 365 -tietojen XPath

Koska UFX-säilön tiedot on kirjoitettu, UFX-kysely näkee sen rakenteisessa muodossa ja käyttää XPathia tiedoissa liikkumiseen ja arvojen valitsemiseen siitä.

UFX-direktiivissä määritetty XPath-lauseke havaitsee säilön tiedot samalla tavalla kuin säilön rakenteen XML-sarjoitetussa muodossa. Tiedot kuitenkin tallennetaan muistin .NET-objekteissa (Entity- ja EntityCollection-tyyppien esiintymissä) eikä XML-tiedostoissa.

Liite A: UFX-tyyppiviittaus

Huomautus: Kaikki UFX-tyypit tukevat ufx-type- ja ufx-formatvalue-metatietoja. Lisämetatietojen kuvaus on kunkin tyypin vieressä seuraavassa taulukossa.

UFX-nimi	Määritetyypin koodi	.NET-nimi	UFX-metatiedot
bool	totuusarvo	totuusarvo
kokonaisluku	Kokonaisluku	Int32
long	BigInt	Int64
double	Double	Double
desimaali	Desimaali	Desimaali
datetime	DateTime	DateTime
guid	Uniqueidentifier	Guid
merkkijono	Muistio	Merkkijono
rahasumma	Rahasumma	Rahasumma
option	Valintaluettelo	OptionSetValue
valinta	Valinta	EntityReference	`ufx-logicalname`
bag	Ei käytettävissä	Entiteetti	`ufx-id` `ufx-logicalname`
list	Ei käytettävissä	EntityCollection
Ei käytettävissä	Ei käytettävissä	AliasedValue	`ufx-aliasentity` `ufx-aliasattribute`

Liite B: UFX-kyselydirektiivit

UFX-direktiivejä voidaan käyttää FetchXML-kyselyn säilön ominaisuuksissa ja XML-elementeissä.

UFX-säilödirektiivit

Määrite	Value	Kuvaus
`ufx:if`	XPath	Testaa XPath-lausekkeen ja käsittelee ominaisuuden vain, jos testi palauttama arvo on tosi.
`ufx:source`	`fetch`	Suorittaa sidotun `<fetch>`-XML-elementin ja määrittää tuloksen ominaisuuteen.
`ufx:select`	XPath	Suorittaa XPath-lausekkeen ja määrittää tuloksen ominaisuuteen. Kun kyselyn kohteena on `bag` tai `list` XML-muotoinen valinnainen `bag`-alimäärite voidaan määrittää muuntamaan XPath-lausekkeen tulos.

UFX FetchXML -direktiivit

Elementti	Määrite	Value	Kuvaus
Kaikki elementit	`ufx:if`	XPath	Testaa XPath-lausekkeen ja lähettää XML-elementin vain, jos testi onnistuu
`ufx:apply`	`select`	XPath	Käy läpi XPath-lausekkeen palauttaman solmujoukon ja tulostaa XML-alielementit kerran kullekin solmulle.
`ufx:value`	`select`	XPath	Suorittaa XPath-lausekkeen ja tulostaa tuloksen nykyisessä XML-elementissä.
`ufx:value`	`attribute`	määritteen nimi	Määrittää XPath-lausekkeen tuloksen määritettyyn määritenimeen nykyisessä XML-elementissä.

Liite C: UFX XPath -funktiot

UFX lisää useita uusia funktioita XPathissa jo olevien funktioiden lisäksi.

datetime()

datetime(): Palauttaa kuluvan ajan UTC-muodossa

list()

list(bag | list, ...[bag | list]): käyttää syötteenä bag- tai list-arvojen määrää ja pienentää ne yhdeksi list-arvoksi

lookup-to-list()

lookup-to-list(lookup, ...[lookup]): käyttää lookup-arvojen määrää, muuntaa niistä jokaisen bag-arvoksi, jossa on ufx-id- ja ufx-logicalname-metatietojoukko, ja pienentää sen sitten yhdeksi list-arvoksi

option-to-list()

option-to-list(option, ...[option]): käyttää option-arvojen määrää, muuntaa niistä jokaisen bag-arvoksi, jossa on yksi option-ominaisuus, ja pienentää ne sitten yhdeksi list-arvoksi

order()

order(list, string, bool): Järjestää luettelon kunkin säilön ominaisuuden mukaan. Ominaisuus on määritetty argumentissa 2, laskeva järjestys määritetään argumentissa 3.
order(list, list): Järjestää luettelon useiden argumentissa 2 luettelona määritettyjen lajittelujärjestysten mukaan. Kullakin toisen luettelon bag-arvolla voi olla name- ja descending-ominaisuus.

iif()

iif(any, any, any): jos argumentti 1 on tosi, palauttaa argumentin 2. Palauttaa muussa tapauksessa argumentin 3.

Liite D: UFX XPath -muuttujat

Nimi	Kuvaus
$input	`bag`, joka on UFX-kyselyn käytettävissä syöttöarvoineen
$null	Tyhjäarvovakio. Kun ominaisuudessa valintaan `$null`, ominaisuus poistetaan säilöstä
$current	Viittaus nykyiseen UFX-kyselyn käsittelemään säilöön

Katso myös

Resurssien vastaavuushaun ymmärtäminen ja mukauttaminen Universal Resource Schedulingissa

Universal Resource Schedulingin laajennettavuuden julkaisutiedot

Jaa