مستند «راهنمای راه‌اندازی سریع WSO2 API Manager»

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

در این راهنما، شما با راه اندازی WSO2 API Manager آشنا خواهید شد. این راهنما شامل مراحل زیر است:

1.  نصب WSO2 API Manager
2. پیکربندی WSO2 API Manager
3. ساخت و مدیریت API ها
4. تست API ها

در انتهای این مطلب با شرکت دانش بنیان پلتکو همراه باشید تا با دنبال کردن این راهنما، شما می توانید WSO2 API Manager را به راحتی راه اندازی کنید و API های خود را به صورت موثر و بهینه مدیریت کنید.

           

راهنمای شروع سریع – مدیریت API

این بخش یک راهنمای گام به گام برای ایجاد، انتشار و فراخوانی یک API با استفاده از پورتال ناشر و توسعه دهنده WSO2 API Manager (WSO2 API-M) است.

قبل از اینکه شروع کنید…

1. نسخه 11 Oracle Java SE Development Kit (JDK) را نصب کنید و متغیر محیطی JAVA_HOME را تنظیم کنید.
   برای اطلاعات بیشتر در مورد تنظیم متغیر محیطی JAVA_HOME  برای سیستم عامل های مختلف، به Setup and Install مراجعه کنید.
2. نسخه 4.0.0 WSO2 API-M را دانلود کنید.
3. WSO2 API-M را با استفاده از Command-lineدر مسیر <API-M_HOME>/bin راه اندازی کنید و دستور زیر را اجرا کنید.

• api-manager.bat –run (برای ویندوز)
• sh api-manager.sh (برای لینوکس)

 

چیزی که خواهی ساخت

در این سناریوی نمونه، شما یک چرخه کامل از یک API را با استفاده از WSO2 API Manager پیاده سازی می‌کنید.

 

1. ایجاد و انتشار یک API از طریق پورتال ناشر WSO2 API-M.
2. API را در محیط Gateway مستقر کنید.
3. API را در پورتال توسعه‌دهنده منتشر کنید.
4. اشتراک در API از طریق پورتال توسعه دهنده WSO2 API-M و تولید کلید‌ها.
5. فراخوانی API با کلیدهای تولید شده.

بیایید شروع کنیم…

مرحله 1 – ایجاد و انتشار یک API

دستورالعمل های زیر را برای ایجاد و انتشار یک API از طریق پورتال ناشر WSO2 API-M دنبال کنید.

1. به پورتال ناشر بروید.
   https://localhost:9443/publisher

2. در صورت ورود به پورتال ناشر لوکال از admin/admin به عنوان اعتبارنامه استفاده کنید یا با استفاده از نام کاربری و رمز عبوری که از پلتکو گرفته‌اید وارد پورتال ناشر پلتکو شوید.

3. یک API ایجاد کنید. ( راه اندازی  API )
   بیایید از یک سرویس REST ساختگی برای ایجاد یک REST API از ابتدا استفاده کنیم.
   یک سرویس ساختگی با پاسخ {“hello”: “world”} به طور پیش‌فرض زمانی ارائه می‌شود که از URL سرویس به عنوان http://run.mocky.io/v2/5185415ba171ea3a00704eed استفاده می‌کنید. که در https://designer.mocky.io سرویس ساختگی ظاهر می شود. بیایید به جای پروتکل HTTPS برای این راهنما از پروتکل HTTP استفاده کنیم.

نکته.

در صورت تمایل ، برای تست این سرویس، URL سرویس

http://run.mocky.io/v2/5185415ba171ea3a00704eed را کپی کنید و در یک مرورگر جدید به آن بروید. شما باید پیام JSON زیر را ببینید.

{“hello”: “world”}

4. REST API را از صفحه اصلی انتخاب کنید و سپس روی Start From Scratch کلیک کنید.

5. جزئیات API را وارد کنید.

 

 

Name	HelloWorld
Context	/hello
Version	1.0.0
Endpoint	http://run.mocky.io/v2/5185415ba171ea3a00704eed   توجه: از پروتکل HTTP استفاده کنید زیرا برای استفاده از HTTPS باید گواهی https://designer.mocky.io را به WSO2 API-M وارد کنید.

6. Create & Publish را کلیک کنید.
   این اولین API شما را در پورتال توسعه‌دهنده منتشر می‌کند و همچنین آن را در دروازه API مستقر می‌کند. اکنون یک OAuth 2.0 ایمن REST API دارید که آماده مصرف (استفاده) است.

 

مرحله 2 – مشترک شدن در API

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

1. به پورتال توسعه‌دهنده بروید. (https://localhost:9490/devportal)
API منتشر شده HelloWorld در پورتال توسعه دهندگان مطابق شکل زیر فهرست شده است.

 

2. روی ورود به سیستم کلیک کنید و همان نام کاربری و رمز عبور پورتال ناشر را به عنوان اعتبارنامه خود وارد کنید تا وارد پورتال توسعه‌دهنده شوید.

3. برای مشاهده نمای کلی API روی تصویر کوچک API کلیک کنید.

 

 

4. یک برنامه OAuth 2.0 را ثبت کنید.

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

 

b. بر روی ابزار اشتراک و تولید کلید در بالای صفحه کلیک کنید.

این ابزار شما را از طریق 5 مرحله راهنمایی می کند که یک برنامه OAuth 2.0 را ثبت کنید که از آن برای مصرف HelloWorldAPI  استفاده خواهید کرد.

 

c. برنامه OAuth 2.0 را ایجاد کنید.

نام برنامه را وارد کنید و بدون تغییر هیچ یک از مقادیر پیش فرض دیگر، روی بعدی کلیک کنید.

 

d. برنامه را در API مشترک کنید.

این برنامه  Greetings  را در  HelloWorld API  در طرح کسب و کار انتخاب شده مشترک می‌کند. بدون تغییر هیچ یک از مقادیر پیش فرض روی بعدی کلیک کنید.

 

 

e. اعتبارنامه برنامه Greetings OAuth2.0 را ایجاد کنید.

Grant Types پروتکل های مختلفی را تعریف می کند که توسط سیستم مجاز خواهد بود و برنامه شما مجاز به درخواست توکن از آن ها خواهد بود. این مورد را در “نوع اعطا” مشاهده کنید. روی بعدی کلیک کنید.

 

f. برای دسترسی به HelloWorld API یک توکن دسترسی آزمایشی برای برنامه Greetings ایجاد کنید.

 

g. برای کپی کردن کد دسترسی آزمایشی تولید شده در کلیپ بورد، روی نماد کپی، همانطور که در زیر نشان داده شده است، کلیک کنید.

h.پایان را کلیک کنید.

اکنون می توانید  HelloWorld API   را با توکن OAuth 2.0 که به تازگی ایجاد کرده اید، تست کنید.

مرحله 3 – فراخوانی API

دستورالعمل های زیر را برای فراخوانی API ایجاد شده قبلی با کلیدهای تولید شده دنبال کنید.

1. روی تست کنید در نوار منوی سمت راست کلیک کنید.
منابع API لیست خواهند شد.

2. توکن دسترسی را که قبلاً کپی کرده اید در قسمت توکن دسترسی قرار دهید.

 

 

3. اگر اولین باری است که از کنسول تست API از مرورگر خود استفاده می کنید، یک برگه جدید باز کنید و به آدرس https://localhost:8243 بروید.

این امر باعث می شود که مرورگر شما گواهی استفاده شده توسط API Gateway را بپذیرد. این مورد نیاز است زیرا به طور پیش‌فرض API Gateway از گواهی امضا شده‌ای استفاده می‌کند که مورد اعتماد مرورگرهای وب نیست.

توجه

این گواهی که توسط API Gateway استفاده می شود، هنگام استقرار سیستم در تولید جایگزین می شود.

4.برای گسترش منبع روی منبع GET وب سرویس و سپس روی Try it out کلیک کنید.

5. روی Execute کلیک کنید.

 

شما باید Respone (پاسخ) {“hello” : “world”} را از API ببینید.

 

تبریک می‌گویم! شما با موفقیت اولین API خود را ایجاد کرده‌اید، از طریق یک برنامه OAuth 2.0 در آن مشترک شده اید، یک توکن دسترسی برای تست به دست آورده اید، و API خود را با توکن دسترسی فراخوانی کرده‌اید.

توسعه و استقرار API به صورت خودکار

بیایید به نحوه استفاده از WSO2 API Controller (apictl) که ابزار خط فرمان برای جابجایی APIها، محصولات API و برنامه‌ها در محیط‌های WSO2 API-M و انجام عملیات CI/CD است، استفاده کنیم.

قبل از اینکه شروع کنید…

1. مطمئن شوید که WSO2 API Manager (WSO2 API-M) 4.0.0 را اجرا می کنید.
2. apictl را دانلود کنید.
   1. به صفحه API Manager Tooling بروید.
   2. نسخه apictl 4.0.0 (یا آخرین نسخه از خانواده 4.x) مبتنی بر سیستم عامل خود را از بخش API Controller Tooling دانلود کنید.
   3. ZIP را در مکان دلخواه استخراج کنید.
      این مکان به عنوان دایرکتوری apictl نامیده می‌شود.
   4. به دایرکتوری apictl بروید.

هشدار

اگر قبلا از نسخه قدیمی apictl استفاده کرده اید، از دایرکتوری /home/<user>/.wso2apictl نسخه پشتیبان تهیه کرده و حذف کنید.

1. در صورت تمایل، دستور زیر را برای مشاهده عملیات موجود اجرا کنید.

./apictl –help

3. apictl را به نمونه ای از WSO2 API-M که در آن می‌خواهید API ها را مستقر کنید، اشاره کنید.
   برای افزودن محیطی برای این منظور دستور زیر را اجرا کنید.

نکته

• در دستور زیر فرض می شود که WSO2 API-M به صورت محلی (localhost) با استفاده از پورت های پیش فرض اجرا می شود.
• برای اطلاعات بیشتر در مورد افزودن محیط ها با استفاده از ترکیب های مختلف پرچم، به
  Add an environment(افزودن محیط) مراجعه کنید.

./apictl add env dev \

         –apim https://localhost:9443

با اجرای موفقیت آمیز این دستور، باید پیام زیر را مشاهده کنید.

Default token endpoint ‘https://localhost:9443/oauth2/token’ is added as the token endpoint

Successfully added environment ‘dev‘

مرحله 1 – ایجاد یک API

1. با ارائه یک نام برای پروژه، یک پروژه API را راه اندازی کنید.
   بیایید از دستور زیر برای ایجاد یک API به نام PetstoreAPI استفاده کنیم. این یک پوشه به نام PetstoreAPI در فهرست فعلی شما ایجاد می کند.

./apictl init PetstoreAPI –oas https://apim.docs.wso2.com/en/4.0.0/assets/attachments/get_started/
petstore.json

با اجرای موفقیت آمیز این دستور، باید پیام زیر را مشاهده کنید.

Initializing a new WSO2 API Manager project in <your-directory-path>/PetstoreAPI

Project initialized

Open README file to learn more

نکته

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

./apictl init –help

2. فایل yaml را به روز کنید.
   • پوشه PetstoreAPI را با یک IDE (به عنوان مثال، VSCode) باز کرده و جستجو کنید.
   • فایل api yaml را باز کنید. همچنین می توانید از یک ویرایشگر متن برای باز کردن این فایل استفاده کنید.
   • مقادیر ویژگی های زیر را مطابق شکل زیر تغییر دهید و فایل را ذخیره کنید.

lifeCycleStatus: PUBLISHED

production_endpoints :             url: https://petstore.swagger.io/v2

sandbox_endpoints  :                url: https://petstore.swagger.io/v2

توجه

• اطمینان حاصل کنید که هیچ فاصله ای بین context در فایل api.yaml وجود ندارد.
• با تغییر وضعیت چرخه عمر پیش‌فرض API از CREATED به PUBLISHED ، API مستقیماً در پورتال توسعه‌دهنده و API Gateway مستقر می‌شود، زمانی که این API را در مرحله زیر به WSO2 API-M فشار دهید.
• اگر می‌خواهید این API را فقط به پورتال ناشر وارد کنید، وضعیت باید CREATED شود.

مرحله 2 – انتشار API

1. API را به WSO2 API-M وارد کنید.
   به دایرکتوری apictl برگردید و دستور زیر را اجرا کنید:

توجه

• اگر برای اولین بار با یک محیط خاص کار می کنید، از شما خواسته می شود اعتبار حساب خود را در WSO2 API-M وارد کنید.
• می‌توانید از اعتبار پیش‌فرض مدیر به‌عنوان admin/admin استفاده کنید.

./apictl import api –file ./PetstoreAPI –environment dev

اکنون باید API خود را با موفقیت در WSO2 API-M مشاهده کنید.

2. برای مشاهده جزئیات API، پورتال‌‌های Publisher وDeveloper را مرور کنید.

• Publisher – https://localhost:9443/publisher

 

• Developer Portal – https://localhost:9443/devportal

مرحله 3 – فراخوانی  API

1. با استفاده از apictl یک توکن دسترسی ایجاد کنید.
   با استفاده ازapictl یک توکن دسترسی ایجاد کنید.

           ./apictl get keys -e dev -n SwaggerPetstore -v 1.0.0 -r admin

شما یک توکن دسترسی دریافت خواهید کرد که می‌تواند برای فراخوانی API شما استفاده شود.

اطلاعات

برای اطلاعات بیشتر در مورد تولید کلیدها با استفاده از apictl، به  Get keys for an API/API Productمراجعه کنید.

2. API را فراخوانی کنید.
   دستور cURL زیر را برای فراخوانی منبع GET /pet از API خود اجرا کنید.
   اطمینان حاصل کنید که توکن دسترسی را که در مرحله قبل به دست آورده اید به عنوان Bearer در درخواست وارد کنید.

curl -H “Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUz….RWrACAUNSFBpxz1lRLqFlDiaVJAg” https://localhost:8243/SwaggerPetstore/1.0.0/pet/2 -k

پاسخ زیر را دریافت خواهید کرد.

{“id”:2,”category”:{“id”:0,”name”:”Dogs”},”name”:”Crunch”,”photoUrls”:[“-“],”tags”:[{“id”:3,”name”:”Crunchiogo”}],”status”:”unavailable”}

توجه

همچنین، می‌توانید API را همانطور که در بخش‌های زیر توضیح داده شده است، با استفاده از پورتال توسعه‌دهنده WSO2 API-M مصرف کنید.

• مشترک شدن در API از طریق پورتال توسعه‌دهنده و تولید کلیدها
• فراخوانی API با کلیدهای تولید شده