انتشار و فراخوانی Process در ESB

ورود از نسخهٔ درست

در لیست فرآیندها شناسهٔ نسخه و خانواده را کنترل کنید و آیکن ESB ردیف مورد نظر را بزنید. جدول سرویس‌های آن نسخه، شناسه، نام لاتین و فعال‌بودن را نشان می‌دهد. تعداد «وب‌سرویس‌ها» در لیست فرآیندها تعداد تعریف‌های متصل است، نه شمار فراخوانی‌ها.

بررسی سازگاری مدل

اگر ساختار مدل برای این مسیر مناسب نباشد، جدول سازگاری نام Node، تعداد فعلی و تعداد مورد نیاز را نشان می‌دهد. از «ویرایش فرآیند» وارد مدل شوید، مسئله را اصلاح و نسخه را ذخیره کنید، سپس ESB را دوباره باز کنید.

این محدودیت‌ها متعلق به ساخت ESB از این پنجره‌اند. وجود یک نماد در BPMN یا کاربرد آن در فرآیند معمولی، سازگاری‌اش با اجرای سرویس‌مانند را ثابت نمی‌کند. به‌ویژه نام کلی TimerEvent و SignalEvent در گزارش اعتبارسنجی را با پشتیبانی/عدم پشتیبانی تمام انواع رویدادها در کل محصول یکی نگیرید.

مدل مناسب برای ESB

ESB از Process یک API قابل فراخوانی می‌سازد. فرآیند مقصد باید دقیقاً یک Message Start Event و دقیقاً یک End Event داشته باشد و بدون توقف انسانی یا انتظار پیام، از ابتدا تا پایان اجرا شود. User Task، Graph Mobile Task، Receive Task، Timer Intermediate Catch، Signal Intermediate Catch و Call Activity از Nodeهای منتظرند و در این مدل مجاز نیستند.

اگر پیام پیش‌نیاز نمایش داده شد، مدل و نسخهٔ فرآیند را اصلاح و سپس به صفحهٔ ESB برگردید. پس از اعتبارسنجی، فهرست ESBها و فرمان افزودن در دسترس قرار می‌گیرد. این قابلیت با دکمهٔ غیرفعال «انتشار فرآیند» در فهرست یکی نیست.

نام، روش درخواست و نوع پاسخ

1. «افزودن» را انتخاب و نام لاتین سرویس را وارد کنید. همین نام در مسیر فراخوانی دیده می‌شود.
2. متد درخواست را از GET یا POST مطابق قرارداد مصرف‌کننده انتخاب کنید.
3. نوع محتوای پاسخ را text/plain یا application/json تعیین کنید.
4. فعال‌بودن و «مجوز استفاده ناشناس» را با سیاست سرویس تنظیم کنید.
5. توضیح سرویس، ورودی مورد انتظار و معنی نتیجه را بنویسید؛ این توضیحات بخشی از مستند مصرف‌کننده است.

فعال‌بودن سرویس و مجوز کاربر دو کنترل جدا هستند. فعال‌کردن ناشناس را راهی برای حل خطای مجوز کاربر ندانید. وقتی روش، نام یا نوع خروجی را عوض می‌کنید، مصرف‌کننده باید قرارداد تازه را دریافت کند.

نام API، متد، پاسخ و هویت فراخوان

«نام لاتین» ESB در آدرس API اثر دارد؛ فقط نامی برای شناسایی داخلی مدیر نیست. برای قرارداد مصرف‌کننده، نام مناسب و پایدار انتخاب و متد GET یا POST را تعیین کنید. «نوع محتوای پاسخ» نیز می‌تواند text/plain یا application/json باشد.

اگر «مجوز استفاده ناشناس» فعال نباشد، فراخوان باید Token معتبر را مطابق مستند تولیدشده، از مسیر Authorization با قالب Bearer یا privateToken پشتیبانی‌شده بفرستد. هویت Token علاوه بر اعتبار احراز هویت باید در Laneِ همان Message Start مجاز باشد؛ Token یک کاربر دیگر صرفاً به دلیل معتبر بودن، دسترسی شروع این Process را ندارد.

با فعال‌کردن مجوز ناشناس، فراخوان بدون Token کاربر ممکن می‌شود و هویت ناشناس در اجرای فرآیند و لاگ آن ثبت می‌شود. این حالت را آگاهانه متناسب با قرارداد عمومی سرویس انتخاب کنید. متن «توضیحات» نیز در مستندات تولیدشدهٔ ESB قرار می‌گیرد؛ هدف API، معنای ورودی‌ها و خروجی را برای مصرف‌کننده روشن بنویسید.

تعریف و نگاشت ورودی‌ها

متغیرهای مورد نیاز را در فرآیند تعریف کنید و مدل را ذخیره کنید. سپس در بخش پارامترهای ESB از فهرست «افزودن پارامتر» متغیر مقصد را انتخاب کنید. نام داخلی متغیر ثابت نمایش داده می‌شود؛ «تغییر نام به» نام بیرونی آن در درخواست سرویس است.

نوع‌های دیده‌شده در انتخاب‌گر عبارت‌اند از Boolean، Byte، SByte، Char، Decimal، Double، Single، Int32، UInt32، Int64، UInt64، Int16، UInt16، String، Object، Guid و DateTime. نوع را با مقدار مصرف‌شده در فرآیند تطبیق دهید؛ انتخاب Object به معنی پذیرش هر متن نامعتبر به‌عنوان JSON نیست.

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

انتخاب ورودی عمومی از Variableهای داخلی

فهرست «افزودن پارامتر» از Variableهای تعریف‌شدهٔ همان Process ساخته می‌شود. فقط Variableهایی را اضافه کنید که باید از بیرون مقدار بگیرند؛ لازم نیست تمام متغیرهای داخلی در API منتشر شوند. برای نمونه، از ده Variable می‌توانید فقط دو ورودی عمومی بسازید و متغیرهای داخلی را در همان فرآیند نگه دارید.

برای هر پارامتر، «نام پارامتر» به Variable داخلی متصل است و «تغییر نام به» نام بیرونی قرارداد را تعیین می‌کند. در تصویر، var2 با نام عمومی Variable2 عرضه شده است. مقدار پیش‌فرض برای نبود ورودی و نوع مقدار برای قرارداد و تبدیل داده تنظیم می‌شود. نام بیرونی، نام Variable داخلی را تغییر نمی‌دهد.

نوع را مطابق مقدار واقعی انتخاب کنید؛ برای مثال، دادهٔ ساختاریافته‌ای که باید به Object تبدیل شود با رشتهٔ ساده یکسان نیست. در مستندات و نمونهٔ درخواست، همان نام عمومی و نوع انتخاب‌شده باید استفاده شود.

از End Event تا خروجی سرویس

خروجی ESB از خروجی‌های تعریف‌شده در End Event انتخاب می‌شود. ابتدا در رویداد پایان کلید خروجی و مقدار آن را تنظیم کنید؛ مقدار می‌تواند از متغیرهای فرآیند بیاید. سپس در ESB آن کلید را به فهرست خروجی‌ها اضافه و نام بیرونی، مقدار پیش‌فرض و نوع را تعیین کنید.

در مثال، کلید داخلی OutOf2 با نام بیرونی O2 و نوع Int32 منتشر شده است. مقدار 555 در کنترل پیش‌فرض دیده می‌شود؛ این تصویر به‌تنهایی نشان نمی‌دهد null، رشتهٔ خالی یا خطای تبدیل همگی به همین مقدار تبدیل می‌شوند. این سه حالت باید مستقل آزمون شوند.

انتخاب خروجی عمومی از End واحد

فهرست خروجی‌های ESB از متغیرهای خروجی همان End واحد گرفته می‌شود. هنگام فراخوان، پارامترهای ورودی Variableهای متناظر را مقداردهی می‌کنند، Process اجرا می‌شود و نتیجهٔ End بر پایهٔ نگاشت خروجی ESB بازگردانده می‌شود. می‌توانید از میان بیست خروجی End فقط یک خروجی را برای این API منتشر کنید.

در نگاشت خروجی ESB، مقدار End به‌صورت رشته دریافت و با «نوع مقدار» منتخب تبدیل می‌شود؛ این شرحِ نگاشت ESB را به همهٔ ساختارهای پاسخ API و سطح‌های Verbosity تعمیم ندهید. نام عمومی و مقدار پیش‌فرض نیز قابل تنظیم‌اند؛ در مثال، اگر خروجی End خالی یا بدون مقدار باشد، مقدار پیش‌فرض خروجی مصرف می‌شود. تبدیل نوع را متناسب با مقدار واقعی بررسی کنید؛ نوشتن نوع عددی، یک رشتهٔ غیرقابل تبدیل را خودبه‌خود به عدد معنادار تبدیل نمی‌کند. نمونهٔ کامل زیر ورودی ساختاریافتهٔ var1 از نوع Object، ورودی var2 با نام عمومی Variable2 و یک خروجی منتخب از نوع Int32 با مقدار پیش‌فرض 555 را نشان می‌دهد.

یک Process می‌تواند چند ESB داشته باشد. هر ESB می‌تواند نام، متد و زیرمجموعهٔ ورودی/خروجی متناسب با مصرف‌کنندهٔ خود داشته باشد؛ تفاوت قرارداد عمومی به معنی نیاز به کپی‌کردن کل مدل Process نیست.

ذخیره و مدیریت سرویس‌های نسخه

پس از کنترل نگاشت‌ها، «ذخیره» را بزنید و بازگشت سرویس به فهرست را بررسی کنید. هر نسخه می‌تواند چند تعریف ESB داشته باشد. سرویس هدف را از نام و شناسهٔ خود پیدا کنید و از عملیات ردیف، ویرایش، حذف یا مستند را انتخاب کنید.

خواندن سند تولیدشده

سند سرویس وضعیت فعال، اجازهٔ ناشناس، گیرندگان مجاز، URL، Method، Content-Type، ساختار درخواست و پاسخ، خطاها و نمونه‌های فراخوانی را کنار هم نشان می‌دهد. قبل از ارسال این سند به مصرف‌کننده، نام کاربران و سازمان را متناسب با مخاطب حذف کنید و نشانی استقرار مقصد را جایگزین نشانی نمونه کنید.

نمونهٔ این سند آدرس /esb/run/CreatingAnEsb و روش POST دارد. نام نهایی به تعریف شما وابسته است؛ آدرس و درگاه localhost نمونه را به محیط عملیاتی منتقل نکنید. پاسخ application/json این نمونه شیئی مانند {"O2":0} است، نه لزوماً پوستهٔ پاسخ RunProcess عمومی.

ورودی و خروجی نمونه با نوع درست

{
  "var1": { "RequestCode": "DEMO-001", "Quantity": 2 },
  "Variable2": "نمونه آموزشی"
}

{ "O2": 0 }

برای var1 که Object تنظیم شده، Object یا Array معتبر بفرستید. بعضی نمونه‌های تولیدشده به‌جای آن رشتهٔ «???» نشان می‌دهند؛ آن placeholder کد آمادهٔ اجرا نیست. String بودن Variable2 نیز با عددی بودن خروجی O2 مستقل است.

مستندات اختصاصی هر ESB

پس از ذخیره، هر ESB در فهرست سه اقدام «مستندات»، «ویرایش» و «حذف» دارد. مستندات را برای همان ESB باز کنید تا آدرس، متد، ورودی‌ها، خروجی‌ها و مجوزهای قرارداد انتخاب‌شده را ببینید؛ اگر دو ESB روی یک Process ساخته‌اید، یکسان‌بودن Process به معنی یکسان‌بودن قرارداد عمومی آن‌ها نیست.

در حالت غیرناشناس، «دسترسی‌های مجاز» از Laneِ Message Start خوانده می‌شود و بخش دریافت Token/ورود در مستندات در دسترس است. با مجوز ناشناس، این نمایش متناسب با قرارداد ناشناس تغییر می‌کند و راهنمای دریافت Token کاربر لازم نیست. نمونه‌های curl، C#، fetch و jQuery در تب‌های مستندات، شیوهٔ درخواست همان قرارداد را نشان می‌دهند. برای کد جدید Custom JS در این راهنما، نمونهٔ fetch مبنای پیشنهادی است؛ وجود تب jQuery به معنی الزام استفاده از آن نیست.

برای کپی نمونه، نام پارامترهای عمومی، متد و نوع محتوا را با آخرین تنظیمات ESB هماهنگ نگه دارید و مقدارهای نمونهٔ آدرس یا Token را با اطلاعات محیط خود جایگزین کنید. پس از تغییر نگاشت، مستند همان ESB را دوباره باز کنید؛ نمونهٔ یک قرارداد قدیمی مبنای مطمئنی برای ورودی تازه نیست.

توکن، مجوز و خطاهای HTTP

برای سرویس بدون مجوز ناشناس، ابتدا POST /SharedApi/Login را با اطلاعات حساب مجاز فراخوانی کنید. نتیجه باید HasError=false داشته باشد و توکن غیرخالی برگرداند. سند ساختاری، توکن را در Content.Token.PrivateToken نشان می‌دهد. سپس در درخواست ESB یکی از هدرهای privateToken یا Authorization: Bearer <PRIVATE_TOKEN> را مطابق قرارداد به کار ببرید.

متن فارسی خطا را از بدنهٔ پاسخ بخوانید و تحلیل را به StatusDescription محدود نکنید. در Login نیز HasError، Message و MessageException را بررسی کنید. موفقیت دریافت توکن، مجوز همهٔ ESBها را تضمین نمی‌کند.

اختلاف مستند و نمونهٔ تولیدشده: تصویر Fetch و jQuery به authResult.PrivateToken اشاره می‌کند، در حالی که ساختار Login داخل همان سند Content.Token.PrivateToken است. پیش از استفاده، مسیر را با پاسخ واقعی محیط تطبیق دهید. نمونه‌های زیر توکن معتبر دریافت‌شده را ورودی می‌گیرند و گذرواژه‌ای داخل کد قرار نمی‌دهند.

نمونه‌های فراخوانی

نام‌ها، نشانی‌ها و مقادیر زیر آموزشی‌اند. متغیر privateToken باید از جریان احراز هویت مجاز برنامه تأمین شود. نمونه‌های تصویری، محل دریافت الگو در محصول را نشان می‌دهند؛ کد تایپی اصلاح‌شدهٔ زیر، نوع Object و مسیر توکن را روشن می‌کند.

cURL

curl -X POST "https://bpms.example/esb/run/CreatingAnEsb"   -H "Authorization: Bearer <PRIVATE_TOKEN>"   -H "Content-Type: application/json; charset=utf-8"   --data '{"var1":{"RequestCode":"DEMO-001","Quantity":2},"Variable2":"demo"}'   --max-time 60

Fetch با توکن موجود

async function callProcessEsb(privateToken) {
  const response = await fetch("https://bpms.example/esb/run/CreatingAnEsb", {
    method: "POST",
    headers: {
      "Content-Type": "application/json; charset=utf-8",
      "Authorization": "Bearer " + privateToken
    },
    body: JSON.stringify({
      var1: { RequestCode: "DEMO-001", Quantity: 2 },
      Variable2: "demo"
    })
  });
  const body = await response.text();
  if (!response.ok) throw new Error(`HTTP ${response.status}: ${body}`);
  return JSON.parse(body); // برای قرارداد application/json این سرویس
}

jQuery با توکن موجود

function callProcessEsbWithJQuery(privateToken) {
  return $.ajax({
    url: "https://bpms.example/esb/run/CreatingAnEsb",
    type: "POST",
    headers: { Authorization: "Bearer " + privateToken },
    contentType: "application/json; charset=utf-8",
    dataType: "json",
    data: JSON.stringify({
      var1: { RequestCode: "DEMO-001", Quantity: 2 },
      Variable2: "demo"
    })
  });
}

C# در کلاینت مستقل

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

public static async Task<string> CallProcessEsbAsync(string privateToken)
{
    using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(60) };
    client.DefaultRequestHeaders.Authorization =
        new AuthenticationHeaderValue("Bearer", privateToken);
    var body = new {
        var1 = new { RequestCode = "DEMO-001", Quantity = 2 },
        Variable2 = "demo"
    };
    using var content = new StringContent(
        JsonSerializer.Serialize(body), Encoding.UTF8, "application/json");
    using var response = await client.PostAsync(
        "https://bpms.example/esb/run/CreatingAnEsb", content);
    var text = await response.Content.ReadAsStringAsync();
    if (!response.IsSuccessStatusCode)
        throw new Exception($"HTTP {(int)response.StatusCode}: {text}");
    return text;
}

این نمونهٔ C# برای کلاینت مستقل با HttpClient و System.Text.Json است؛ API جدیدی برای Script Task معرفی نمی‌کند. سازگاری کتابخانه‌ها و نسخهٔ .NET مصرف‌کننده را در پروژهٔ مقصد کنترل کنید.

آزمون و رفع اشکال قرارداد

در آزمون پذیرش، ورودی معتبر، حذف پارامتر اختیاری، null، نوع ناسازگار، توکن نامعتبر و حساب فاقد مجوز را مستقل ثبت کنید. GET و POST و دو نوع محتوای پاسخ را فقط برای قراردادهایی که واقعاً تعریف کرده‌اید آزمایش کنید. نتیجهٔ موفق HTTP را با نتیجهٔ مورد انتظار فرآیند و خروجی End Event تطبیق دهید.