Επεκτείνετε το Universal Resource Scheduling με Καθολικό FetchXML

Άρθρο
06/06/2024

Η UFX είναι μια σύνθετη γλώσσα ερωτημάτων που σάς δίνει τη δυνατότητα να θέσετε ερωτήματα σε δεδομένα χρησιμοποιώντας δυναμικό σχήμα FetchXML και να προετοιμάσετε τα δεδομένα που προκύπτουν για κατανάλωση από τη λύση Universal Resource Scheduling (URS). Αυτή η γλώσσα ερωτημάτων σάς επιτρέπει να δημιουργείτε προσαρμοσμένα ερωτήματα για να προσαρμόσετε και να επεκτείνετε τον πίνακα χρονοδιαγράμαμτος και τα φίλτρα βοηθού χρονοδιαγράμματος ώστε να καλύπτονται οι μοναδικές ανάγκες του οργανισμού.

Το UFX αποτελείται από δύο στοιχεία, το Σύνολο UFX και το Ερώτημα UFX.

Απλό σύνολο UFX

Ένα σύνολο UFX περιέχει στατικά δεδομένα που πληκτρολογήσατε. Στη μνήμη, εμφανίζεται ως λεξικό με κλειδιά και τιμές. Μπορεί να σειριοποιηθεί σε JSON και XML. Με τα δεδομένα που πληκτρολογήσατε δίνεται η δυνατότητα σε ένα Ερώτημα UFX να θέσει ερωτήματα σε δεδομένα από αυτό και στο περιβάλλον εργασίας χρήστη να συνδεθεί με αυτό.

Για πρακτικούς λόγους και για λόγους απόδοσης, το σύνολο εντός της μνήμης του Dynamics 365 υλοποιείται στο στοιχείο SDK Entity εφαρμογών.

Το σύνολο δειγμάτων περιέχει δύο τιμές.

Στη μνήμη:

κλειδί	τιμή	τύπος
όνομα	John	συμβολοσειρά
ηλικία	36	ακέραιος

Στο JSON:

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

Στο XML:

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

Υποστηριζόμενοι τύποι UFX

Ένα σύνολο UFX μπορεί να περιέχει πολλούς τύπους τιμών. Ταξινομούνται σε τρεις τύπους κλάσεων:

Κατηγορία	Τιμή
Απλοί τύποι	`bool (Boolean)`, `int (Int32)`, `long (Int64)`, `double (Double)`, `decimal (Decimal)`, `datetime (DateTime)`, `guid (Guid)`, `string (String)` Ειδικοί απλοί τύποι Dynamics 365: `money (Money)`, `option (OptionSet)`, `lookup (EntityReference)`
Άλλα σύνολα	`bag (Entity)`
Λίστα συνόλων	`list (EntityCollection)`

Ακολουθεί ένα σύνολο 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 συντάσσονται ως XML που βασίζονται σε Σύνολα UFX. Οι ιδιότητες στο σύνολο μπορεί να περιέχουν Οδηγίες UFX για υποβολή ερωτημάτων σε δεδομένα δυναμικά. Ένα ερώτημα UFX εκτελείται σε στοιχεία εντός μνήμης, όχι σε XML. Καταγράφονται μόνο οι οδηγίες σε XML. Η έξοδός του μπορεί να σειριοποιηθεί σε JSON ή XML.

Το παρακάτω ερώτημα UFX καθορίζει την ιδιότητα accounts στο σύνολο με την οδηγία source UFX. Αυτό έχει ως αποτέλεσμα το ενσωματωμένο FetchXML να εκτελεστεί από το Dynamics 365 και η ιδιότητα 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 είναι η δυνατότητα να δημιουργήσει FetchXML βάσει δεδομένων εισόδου.

Το παρακάτω δείγμα, γίνεται αναζήτηση λογαριασμών κατά τιμή που παρέχεται από τον χρήστη και είναι διαθέσιμη ως σύνολο UFX μέσω XPath $input μεταβλητής. Λάβετε υπόψη σας τις οδηγίες UFX εάν και τιμή στο στοιχείο 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 διατηρεί αυτές τις πρόσθετες πληροφορίες ως μετα-δεδομένα που επισυνάπτονται στην κύρια τιμή.

Σειριοποιημένο σε 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 για αλλαγή των δεδομένων και επιλογή τιμών από αυτό.

Μια έκφραση UFX που ορίζεται σε οδηγία UFX βλέπει τα δεδομένα στο σύνολο παρόμοια με τη δομή του συνόλου σε μορφή σειριοποιημένη XML. Ωστόσο, τα δεδομένα αποθηκεύονται στη μνήμη .NET αντικειμένων (σε παρουσίες τύπων Entity και EntityCollection) και όχι σε έγγραφα XML.

Παράρτημα Α: UFX τύπος αναφοράς

Σημείωση: Όλοι οι τύποι UFX υποστηρίζουν τα μεταδεδομένα ufx-type και ufx-formatvalue. Τα επιπλέον μεταδεδομένα περιγράφονται δίπλα σε κάθε τύπο στον παρακάτω πίνακα.

Όνομα UFX	Κωδικός τύπου χαρακτηριστικού	Όνομα .NET	Μετα-δεδομένα UFX
δυαδ.	Δυαδική τιμή	Δυαδική τιμή
ακέραιος	Ακέραιος	Int32
μεγάλου μήκους	BigInt	Int64
διπλής ακρίβειας	Διπλό	Διπλό
δεκαδικό	Δεκαδικός	Δεκαδικός
ημερομηνία/ώρα	ΗμερομηνίαΏρα	ΗμερομηνίαΏρα
guid	Uniqueidentifier	Guid
συμβολοσειρά	Υπόμνημα	Συμβολοσειρά
χρήματα	Χρηματικός τύπος	Χρηματικός τύπος
επιλογή	Λίστα επιλογών	OptionSetValue
αναζήτηση	Αναζήτηση	EntityReference	`ufx-logicalname`
σύνολο	Δ/Υ	Οντότητα	`ufx-id` `ufx-logicalname`
list	Δ/Υ	EntityCollection
Δ/Υ	Δ/Υ	AliasedValue	`ufx-aliasentity` `ufx-aliasattribute`

Παράρτημα Β: Οδηγίες ερωτήματος UFX

Οι οδηγίες UFX μπορούν να χρησιμοποιηθούν σε ιδιότητες συνόλου και σε στοιχεία XML ενός ερωτήματος FetchXML.

Οδηγίες συνόλου UFX

Χαρακτηριστικό	Value	Περιγραφή
`ufx:if`	XPath	Ελέγχει την έκφραση XPath και επεξεργάζεται μόνο την ιδιότητα, αν η δοκιμή επιστρέφει true
`ufx:source`	`fetch`	Εκτελεί το ενσωματωμένο στοιχείο `<fetch>` XML και αντιστοιχίζει το αποτέλεσμα στην ιδιότητα
`ufx:select`	XPath	Εκτελεί την έκφραση XPath και αντιστοιχίζει το αποτέλεσμα στην ιδιότητα Όταν υποβάλετε ερωτήματα για ένα `bag` ή `list` ένα προαιρετικό, θυγατρικό `bag` σε μορφή XML μπορεί να καθοριστεί για να μετατρέψετε το αποτέλεσμα της παράστασης XPath

Οδηγίες UFX FetchXML

Στοιχείο	Χαρακτηριστικό	Value	Περιγραφή
Όλα τα στοιχεία	`ufx:if`	XPath	Ελέγχει την έκφραση XPath και εκπέμπει μόνο το στοιχείο XML εάν ολοκληρωθούν με επιτυχία οι δοκιμές
`ufx:apply`	`select`	XPath	Διέρχεται από το nodeset που επιστρέφεται από την έκφραση XPath και εξάγει τα θυγατρικά στοιχεία XML μία φορά για κάθε κόμβο
`ufx:value`	`select`	XPath	Εκτελεί την έκφραση XPath και εμφανίζει το αποτέλεσμα στο τρέχον στοιχείο XML
`ufx:value`	`attribute`	όνομα χαρακτηριστικού	Αντιστοιχίζει το αποτέλεσμα της έκφρασης XPath για το συγκεκριμένο όνομα χαρακτηριστικού στο τρέχον στοιχείο XML

Παράρτημα C: UFX XPath λειτουργίες

Το UFX προσθέτει έναν αριθμό νέων λειτουργιών, εκτός από αυτές που διατίθενται εγγενώς στο XPath.

datetime()

datetime(): επιστρέφει την τρέχουσα ώρα σε UTC

list()

λίστα(σύνολο | λίστα, ...[σύνολο | λίστα]): Λαμβάνει τον αριθμό των τιμών bag ή list ως καταχώριση και τα κάνει ένα list

lookup-to-list()

lookup-to-list(αναζήτηση, ...[αναζήτηση]): Λαμβάνει έναν αριθμό τιμών lookup, τις μετατρέπει σε bag με μεταδεδομένα ufx-id και ufx-logicalname και τα κάνει ένα list

option-to-list()

option-to-list(επιλογή, ...[επιλογή]): Λαμβάνει έναν αριθμό τιμών option, τις μετατρέπει σε σύνολο bag με απλή ιδιότητα option και τις κάνει ένα list

order()

παραγγελία(λίστα, συμβολοσειρά, δυαδ.): Παραγγέλνει μια λίστα κατά ιδιότητα σε κάθε σύνολο. Η ιδιότητα έχει καθοριστεί στο όρισμα 2, η φθίνουσα σειρά καθορίζεται στο όρισμα 3.
παραγγελία (λίστα, λίστα): Γίνεται παραγγελία μιας λίστας σε πολλαπλές σειρές ταξινόμησης που καθορίζεται ως μια λίστα στο όρισμα 2. Κάθε bag από τη δεύτερη λίστα μπορεί να περιέχει ένα name και descending ιδιότητα

iif()

iif(οποιοδήποτε, οποιοδήποτε, οποιοδήποτε): Αν το όρισμα 1 είναι αληθές, επιστρέφει το όρισμα 2, ειδάλλως επιστρέφει το όρισμα 3

Παράρτημα Δ: UFX XPath μεταβλητές

Όνομα	Περιγραφή
$input	Ένα `bag` διαθέσιμο στο ερώτημα UFX με τιμές εισαγωγής
$null	Μια σταθερά null. Αν επιλέξετε `$null` σε μια ιδιότητα καταργείται η ιδιότητα από το σύνολο
$current	Η αναφορά στο τρέχον σύνολο υπόκειται σε επεξεργασία από το ερώτημα UFX

Δείτε επίσης

Κατανόηση και προσαρμογή της αντιστοίχισης πόρων στο Universal Resource Scheduling

Σημειώσεις έκδοσης επεκτασιμότητας Universal Resource Scheduling

Κοινή χρήση μέσω