توسيع Universal Resource Scheduling باستخدام FetchXML العالمي‬

إن UFX عبارة عن لغة استعلام متقدم تتيح لك إمكانية الاستعلام عن البيانات باستخدام FetchXML الديناميك، والشكل، وإعداد البيانات الناتجة للاستهلاك بواسطة حل Universal Resource Scheduling (URS). تسمح لك لغة الاستعلام هذه بإنشاء استعلامات مخصصة لتخصيص وتوسيع لوحة الجدولة وجدولة عوامل تصفية مساعد الجدولة للوفاء بمتطلبات الأعمال الفريدة لدى المؤسسة.

تتكون لغة UFX من مكونين اثنين وهما مجموعة UFX واستعلام UFX.

مجموعة UFX البسيطة

تحتوي مجموعة UFX على بيانات مكتوبة ثابتة. وفي الذاكرة، يتم تمثيلها كقاموس يتضمن مفاتيح وقيم. ويمكن سلسلتها إلى JSON وXML. بسبب وجود بيانات مكتوبة، بإمكان استعلام UFX" الاستعلام عن البيانات منها، وبإمكان واجهة مستخدم العميل الربط بها.

لأسباب عملية وأسباب تتعلق بالأداء، يتم تطبيق المجموعة في الذاكرة على كائن Entity في SDK تطبيقات Dynamics 365.

تحتوي المجموعة النموذجية على قيمتين.

في الذاكرة:

المفتاح	القيمة	اكتب
الاسم	أشرف	سلسلة
السن	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 على شكل مجموعات UFX قائمة على XML. بإمكان الخصائص في المجموعة أن تحتوي على توجيهات UFX الاستعلام عن البيانات ديناميكيًا. يتم تنفيذ استعلام UFX على الكائنات في الذاكرة، وليس XML. وحدها التوجيهات تكون مكتوبة بلغة XML. ويمكن سلسلة إخراجها إلى JSON أو XML.

يحدد استعلام UFX التالي الخاصية accounts في المجموعة التي تتضمن توجيه UFX source. ويؤدي هذا إلى تنفيذ 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>

يأخذ توجيه UFX select تعبير 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 لعبور البيانات وتحديد قيم منها.

يرى تعبير XPath المحدد في توجيه UFX البيانات في المجموعة مشابهة لهيكل المجموعة في نموذج XML المسلسل. ومع ذلك، يتم تخزين البيانات في كائنات NET. في الذاكرة (في مثيلات من النوع Entity وEntityCollection) وليس في مستندات XML.

الملحق أ: مرجع من النوع UFX

ملاحظة: تدعم كافة أنواع UFX بيانات التعريف ufx-type وufx-formatvalue. يتم وصف بيانات تعريف إضافية إلى جانب كل نوع في الجدول التالي.

اسم UFX	كود نوع السمة	اسم NET.	بيانات تعريف UFX
منطقي	منطقي	منطقي
العدد الصحيح	‏‏عدد صحيح	Int32
طويل	عدد صحيح كبير	Int64
مزدوج	‏‏مزدوج	‏‏مزدوج
عشري	عشري	عشري
التاريخ والوقت	التاريخ والوقت	التاريخ والوقت
guid	Uniqueidentifier	المعرف الفريد العمومي
سلسلة	مذكرة	السلسلة
المال	نقود	نقود
خيار	قائمة اختيار	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	تنفيذ عنصر XML المضمن <fetch> وتعيين النتيجة إلى الخاصية
ufx:select	XPath	تنفيذ تعبير XPath وتعيين النتيجة إلى الخاصية عند الاستعلام عن bag أو list، يمكنك تحديد تابع اختياري bag في نموذج XML لتحويل نتيجة تعبير XPath

توجيهات UFX FetchXML

العنصر	السمة	Value	الوصف
جميع العناصر	ufx:if	XPath	اختبار تعبير XPath وحذف عنصر XML فقط في حالة نجاح الاختبارات
ufx:apply	select	XPath	الدوران حول مجموعة عقد تم إرجاعها بواسطة تعبير XPath وإخراج عناصر XML التابعة مرة واحدة لكل عقدة
ufx:value	select	XPath	تنفيذ تعبير XPath وإخراج النتيجة في عنصر XML الحالي
ufx:value	attribute	اسم السمة	تعيين نتيجة تعبير XPath إلى اسم السمة المحددة على عنصر XML الحالي

الملحق ج: دالات UFX XPath

يضيف UFX عددًا من الدالات الجديدة بالإضافة إلى تلك المتوفرة في XPath.

datetime()

• datetime(): إرجاع الوقت الحالي حسب توقيت UTC

list()

• list(bag | list, ...[bag | list]): يأخذ عددًا من قيم bag أو list كإدخال ويقوم بتسويتها في list واحدة

lookup-to-list()

• lookup-to-list(lookup, ...[lookup]): يأخذ عددًا من قيم lookup، ويحول كل واحدة منها إلى bag مع مجموعة بيانات التعريف ufx-id وufx-logicalname ويقوم بتسويتها في list واحدة

option-to-list()

• option-to-list(option, ...[option]): يأخذ عددًا من قيم option، ويحول كل واحدة منها إلى bag مع خاصية option واحدة، ويقوم بتسويتها في list

order()

• order(قائمة، سلسلة، منطقي): ترتيب قائمة حسب خاصية في كل مجموعة. تم تعيين الخاصية في الوسيطة 2، تم تحديد تنازلي في الوسيطة 3.
• order(قائمة، قائمة): ترتيب قائمة حسب ترتيبات فرز متعددة محددة كقائمة في الوسيطة 2. بإمكان كل bag في القائمة الثانية أن تحتوي على name وخاصية descending

iif()

• iif(أي، أي، أي): إذا كانت قيمة الوسيطة 1 تساوي true، ترجع الوسيطة 2، وإلا ترجع الوسيطة 3

الملحق د: متغيرات UFX XPath

الاسم	الوصف
$input	bag متوفرة لاستعلام UFX مع قيم إدخال
$null	ثابت فارغ. يؤدي تحديد $null على خاصية إلى إزالة الخاصية من المجموعة
$current	الإشارة إلى المجموعة الحالية الجاري معالجتها بواسطة استعلام UFX

راجع أيضًا

فهم وتخصيص مطابقة الموارد في Universal Resource Scheduling

ملاحظات حول الإصدار لإمكانية توسيع Universal Resource Scheduling