امروزه بسیاری از تولیدکنندگان نرم افزارها، برای ارتباط و تبادل اطلاعات با نرم افزارهای دیگر در محیط وب از وب سرویسهای مبتنی بر استاندارد *REST استفاده می کنند. به همین منظور شرکت نوسا نیز برای امکان تعامل با سیستمهای دیگر نرم افزاری، این استاندارد را در سیستم مدیریت فرایندها پیاده سازی کرده است. بنابراین ابتدا بهتر است با ساختار کلی REST آشنا شویم.
*: در این مستند فرض شده است که مخاطب با مفاهیم اصلی و ساختار استاندارد REST آشنایی دارد بنابراین در صورت عدم آشنایی با موضوع بهتر است ابتدا به مستندات زیر مراجعه کنید:
API (رابط برنامه نویسی سیستمهای کاربردی) چیست؟
تفاوتهای میان SOAP و REST
نحوه کار با RESTful API
معماری REST
در هر ارتباط از نوع REST چهار جزء زیر وجود دارد:
- سرور REST: ارائه کننده خدمات، سرور نامیده می شود. هر سرور REST از طریق یک شناسه یونیک بنام آدرس پایه (baseURL) قابل دسترسی است.
- خدمات ارائه شده : هر خدمات خاص نیز با یک شناسه یونیک ارائه می شود که ترکیبی از آدرس پایه به اضافه یک عبارت مختص آن خدمات است.
- کلاینت REST: مشتری یا گیرنده خدمات را کلاینت می نامیم.
- درخواست/ پاسخ: درخواستها از کلاینت به سرور فرستاده می شود و پاسخ آنها از سرور به کلاینت ارسال می شود. این درخواستها/ پاسخها با فرمت خاصی تولید می شود که قواعد آن توسط ارائه کننده وب سرویس تعیین می شود.
در این مستند ما به معرفی کلاینت REST سیستم مدیریت فرایندها و نیز نحوه تولید درخواستها توسط این کلاینت می پردازیم.
کلاینت REST سیستم مدیریت فرایندها
سیستم مدیریت فرایندها با استفاده از این کلاینت می تواند از ارائه کننده سرویسهای وب، خدمات مورد نظر خود را دریافت نماید. اولین گام برای استفاده از خدمات وب سرویسها، برقراری ارتباط با وب سرویس می باشد:
گام اول: برقراری ارتباط با وب سرویس
بطور کلی، سیستم مدیریت فرایندها برای اتصال به وب سرویس ها از تابع CreateRestClient از موجود WorkConnUtils استفاده می کند. الگوی این تابع به شکل زیر است:
function CreateRestClient(baseURL): WorkRestClient
همانطور که می بینید، این اتصال از طریق آدرس پایه سرور (baseURL) انجام می شود. خروجی این تابع، یک موجود از نوع WorkRestClient است. در واقع تمام عملیات استاندارد تعامل با وب سرویسها، اعم از تولید متن درخواست، ارسال درخواست، دریافت پاسخ و ... از طریق ویژگی ها و متدهای این موجود انجام می شود. بنابراین در اینجا بهتر است ابتدا با ساختار این موجود آشنا شویم:
WorkRestClient- ارائه کننده ابزارهای کلاینت REST
همانطور که گفته شد، برقراری تعامل با وب سرویسها از طریق ابزارهای این موجود انجام می شود. الگوی کلی این موجود به شکل زیر است:
WorkRestClient = {
BaseURL String/RO
Method Number/RW
Response Object
function AddHTTPHeader(name, value)
function AddParameter(name, value)
function AddBody(body)
function Execute(): Boolean
}
همانطور که ملاحظه می کنید این موجود شامل سه ویژگی (Property) و چهار تابع به شرح زیر است:
ویژگی (Property)های WorkRestClient
BaseURL (آدرس پایه): این ویژگی آدرس پایه خدمات مورد نظر را نشان می دهد و غیرقابل ویرایش است. یادآوری می شود که در هنگام اتصال از طریق تابع CreateRestClient با وب سرویس، این آدرس تعیین می شود.
Method (متد): منظور متدهای HTTP است که از طریق آنها می توانیم با وب سرویسها تعامل کنیم. پرکاربردترین این متدها به شرح زیر است:
GET : این متد برای دریافت منابع از وب سرویس به کار می رود
POST: این متد برای ارسال داده ها به وب سرویس می باشد.
این ویژگی قابل ویرایش است و به این معنی است که توسط کاربر کلاینت تعیین می شود. برای تعیین متد باید کد مربوط به آن را در این ویژگی تعیین کنید. این کد از نوع عدد صحیح است که در ادامه و در مثالها توضیح داده خواهد شد.
نکته مهم: متدهای GET و POST امکان تعامل با انواع وب سرویسها را دارند و محدود به وب سرویسهای از نوع REST نیستند بنابراین موجود WorkRestClient با پشتیبانی از این متدها، محدود به سرورهای REST نیست و می تواند با هر وب سرویسی که متدهای GET و POST را پشتیبانی می کند ارتباط برقرار نماید.
Response (پاسخ): پاسخی که از سرور دریافت می شود در این ویژگی ذخیره می شود. این ویژگی یک Object است که خود دارای چند مشخصه است که اطلاعات مختلف پاسخ را شامل می شود. ساختار این Object به شکل زیر است:
Response = {
StatusCode Number/RO
StatusText String/RO
Content String/RO
}
به این ترتیب، ویژگی (Property)های پاسخ عبارتند از : کد وضعیت (StatusCode) ، متن وضعیت (StatusText) و متن پاسخ (Content)
توابع WorkRestClient
از این توابع برای تولید متن درخواست و ارسال آن به سرور استفاده می کنیم. این توابع به شرح زیرند:
AddHTTPHeader(name, value) : برای تعیین هدرها از این تابع استفاده می کنیم. در این تابع برای هر هدر یک نام (name) و یک مقدار (value) را تعیین می کنیم.
AddParameter(name, value) : برای تعیین مقدار پارامترها از این تابع استفاده می کنیم. در این تابع، برای هر پارامتر یک نام (name) و یک مقدار (value) تعیین می کنیم.
AddBody(body) : از این تابع برای افزودن بدنه (body) داده ها به درخواست استفاده می کنیم. توضیح این که در اینجا فرمت body از نوع JSON Object است.
توضیح: فرمت داده های ارسالی را مستندات وب سرویس مشخص می کند. برای مثال یک وب سرویس ممکن است اطلاعات نام کاربری و کلمه عبور را به شکل مقدار پارامتر (Parameter value) بخواهد که در این حالت از AddParameter استفاده می کنیم و وب سرویس دیگر ممکن است همین اطلاعات را در قالب JSON بخواهد که در این صورت از AddBody استفاده می کنیم. لازم به توضیح است که وب سرویسهای REST معمولا از قالب JSON برای درخواستها و پاسخها استفاده می کنند. در ادامه مطلب، این مفاهیم در قالب مثالهای واقعی بیشتر توضیح داده شده است.
Execute : با استفاده از این تابع، درخواست (Request) به سرور ارسال می شود و سرور پس از پردازش ، پاسخ(Response) را به کلاینت برمی گرداند.
مثال: دریافت خدمات از API سامانه ارسال پیامک ایده پیام
1-دریافت مانده اعتبار مشتری از وب سرویس اعتبار (Credit)
درخواست مانده اعتبار از متد GET استفاده می کند و تابع اجرایی آن به شکل زیر است:
برای آشنایی با نحوه عملکرد این تابع، آن را بخش به بخش تحلیل می کنیم:
var clt = WorkConnUtils.CreateRestClient("http://185.112.33.62/api/...rest/my/credit" ) ;
شناسه یونیک این وب سرویس http://185.112.33.62/api/v1/rest/my/credit می باشد. در اینجا قبل از هر چیز یک اتصال به وب سرویس مورد نظر ایجاد می کنیم و در نتیجه این کار یک WorkRestClient ایجاد می شود که آن را در متغیر clt ذخیره می کنیم.
if (!clt) throw "Could not create REST client!";
در اینجا تعیین می کنیم که اگر اتصال برقرار نشود، اجرای تابع متوقف شده و این مساله به کاربر اعلام شود.
clt.Method = RestEnums.RequestMethod.GET;
در این مرحله، متد HTTP مورد نظر خود را انتخاب می کنیم که در اینجا متد GET را برای دریافت اطلاعات انتخاب می کنیم. ملاحظه می کنید که در اینجا برای خوانایی برنامه، بجای اینکه کد عددی GET را وارد کنیم از ویژگی RequestMethod از موجودی بنام معین کننده متدها) (RestEnums استفاده شده است. الگوی RestEnums را در زیر مشاهده می کنید:
RestEnums = {
RequestMethod = {
POST = 0;
PUT = 1;
GET = 2;
DELETE = 3;
PATCH = 4;
}
}
ملاحظه می کنید که در این الگو، با انتخاب هر متد HTTP کد عددی معادل آن متد، در برنامه ذخیره می شود.
clt.AddHTTPHeader('username', 'abcd' ) ;
clt.AddHTTPHeader('password', 'abcd1234' ) ;
در این مرحله، نام و کلمه عبور کاربری را که می خواهیم مانده اعتبار او را دریافت کنیم، بصورت Header به درخواست اضافه می کنیم. یادآوری می شود که نحوه و فرمت داده های ارسالی، توسط مستندات وب سرویس تعیین می شود و در این مثال، اطلاعات نام کاربری و کلمه عبور را با استفاده از تابع AddHTTPHeader به شکل هدر ذخیره می کنیم.
clt.Execute();
در این مرحله درخواست تکمیل شده و به وب سرویس ارسال و در آنجا پردازش می شود.
var res = JSON.parse(clt.Response.Content);
در این مرحله، متن پاسخ وب سرویس (clt.Response.Content) در یک متغیر از نوع Object بنام res قرار می گیرد. همانطور که قبلا گفته شد، پاسخ وب سرویس (clt.Response) بصورت یک رشته حرفی و در قالب JSON فرستاده می شود لذا در این مرحله برای امکان تفکیک و شناسایی مشخصه های پاسخ باید از متد JSON.parse برای تبدیل رشته حرفی به یک Object استفاده کنیم.
if (!res) throw "Invalid response content!";
در اینجا اگر پاسخ مناسب و معتبری از وب سرویس دریافت نشود، برنامه متوقف شده و پیغامی مبنی بر نامعتبر بودن پاسخ ظاهر می شود.
if (res.status == 200) {
throw “credit: “ + res.result.value;
} else throw res.message;
برای درک این بخش از برنامه، ابتدا باید با ساختار پاسخ در این وب سرویس خاص آشنا شویم. طبق مستندات وب سرویس، ساختار پاسخ به شکل زیر است:
همانطور که می بینید، متغیر res دارای یک مشخصه وضعیت (status) است که کد وضعیت پاسخ را برمی گرداند. کد 200 به معنی صحیح و معتبر بودن ساختار پاسخ است. در این حالت پاسخ شامل یک مشخصه دیگر بنام result شامل مشخصه value خواهد بود که متن پاسخ دریافت شده (در اینجا مقدار مانده اعتبار کاربر) است. در غیر این صورت اگر کد وضعیت هر عدد دیگری غیر از 200 باشد به معنی نامعتبر بودن پاسخ است که در این حالت ساختار پاسخ به شکل زیر است:
ملاحظه می کنید که برای پاسخهای نامعتبر، بجای result یک message وجود دارد که خطای صورت گرفته را نمایش خواهد داد.
حال که با ساختار پاسخ در این وب سرویس آشنا شدیم می توانیم این بخش از برنامه را بهتر تفسیر و درک کنیم:
if (res.status == 200) {
throw “credit: “ + res.result.value;
} else throw res.message;
در این قسمت تعیین شده است که اگر پاسخ معتبر بود، آنگاه مقدار مانده اعتبار کاربر (res.result.value) با برچسب credit نمایش داده شود و در غیر این صورت متن خطای (res.message) پاسخ نمایش داده شود.
2- ارسال پیامک از طریق وب سرویس ارسال (Send)
سامانه ایده پیام برای ارسال پیامک دو نوع وب سرویس ارائه کرده است. یک وب سرویس از استاندارد SOAP و وب سرویس دیگر از استاندارد REST استفاده می کنید. در ادامه برای هر وب سرویس یک مثال ذکر شده است:
2-1 استفاده از وب سرویس تحت SOAP
این وب سرویس داده های درخواست از نوع POST را از طریق مقادیر پارامترها دریافت می کند. برای نمونه به مثال زیر توجه کنید:
مانند مثال قبل، در سطر اول ارتباط با وب سرویس برقرار می شود و در نتیجه آن، یک موجود WorkRestClient ایجاد می شود که در متغیری بنام clt قرار می گیرد. و در سطر دوم تعیین می شود که اگر کلاینت REST ایجاد نشد آنگاه برنامه متوقف شده و این پیغام برای کاربر نمایش داده شود. بنابراین تحلیل را از سطر سوم آغاز می کنیم:
clt.Method = RestEnums.RequestMethod.POST;
از آنجایی که ارسال پیامک یک درخواست از نوع POST است لذا در این سطر متد POST تعیین شده است.
clt.AddParameter('username', 'abcd' ) ;
clt.AddParameter('password', 'f88528a47ea841' ) ;
clt.AddParameter('from', '90008748' ) ;
clt.AddParameter('to', '09123456789' ) ;
clt.AddParameter('text', 'تست لغو 11' ) ;
در این قسمت، داده های لازم برای ارسال پیامک شامل username(نام کاربری)، (password)کلمه عبور، from(شماره تلفن فرستنده)، to(شماره موبایل گیرنده) و text(متن پیامک) را از طریق تابع AddParameter بصورت مقدار پارامتر های مشخص تعیین می کنیم.
clt.Execute();
در این مرحله، درخواست به سرور وب ارسال و در آنجا پردازش می شود.
throw "StatusCode: " + clt.Response.StatusCode +
"\nStatusText: " + clt.Response.StatusText +
"\nContent: " + clt.Response.Content;
در این مرحله، پاسخ دریافتی در سه سطر نمایش داده می شود. در سطر اول، کد وضعیت پاسخ با برچسب StatusCode ، در سطر دوم شرح وضعیت با برچسب StatusText و در سطر سوم، متن پاسخ با برچسب Content نمایش داده می شود.
2-2 استفاده از وب سرویس REST
در این مثال نیز مانند مثال قبل، می خواهیم درخواست ارسال پیامک را با متد POST ارسال کنیم اما با این تفاوت که در این مثال، وب سرویس از نوع REST است و به همین دلیل بدنه داده های لازم برای ارسال پیامک را با ساختار JSON تعیین و ارسال می کنیم.
در این مثال، همانند دو مثال قبلی، در سطر اول ارتباط با وب سرویس برقرار شده و یک WorkRestClient ایجاد می شود. در سطر دوم تعیین می شود که در صورت عدم برقراری ارتباط، برنامه متوقف شده و پیغامی مبنی بر عدم ایجاد کلاینت REST نمایش داده شود. در سطر سوم نیز متد درخواست از نوع POST تعیین می شود. بنابراین تحلیل را از سطر چهارم شروع می کنیم:
clt.AddHTTPHeader('username', 'abcde' ) ;
clt.AddHTTPHeader('password', 'klmn1234' ) ;
در اینجا نیز مطابق مستندات وب سرویس، داده های نام و کلمه عبور کاربر را به شکل Header ذخیره می کنیم.
var body = {};
body.from = "90008748";
body.recipients = ["09123456789"];
body.message = "rest test\n" + "لغو 11";
همانطور که گفته شد، برای وب سرویسهای REST داده های درخواست، به فرمت JSON Object ارسال می شود لذا در این مرحله یک متغیر Object بنام body ایجاد می کنیم و داده های لازم برای ارسال پیامکها را بصورت مشخصه های این Object ذخیره می کنیم. به این ترتیب، شماره فرستنده را در مشخصه body.from، شماره موبایل گیرنده ها را در مشخصه body.recipients به شکل آرایه وارد می کنیم (توجه کنید که ممکن است بیش از یک گیرنده پیامک داشته باشیم) و در آخر، متن پیامک را در مشخصه body.message ذخیره می کنیم.
clt.AddBody(JSON.stringify(body));
حال برای ارسال داده های بدنه (body) باید آن را از حالت Object به یک رشته حرفی تبدیل کنیم که این کار از طریق JSON.stringify انجام می شود. سپس این رشته حرفی را با استفاده از تابع AddBody به درخواست اضافه می کنیم.
clt.Execute();
در این مرحله، درخواست به وب سرویس ارسال شده و در آنجا پردازش می شود.
var res = JSON.parse(clt.Response.Content);
if (!res) throw "Invalid response content!";
همانند مثال POST قبلی، در این مثال نیز پاسخ ارسالی از وب سرویس (Response.Content) را از طریق JSON.parse به یک Object تبدیل می کنیم و آن را در متغیر res ذخیره می کنیم. سپس اگر به هردلیل پاسخ ارسالی معتبر نبود آنگاه برنامه را متوقف می کنیم و پیغام عدم اعتبار پاسخ را نمایش می دهیم.
if (res.status == 200) {
throw "smsid: " + res.result.id +
"\nstate: " + res.result.status ;
} else throw res.message;
برای تحلیل این قسمت از برنامه ابتدا باید از طریق مستندات، ساختار پاسخ در این وب سرویس را بررسی کنیم. طبق این مستندات، ساختار پاسخ در این وب سرویس به شکل زیر است :
به این ترتیب، پاسخ دارای یک مشخصه بنام کد وضعیت اعتبار پاسخ (status) است که کد 200 به معنی معتبر بودن پاسخ است که در این وضعیت، یک مشخصه دیگر بنام (result) متن پاسخ را در بر دارد. این مشخصه خود دارای دو کلید بنامهای وضعیت ارسال پیامک status و id (شماره یونیک پیامک) می باشد. در صورتی که status برابر با 0 باشد به معنی ارسال موفقیت آمیز است و هر عدد دیگر بیانگر خطای صورت گرفته در هنگام ارسال پیامک است. برای مثال عدد 22 به معنی این است که "شماره موبایل گیرنده اشتباه است". کلید id در واقع شماره یونیک پیامک می باشد. به بیان دیگر، در پاسخ، id های پیامکها به همراه وضعیت ارسال آنها نمایش داده می شود. حال اگر اساسا پاسخ معتبر نبود آنگاه ساختار پاسخ به این شکل خواهد بود:
در این حالت، مقدار status مطابق با استانداردهای http است. برای مثال مقدار 404 به معنی یافت نشدن منبع است. مقدار message نیز یک توضیح کمکی برای عدم اعتبار پاسخ است. حال که با ساختار پاسخ آشنا شدیم می توانیم برنامه را بهتر درک کنیم:
if (res.status == 200) {
throw "smsid: " + res.result.id +
"\nstate: " + res.result.status ;
} else throw res.message;
در این قسمت به شرط معتبر بودن پاسخ، شماره id پیامکها در یک سطر و وضعیت ارسال در سطر دیگر نمایش داده می شود و در غیر این صورت، پیغام خطای عدم اعتبار پاسخ res.message نمایش داده می شود.
سخن آخر: همانطور که در بالا هم توضیح داده شد، هر وب سرور دارای مشخصات منحصر به خود می باشد که امکان مستندسازی برای تمام انواع وب سرورها را ناممکن می سازد. لذا این مستند تنها برای آشنایی کلی با نحوه ارتباط با انواع وب سرورها و نیز آشنایی با ساختار کلی و ابزارهای WorkRestClient برای تعامل با وب سرورها می باشد.
تمرین: یک وب سرویس رایگان در محیط وب پیدا کنید و سعی کنید از طریق REST Client از این وب سرویس خدمات دریافت کنید.
ضمیمه: ارسال پیام به وب سرویس REST سیستم مدیریت فرایندهای نوسا
با مجهز شدن API سیستم مدیریت فرایندها به وب سرویس REST حال میزبانهای سیستم مدیریت فرایند نوسا می توانند از طریق کلاینت REST به وب سرویسهای یکدیگر پیام (message) ارسال کنند. برای این کار باید موارد زیر در نظر گرفته شود:
1- بدنه (Body) درخواست، شامل ویژگی (Property های زیر است:
- dbName: نام پایگاه گیرنده پیام که الگوی MyDB _ReposXP_ دارد. یعنی پیشوند _ReposXP_ میان نام تمام پایگاهها مشترک است و MyDB عبارت دلخواهی است که برای هر پایگاه به شکل خاص تعیین می شود.
- workKey:کلید کار گیرنده پیام. اگر گیرنده پیام مشخص است باید کلید کار گیرنده پیام را در این پارامتر مقداردهی می کنیم در غیر این صورت اگر گیرنده مشخص نیست باید مقدار صفر را به این پارامتر بدهید. در این حالت پیام به شکل رخداد (event) ارسال خواهد شد.
- messageKeyStr : کلید حرفی پیام
- note: یادداشت پیام
- checkPendings : انجام/عدم انجام امور معوقه موتور گردش کار. این پارامتر نیز از نوع منطقی است و مقدار true به معنی این است که CheckPendings انجام شود.
- numberParam: پارامتر عددی پیام. اگر پارامتر عددی تعیین نشده است باید مقدار این پارامتر را برابر صفر قرار دهید.
- stringParam: پارامتر حرفی پیام
2- Header ها شامل موارد زیر است:
- Content-Type (نوع محتوای درخواست)
- Autorization (احراز هویت)
جزئیات محتوای درخواست ارسال پیام از جمله Headerهای فوق، در مثال زیر توضیح داده شده است:
کلیات و ساختار این درخواست در یکی از مثالهای متن توضیح داده شده است اما این مورد خاص دارای تفاوتهایی است که نیاز به توضیح دارد:
محتوای متفاوت Headerها
در این درخواست، هدرها به شکل زیر درج می شود:
RestClt.AddHTTPHeader("Content-Type", "application/json" ) ;
RestClt.AddHTTPHeader('Authorization', MakeBasicAuthorization('NOSA-TEST\\sampleUser', 'abcd1234' ) ;
در سطر اول، نوع محتوای درخواست تعیین می شود که به فرمت applicatio/json می باشد و در سطر دوم نحوه احراز هویت در سرور مقصد مشخص می شود. در این مورد خاص، روش احراز هویت به روش Basic است و نام کاربری و کلمه عبور با الگوی userName:password و با کدینگ Base64 به تابع پاس می شود. در واقع این Header به شکل زیر تعیین می شود:
RestClt.AddHTTPHeader('Authorization', 'Basic ' + 'Tk9TQS1URVNUXHJlcHRlc3QxOk5vc2ExMjM0' ) ;
اما از آنجایی که کدینگ عبارت احراز هویت به شکل دستی دشواریهای خاص خود را دارد لذا تابعی بنام MakeBasicAuthorization تعریف می کنیم که پارامترهای ورودی آن نام کاربری و کلمه عبور و خروجی این تابع، عبارت احراز هویت با کدینگ Base64 می باشد. این تابع به شرح است:
function MakeBasicAuthorization(userName, password) {
var str = userName + ':' + password;
var arr = [ ];
for (var i=0; i < str.length; i++)
arr.push(str.charCodeAt(i));
return 'Basic ' + WorkUtils.BtoA(arr);
}
این تابع:
- نام کاربری و کلمه عبور را به شکل عبارت حرفی می گیرد.
- ترکیب این دو را با الگوی userName + ':' + password در یک متغیر قرار می دهد
- یک متغیر از نوع آرایه تعریف می کند و کاراکترهای ترکیب بالا را اعضای این آرایه قرار می دهد
- از طریق متد BtoA از WorkUtils کاراکترهای آرایه بالا را به صورت Base64 کد می کند .
- و در نهایت عبارت مورد نیاز را به شکل رشته حرفی و الگوی "نوع احراز هویت + نام کاربری: کلمه عبور" بازمی گرداند.