راهنمای ایجاد سرویس‌های واسط در پلتفرم پلتکو

این مستند شامل توضیحات فنی مربوط به جزئیات نحوه پیاده سازی، نصب و راه اندازی، و پیکربندی سرویس های واسط در ماژول PI از سیستم پلتکو می‌باشد. لازم به تاکید است که صرفا زمانی از ماژول PI استفاده می‌شود که در فراخوانی endpoint ‌های موجود نیاز به تغییرات و استانداردسازی‌های زیادی (چه در قسمت درخواست و چه در قسمت پاسخ) وجود داشته باشد. شرکت داده کاوان تصمیم یار از زبان برنامه نویسی پایتون و فریمورک FastAPI برای توسعه سرویس های واسط استفاده می نماید. زبان برنامه نویسی پایتون از نوع زبان های همه منظوره، مفسری، شی گرا و سطح بالاست. در پایتون، سورس کد به یک فرمت میانی به نام bytecode کامپایل می‌شود. این کدهای سطح پایین و فشرده، بر روی ماشین مجازی پایتون (Python Virtual Machine) اجرا می‌شوند. PVM نرم‌افزاری است که کار سخت‌افزار واقعی را شبیه‌سازی و نقش یک مفسر را بازی می‌کند و در حین اجرای برنامه، دستورالعمل‌های نوشته‌شده به bytecode را به زبان ماشین ترجمه می‌کند.

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

 ساختار پروژه

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

فایل/دایرکتوری های ذیل پروژه یک سرویس واسط عبارتند از:

• .gitignore : فایل هایی که توسط git نادیده گرفته می‌شوند و در repository پروژه نباید commit شوند.
• docker-compose.yml: تنظیمات مربوط به اجرای اپلیکیشن چند کانتینری PI
• Dockerfile: تنظیمات مربوط به نحوه ساخت image-ها
• README.md: توضیحات مربوط به نسخه ها و …
• requirements.txt: لیست کتابخانه و پلاگین هایی استفاده شده در پروژه
• run.bat: یک اسکریپت ویندوزی برای اجرای پروژه که به صورت مجزا داخل یک terminal هم قابل اجراست.
• دایرکتوری app:

1. دایرکتوری _conf: دارای 2 فایل به نام های config_manager و config می‌باشد. config_manager مقادیر پیکربندی را برای استفاده در ماژول های مختلف از config خوانده و در متغیر settings ذخیره می نماید. برای مشاهده پیکربندی های config به بخش 5 مستند مراجعه نمایید.

2. دایرکتوری common: عملیات عمومی و مشترک در این دایرکتوری تعریف می شوند و شامل 3 کلاس به شرح زیر می‌باشد:

• APILog: منطق مربوط به نحوه ثبت لاگ درخواست/پاسخ سرویس های واسط در این کلاس پیاده سازی شده است. متد logRequestBeforeSend ثبت لاگ درخواست PI به Provider، و متد logResponseAfterSend ثبت لاگ پاسخ Provider به PI را انجام می دهد ،
• HttpStatusCodeMapper: در این کلاس نگاشت بین کدوضعیت های پاسخ Provider و کدوضعیت های تعیین شده از سوی کارفرما پیاده سازی شده است،
• FormatOutput: در این کلاس فرمت عمومی تعیین شده توسط کارفرما برای پاسخ برگشتی به Consumer-های سرویس های واسط و همچنین فرمت های خروجی برخی از انواع خطاها پیاده سازی شده است.

3. سایر دایر کتوری ها: هر سرویس واسط دارای یک دایرکتوری مجزا می باشد. فایل ها و گواهی های دیجیتال مربوطه به هر سرویس در زیر دایرکتوری files نگه داری می‌شود. کلاس هایی که نام آن ها با OutputFormat تمام می شود نیز سرویس واسط متناظر هر یک از عملگر های سرویس می باشند. در کلاس Service نیز پیاده سازی ارسال درخواست، دریافت پاسخ و ثبت لاگ درخواست/پاسخ های مربوط به فراخوانی های سرویس‌ انجام شده است.

4. main.py: به بخش بعدی مستند مراجعه نمایید

 نحوه فعال/ غیر فعال کردن سرویس های واسط

تمامی سرویس های واسط برای فعال سازی باید در فایل app/main.py پروژه ایکه در آن پیاده سازی شده اند ابتدا import و سپس include شوند. برای غیرفعال کردن یک سرویس نوعی کافیست دستور include آن را به حالت comment درآوریم.

توجه: بعد از هر تغییر کوچکی در کد باید داکر PI مجددا تولید و از طریق Docker Swarm سرویس آپدیت شود.

 نحوه استفاده از ماژول مدیرت لاگ سیستم پلتکو در زبان های غیر پایتونی

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

قالب لاگ ارسال درخواست به Provider:

[{YYYY-MM-DD HH:mm:ss,SSS}] {log_level} {API_LOG} {“headers”: [“{header1}”, “{header2}”, …], “sourceIP”: “{sourceIP}”, “payload”: “{request_body}”, “verb”: “{http_method_type}”, “correlationId”: “{activity_id}”, “apiTo”: “{context}”, “flow”: “{log_name}”, “endpoint”: “{endpoint_address}”, “endpointName”: “{endpointName}”, “endpointCompany”: “{endpointCompany}”, “apiName”: “{apiName}”}

نمونه لاگ ارسال درخواست به Provider:

[2023-06-17 19:49:13,467] INFO {API_LOG} {“headers”: [“Content-Type=application/soap+xml;charset=UTF-8”], “sourceIP”: “localhost:8000”, “payload”: “<soap-env:Envelope xmlns:soap-env=\”http://www.w3.org/2003/05/soap-envelope\”>\n <description>salam</description>\n </soap-env:Body>\n</soap-env:Envelope>\n”, “verb”: “POST”, “correlationId”: “64f06bef-0019-4bf4-875a-76c03b10d2fc”, “apiTo”: “api/account/v1.0/withdraw”, “flow”: “REQUEST_OUT_PI”, “endpoint”: “http://localhost/WSWithdrawal/WSWithdrawalServiceSoap12HttpPort?WSDL”, “endpointName”: “pouya_accountWithdrawal”, “endpointCompany”: “karfarma”, “apiName”: “accountWithdrawal”}

قالب لاگ پاسخ دریافتی از Provider:

[{YYYY-MM-DD HH:mm:ss,SSS}] {log_level} {API_LOG} {“headers”: [“{header1}”, “{header2}”, …], “payload”: “{request_body}”, “verb”: “{http_method_type}”, “correlationId”: “{activityid}”, “statusCode”: “{http_status_code}”, apiTo”: “{context}”, “flow”: “{log_name}”, “endpoint”: “{endpoint_address}”, “endpointName”: “{endpointName}”, “endpointCompany”: “{endpointCompany}”, “apiName”: “{apiName}”}

نمونه لاگ پاسخ دریافتی از Provider:

[2023-06-17 19:49:14,105] INFO {API_LOG} {“headers”: [“Date=Sat, 17 Jun 2023 16:19:27 GMT”, “Content-Type=application/soap+xml; charset=utf-8”], “payload”: “<?xml version=’1.0′ encoding=’UTF-8′?></S:Body></S:Envelope>”, “verb”: “POST”, “correlationId”: “64f06bef-0019-4bf4-875a-76c03b10d2fc”, “statusCode”: 200, “apiTo”: “api/account/v1.0/withdraw”, “flow”: “RESPONSE_IN_PI”, “endpoint”: “http://localhost/WSWithdrawal/WSWithdrawalServiceSoap12HttpPort?WSDL”, “apiName”: “accountWithdrawal”}

پارامترهای قالب های فوق الذکر در جدول صفحه بعد تشریح شده اند.

توجه: نام تمام فیلد ها (حتی space بین کاراکتر ها) باید دقیقا مشابه قالب لاگ ها باشد.

 متغیرهای عمومی

متغیرهای عمومی در فایل app/_conf/config.py پروژه تعریف و مقدار دهی می شوند. مقدار این متغیرها را می توان به صورت داینامیک با تعریف متغیر های محلی (environment variables) در سیستم عامل یا فایل docker-compose تغییر داد:

LOG_FILE_ADDR: آدرس محل ذخیره فایل های لاگ
MY_SIMPLE_CONF: مقدار برگشتی سرویس تست (health check) که در ماژول sample_service استفاده می‌شود.
REDIS_URL: نام Docker Image و پورت Redis باید مطابق الگو و نمونه زیر تعریف شود:

“dockerImageName1:port1,dockerImageName2:port2,…”
“redis-node-1:7000,redis-node-2:7002,redis-node-3:7003”

به ازای هر سرویس واسط باید مدت زمان مورد نظر برای Timeout کردن فراخوانی ها و ارسال Fault به Consumer-ها را به صورت زیر تعریف کنیم:

SERVICE_REQUEST_TIMEOUT_TIME: مقدار در نظر گرفته شده برای Timeout کردن فراخوانی انجام شده از سرویس
SERVICE_REQUEST_TIMEOUT_TIME: مقدار در نظر گرفته شده برای Timeout کردن فراخوانی انجام شده از سرویس
SERVICE_REQUEST_TIMEOUT_TIME: مقدار در نظر گرفته شده برای Timeout کردن فراخوانی انجام شده از یک سرویس

 نحوه استفاده از زبان های برنامه نویسی غیر پایتونی برای توسعه سرویس های واسط

شما می‌توانید به جای زبان برنامه نویسی پایتون از زبان های برنامه نویسی دیگر نیز برای توسعه سرویس های واسط استفاده نمایید. بدین منظور تنها کافیست موارد زیر را رعایت فرمائید:

1.  ثبت لاگ درخواست/پاسخ ها: به اینجا مراجعه کنید.
2. ساختار پیام پاسخ: برای پاسخ تمام سرویس های واسط ساختار عمومی از سوی کارفرما اعلام می‌شود.

نحوه استقرار سرویس جدید به جای PI

بعد از اتمام عملیات توسعه یک واسط نوعی، باید آن را برای استقرار در سیستم پلتکو آماده نمایید. برای اینکار باید از پروژه خود یک docker image تهیه کنید و مطابق راهنمایی ارائه شده در مستند راه‌اندازی پلتفرم پلتکو توضیح داده شده است آن را اجرا کنید. بعد از آن می‌توانید از پرتال Publisher سیستم WSO2 API Manager ، API متناظر سرویس ها را پراکسی نمایید.