Universal FetchXML rozszerzający Universal Resource Scheduling

Universal FetchXML (UFX) to zaawansowany język zapytań, który umożliwia wykonywanie zapytań o dane przy użyciu dynamicznego formatu FetchXML, kształtowanie i przygotowywanie danych wynikowych do użycia przez rozwiązanie Universal Resource Scheduling (URS). Ten język zapytań umożliwia tworzenie kwerend niestandardowych w celu dostosowywania i rozszerzania filtrów tablicy harmonogramu i asystenta planowania w celu spełnienia unikatowych potrzeb biznesowych organizacji.

UFX składa się z dwóch komponentów: torby UFX i zapytania UFX.

Prosta torba UFX

Torba UFX zawiera dane statyczne. W pamięci modeluje słownik z kluczami i wartościami. Może być serializowany do formatów JSON i XML. Wpisywanie danych pozwala zapytaniu UFX na wysyłanie z nich zapytań o dane, a interfejsowi użytkownika klienta na powiązanie się z nimi.

Ze względów praktycznych i wydajnościowych torba w pamięci jest implementowana na obiekcie Dynamics 365 Apps SDK Entity .

Worek na próbkę zawierający dwie wartości.

W pamięci:

W formacie JSON:

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

W formacie XML:

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

Typy obsługiwane przez UFX

Torba UFX może zawierać wartości wielu typów. Są one podzielone na trzy klasy typów:

Oto przykładowa torba JSON zawierająca więcej typów:

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

Ta sama torba w 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>

Zapytania UFX

Zapytania UFX są zapisywane jako worki UFX oparte na XML. Właściwości w torbie mogą zawierać dyrektywy UFX do dynamicznego wysyłania zapytań do danych. Zapytanie UFX jest wykonywane na obiektach w pamięci, a nie w kodzie XML. Tylko dyrektywy są zapisane w formacie XML. Jego dane wyjściowe mogą być serializowane do formatu JSON lub XML.

Poniższe zapytanie UFX definiuje accounts właściwość w torbie z dyrektywą source UFX. W rezultacie Dynamics 365 wykonuje wbudowany FetchXML, wypełniając accounts właściwość listą worków. Miejsce EntityCollection , w którym każdy worek reprezentuje indywidualny rekord klienta z usługi 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>

Zapytanie UFX jest przetwarzane sekwencyjnie i może zawierać wiele zapytań FetchXML.

Oto fragment kodu wyniku poprzedniego zapytania UFX zserializowanego do formatu XML. Zwróć uwagę, że niektóre wartości mają metadane dodatkowo je opisujące.

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

Dyrektywa select UFX przyjmuje wyrażenie XPath, które wybiera wartości z bieżącego worka.

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

Wynikowy worek w formacie XML:

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

Z pewnością najpotężniejszym aspektem zapytania UFX jest jego zdolność do dynamicznego generowania FetchXML na podstawie danych wejściowych.

W poniższym przykładzie wyszukujemy konta według wartości podanej przez użytkownika i dostępnej jako torba UFX za pomocą zmiennej XPath $input . Zwróć uwagę na dyrektywy UFX if i value w condition elemencie.

<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 Jeśli właściwość w torbie wejściowej zawierała %city% utworzony warunek FetchXML wykonywany przez usługę Dynamics 365, wyglądałby następująco.

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

Klucze, wartości i metadane

Torba UFX zawiera klucze i wartości, przy czym niektóre wartości mają więcej metadanych, aby je opisać.

Przykładem może być wartość typu lookup (EntityReference). W przypadku zapytania z Dynamics 365 za pośrednictwem FetchXML zwraca logiczną nazwę encji i sformatowaną nazwę wyświetlaną rekordu. Torba UFX zachowuje te dodatkowe informacje jako metadane dołączone do wartości podstawowej.

Serializowane do formatu JSON, a lookup z metadanymi wyglądają następująco:

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

W formacie XML:

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

XPath za pośrednictwem danych Dynamics 365

Wpisywanie danych w torbie UFX umożliwia zapytaniu UFX wyświetlenie ich w ustrukturyzowanym formacie i użycie XPath do przejrzenia danych i wybrania z nich wartości.

Wyrażenie XPath określone w dyrektywie UFX powoduje, że dane w torbie są podobne do struktury worka w postaci serializowanej w formacie XML. Jednak dane są przechowywane w obiektach .NET w pamięci (w wystąpieniach Entity i EntityCollection typach), a nie w dokumentach XML.

Odniesienie do typu UFX

Wszystkie typy UFX obsługują ufx-type metadane i ufx-formatvalue . Dodatkowe metadane są opisane obok każdego typu.

Dyrektywy zapytań UFX

Dyrektywy UFX mogą być używane w odniesieniu do właściwości worka oraz elementów XML zapytania FetchXML.

Dyrektywy dotyczące toreb UFX

Dyrektywy UFX FetchXML

Funkcje UFX XPath

UFX dodaje wiele nowych funkcji oprócz tych dostępnych natywnie w XPath.

data/godzina()

• datetime(): Zwraca bieżący czas w UTC

lista()

• list(torba | lista, ... [bag | list]): Pobiera pewną liczbę bag wartości or list jako dane wejściowe i spłaszcza je do jednej list

Szukaj do-listy()

• Lookup-to-list(Wyszukiwanie, ... [lookup]): Pobiera pewną liczbę lookup wartości, konwertuje każdą z nich na a bag z zestawem ufx-id metadanych i ufx-logicalname i spłaszcza je do jednego list

option-to-list() (opcja do listy)

• option-to-list(opcja, ... [opcja]): Pobiera pewną liczbę option wartości, konwertuje każdą z nich na a bag z pojedynczą option właściwością i spłaszcza je do jednej list

porządek()

• order(list, string, bool): porządkuje listę według właściwości w każdym worku. Właściwość jest określona w argumencie 2, malejąco jest określona w argumencie 3.
• order(list, list): Uporządkuj listę według wielu porządków sortowania określonych jako lista w argumencie 2. Każdy bag z drugiej listy może mieć właściwość name i descending

iif()

• iif(any, any, any): Jeśli argument 1 jest prawdziwy, zwraca argument 2, w przeciwnym razie zwraca argument 3

Zmienne UFX XPath

Dodatkowe zasoby

Opis i dostosowywanie dopasowywania zasobów w Universal Resource Scheduling