تعریف مجموعه گزینه در Model-Driven

شناسهٔ شِما: model-driven-option-set@1 شِمای قابل‌خواندن توسط ماشین: model-driven-option-set.schema.json

بازنمایی مرجع یک مجموعه گزینه — فهرستی نام‌دار و قابل‌بازاستفاده از مقادیر مجازی که یک فیلد می‌تواند بگیرد (بخش 6.14). Dataverse همین مفهوم را Choice می‌نامد. به شکل یکسان اعتبارسنجی می‌شود، چه از طراح بیاید، چه از یک فراخوانی API، چه از یک دستیار هوش مصنوعی، و چه از یک وارد کردن راه‌حل.

شکل

فیلد	نوع	اجباری	یادداشت‌ها
logicalName	string	بله	پیشوند ناشر در ابتدا، با snake-case کوچک (مثلاً par_invoicestatus).
displayName	string	بله	نام خوانا برای انسان.
description	string	خیر	اینکه مجموعه برای چیست.
publisherPrefix	string	خیر	پیشوند ناشر مالک. حمل می‌شود تا تعریف، خودش ناشرش را نام ببرد و کار استنتاج آن از روی نام منطقی بر دوش وارد‌کننده نیفتد.
optionValueBase	integer	بله	مبنای مقدار گزینهٔ ناشر مالک، و value هر گزینه در آن مطلق است — 110000001، نه 1. از ۲۰۲۶-۰۹-۱۲ اجباری است: تعریفی بدون آن هنگام وارد کردن رد می‌شود، و نخستین راهکار محصول همین‌طور نوشته شده بود و همهٔ آزمون‌ها را گذرانده بود.
nextOptionValue	integer	خیر	نشانهٔ بیشینهٔ مجموعه — مقدار بعدی‌ای که واگذار خواهد کرد. به جای اینکه از options استنتاج شود ذخیره می‌شود، تا شمارهٔ یک گزینهٔ بازنشسته هرگز دوباره صادر نشود. پایین‌تر را ببینید.
options	array	بله	گزینه‌ها، به ترتیب نمایش. دست‌کم یکی — مجموعه‌ای که کسی نتواند از آن چیزی برگزیند، مجموعه نیست.

گزینه

فیلد	نوع	اجباری	یادداشت‌ها
value	integer	بله	مقداری که ذخیره می‌شود. پلتفرم آن را از مبنای ناشر مالک تخصیص می‌دهد و پس از تخصیص تغییرناپذیر است. کمینه ۱ — پایین‌تر را ببینید.
displayName	string	بله	آنچه کاربر برمی‌گزیند.
description	string	خیر	معنای گزینه.

چرا مقادیر عددهای بزرگ‌اند و هرگز 0/1/2 نیستند

value همان چیزی است که پایگاه داده واقعاً ذخیره می‌کند. هر ناشر مالک بازه‌ای از عددهاست (مثلاً 270150000–270159999)، و گزینه‌های یک مجموعه رو به بالا از مبنای آن شماره‌گذاری می‌شوند:

270150000, 270150001, 270150002, …

اگر هر ناشر از 0 آغاز می‌کرد، وارد کردن راه‌حل‌های دو ناشر در یک محیط بی‌سروصدا باعث می‌شد «Draft» یک ناشر معنای «Cancelled» ناشر دیگر را بدهد — چون هر دو به‌صورت 0 ذخیره می‌شدند. بازهٔ به‌ازای‌هر‌ناشر این را ناممکن می‌کند. این همتای عددی پیشوند ناشر است، که همین کار را برای نام‌ها انجام می‌دهد.

دو قاعده از این برمی‌آید، و هر دو اعمال می‌شوند:

• شما مقادیر را انتخاب نمی‌کنید. API ساخت هیچ مقداری نمی‌گیرد؛ پلتفرم مقدار بعدی را از بازهٔ ناشر تخصیص می‌دهد. در به‌روزرسانی، گزینه‌ای که مقداری حمل می‌کند گزینه‌ای است که دارید نگه می‌دارید — مقداری ناشناخته رد می‌شود، نه پذیرفته.
• یک مقدار هرگز تغییر نمی‌کند. تغییر نام یک گزینه رایگان و بی‌خطر است؛ تغییر شمارهٔ آن هر رکوردی را که پیشاپیش آن را ذخیره کرده به جای دیگری نشانه می‌رود. شمارهٔ گزینهٔ برداشته‌شده به جای صدور دوباره، بازنشسته می‌شود.

وارد کردن و خروجی گرفتن

مقادیر همراه تعریف سفر می‌کنند؛ هنگام وارد کردن دوباره تخصیص داده نمی‌شوند. رکوردهای محیط مبدأ پیشاپیش آن‌ها را نگه داشته‌اند، پس راه‌حلی که در Test یا Prod وارد می‌شود باید با Dev هم‌داستان باشد که 270150001 چه معنایی دارد.

nextOptionValue به همین دلیل، یک گام دورتر، سفر می‌کند. این مقدار بعدی‌ای است که مجموعه واگذار خواهد کرد، و به جای اینکه از روی گزینه‌های موجود درآورده شود، ذخیره می‌شود. اگر گزینه‌ای برداشته شده باشد، این نشانه بالای شماره‌ای می‌ماند که آن گزینه داشت — پس آن شماره به جای اینکه به گزینهٔ تازهٔ بعدی داده شود بازنشسته می‌گردد، و این مهم است چون ممکن است رکوردی جایی هنوز آن را نگه داشته باشد. محیط وارد‌کننده‌ای که این نشانه را دوباره از روی گزینه‌های دریافتی درمی‌آورد، دقیقاً همین محافظت را خنثی می‌کند. تعریفی بدون nextOptionValue به نشانهٔ استنتاج‌شده بازمی‌گردد، که برای سندی که هرگز یکی را ثبت نکرده، بهترین پاسخ موجود است.

یک وارد کردن، همان چیزی را وارسی می‌کند که تخصیص در حالت عادی تضمین می‌کرد: هر مقدار باید درون بازهٔ ناشر بنشیند، هیچ دو گزینه‌ای نباید یک مقدار یا یک برچسب را شریک باشند، و نام منطقی باید در محیط مقصد آزاد باشد. مقداری از بازهٔ ناشری دیگر به جای ذخیره‌شدن رد می‌شود — پذیرفتنش همان تصادمی را می‌کاشت که طرح بازه‌ها برای جلوگیری از آن وجود دارد.

گره‌زدن یک فیلد به یک مجموعه

یک فیلد موجودیت با نام به یک مجموعه ارجاع می‌دهد، در تعریف موجودیت:

{ "logicalName": "par_status", "displayName": "Status", "dataType": "OptionSet", "optionSet": "par_invoicestatus" }

ستون یک bigint است که مقدار گزینهٔ برگزیده را نگه می‌دارد. سرور نوشتنی را که مقدارش یکی از گزینه‌های مجموعه نباشد رد می‌کند.

نمونه

{
  "logicalName": "par_invoicestatus",
  "displayName": "Invoice Status",
  "description": "The lifecycle of an invoice",
  "publisherPrefix": "par",
  "optionValueBase": 270150000,
  "nextOptionValue": 270150003,
  "options": [
    { "value": 270150000, "displayName": "Draft", "description": "Not yet sent to the customer" },
    { "value": 270150001, "displayName": "Sent" },
    { "value": 270150002, "displayName": "Paid" }
  ]
}