وب سرویس soap چیست؟

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

وب سرویس چیست؟

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

WSDL چیست؟

WSDL یک استاندارد مهم در وب سرویس است. هر وب سرویس دارای یک فایل WSDL می‌باشد. این فایل به توصیف وب سرویس می‌پردازد و نحوه استفاده از وب سرویس را توضیح می‌دهد که به برنامه‌ها می گوید که وب سرویس مورد نظر چه ورودی‌هایی دریافت و چه خروجی‌هایی را به آن برمی‌گرداند . WSDL صرفا برای برنامه طراحی شده است و برای کاربران استفاده کننده از وب سرویس طراحی نشده است. بسیاری از نرم افزارهایی که به ساخت وب سرویس می پردازند فایل WSDL وب سرویس را نیز خود به صورت اتوماتیک تولید می کنند.

لازم به ذکر است که بصورت معمول در web apiهای مبتنی بر پروتکل soap برای ارائه توضیحات رفتار و ویژگی‌های وب سرویس از فایل wsdl استفاده می‌شود. اما در وب سرویس‌هاس REST یا RESTfull از که یک خود یک سبکی از معماری است برای ارائه توضیحات ویژگی‌های وب سرویس از فایل  RSDL استفاده می‌شود.

در سامانه ملی پیامکی با دو شیوه میتوان به وب سرویس پیامکی متصل شد:

1- وب سرویس REST

یک مدل معماری برای ارائه سرویس ها و API های عمومی روی بستر اینترنت با استفاده از پروتکل HTTP می‌باشد .وب سرویس REST روی دسترسی به منابع آدرس دار با یک رابط مشخص تمرکز دارد . یعنی هر منبعی حاوی یک URL معین و واحدی است. در این نوع از طراحی، از عملیات موجود در خود HTTP بهره برداری می شود.
در ملی پیامک با استفاده از متد GET و همچنین با استفاده از متد POST می‌توان از وب سرویس استفاده کرد.

برای مشاهده نمونه کدهای اتصال به وب سرویس سامانه ملی پیامک می‌توانید از صفحه مستندات دیدن فرمایید.

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

2- وب سرویس SOAP

SOAP یک پروتکل انتقال است که به برنامه ی در حال اجرا بر روی سیستم های مجزا اجازه انتقال و تبادل پیام را می دهد. البته برخی ازSOAP به اشتباه “وب سرویس” نام می برند. فرمت پیام ها در این نوع وب سرویسXML می باشد و ساختار پیام مخصوص خود را دارد.

فرمت XML به شکل زیر می باشد:

POST /post/send.asmx HTTP/1.1
Host: 37.228.138.118
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://tempuri.org/SendSimpleSMS2"
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<SendSimpleSMS2 xmlns="http://tempuri.org/">
<username>string</username>
<password>string</password>
<to>string</to>
<from>string</from>
<text>string</text>
<isflash>boolean</isflash>
</SendSimpleSMS2>
</soap:Body>
</soap:Envelope>

در قطعه کد فوق نحوه فراخوانی متد SendSimpleSMS2 که برای ارسال پیامک تکی از وب سرویس در ملی پیامک کاربرد دارد ، آمده است.

با وب سرویس ملی پیامک شما میتوانید به راحتی به تمامی امور پیامکی و غیرپیامکی از قبیل ارسال پیامک ، ارسال پیامک زماندار، ارسال پیامک صوتی،ارسال پیامک از طریق وب سرویس خدماتی، دریافت وضعیت تحویل پیامک (دلیوری) ، دریافت و یا تغییر موجودی حساب، حذف پیامک، مشاهده پیام های ارسالی و دریافتی( صندوق دریافت )، دسترسی به امور تیکتی سامانه، اضافه کردن کاربر (زیر کاربر و یا کاربر در پنل های نمایندگی) و عملیات های کاربری، ایجاد شاخه و کار با عملیات های مربوط به آن، …، روی SOAP دسترسی داشته باشید .

آدرس وب سرویس SOAP

برای استفاده از SOAP نیاز هست که برنامه کاربر از طریق آدرس هایی که داخل مستندات درج شده است به وب سرویس ملی پیامک متصل شود.

این آدرس ها شامل مقادیر زیر می باشند:

• http://api.payamak-panel.com/post/send.asmx
• http://api.payamak-panel.com/post/receive.asmx
• http://api.payamak-panel.com/post/Users.asmx
• http://api.payamak-panel.com/post/contacts.asmx
• http://api.payamak-panel.com/post/actions.asmx
• http://api.payamak-panel.com/post/Schedule.asmx
• http://api.payamak-panel.com/post/Voice.asmx

هر کدام از این آدرس ها برنامه کاربر را به کلاس هایی متصل می کند که داخل آنها متد های مختلفی وجود دارند و با استفاده از آن می توان عملیات خاصی را انجام داد.

به عنوان مثال در بخش زیر عملیات ارسال پیامک تکی به واسطه متد SendSimpleSMS2 را مورد بررسی قرار می دهیم.

برای این منظور از آدرس http://37.228.138.118/post/send.asmx استفاده میکنیم.

پارامترهای سرویس SOAP

در متد فوق پارامتر های ورودی به این شکل تعریف می گردد:

• پارامترهای username و password: اطلاعات ورود به پنل ملی پیامک.
• پارامتر to: شماره گیرنده.
• پارامتر from: شماره فرستنده.
• پارامتر text: متن پیامک ارسالی.
• پارامتر isflash: تعیین میکند که آیا پیامک به صورت فلش ارسال گردد(true) یا خیر(false) که معمولا میبایست false باشد.

با تنظیم پارامتر های ورودی تعریف شده در بالا پیامکی با متن موردنظر ارسال خواهد شد.

خروجی سرویس SOAP

اما در مقابل وب سرویس میتواند یکی از مقادیر زیر را به عنوان خروجی برگرداند:

• رشته عددی Recid : ارسال با موفقیت انجام شده است.
• 0 : نام کاربری یا رمز عبور اشتباه می باشد.
• 1 : درخواست با موفقیت انجام شد.
• 2 : اعتبار کافی نمی باشد.
• 3 : محدودیت در ارسال روزانه
• 4 : محدودیت در حجم ارسال
• 5 : شماره فرستنده معتبر نمی باشد.
• 6 : سامانه در حال بروزرسانی می باشد.
• 7 : متن حاوی کلمه فیلتر شده می باشد.
• 9 : ارسال از خطوط عمومی از طریق وب سرویس امکان پذیر نمی باشد.
• 10 : کاربر مورد نظر فعال نمی باشد.
• 11 : ارسال نشده
• 12 : مدارک کاربر کامل نمی باشد.

همانطور که در تصویر فوق مشاهده می گردد، بعد از ارسال مقادیر ورودی، یک رشته عددی از سمت وب سرویس اعلام می شود که به آن RecId می گویند. RecId در خروجی توابع مختلف وضعیت و پاسخ وب سرویس به درخواست های ما را نشان می دهد. از کاربرد های RecId میتوان به اهمیت آن در دریافتگزارش تحویل اشاره نمود. به طوریکه با وارد نمودن آن در متد GetDeliveries وضعیت تحویل یا عدم تحویل پیامک موردنظر مشخص میگردد.

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

برخی از متد های مهم وب سرویس ملی پیامک:

در جدول فوق برخی به از پرکاربردترین و مهم ترین متدهای وب سرویس SOAP ملی پیامک اشاره شده است. در صورت تمایل میتوانید جهت مشاهده کامل متدها میتوانید اینجا کلیک کنید و یا با شماره 02163404 تماس حاصل بفرمائید.