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

توسعه افزونه ها برای جوملا 5 23 بهمن 1403 بازدید: 47

(زمان تقریبی مطالعه: 16 - 31 دقیقه)

بیان خلاصه ای از بحث توسط هوش مصنوعی:

در این فصل، ما قصد داریم Web Services API جوملا را که اخیرا اضافه شده است را بررسی کنیم ، که به ما امکان می دهد سایت جوملا خود را با سایر وب سایت ها و خدمات، یکپارچه کنیم. ما یک راه ساده برای مصرف این وب سرویس API از رایانه خود ارائه خواهیم کرد که به ما امکان می دهد پیشرفت های خود را آزمایش کنیم. ما همچنین مجوزهایی را که بر وب سرویس API جوملا تأثیر می گذارد، بررسی خواهیم کرد و در نهایت، یک وب سرویس API برای کامپوننت خود اضافه می کنیم تا اطلاعات را به سایت ما بدهد و به آن اضافه کند.

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

استفاده از وب سرویس API جوملا به ما امکان می دهد تا داده ها را با سایر وب سایت ها تبادل کنیم و سایت های خود را فراتر از مرورگر وب گسترش دهیم. یکی از زمینه های جالب برای یک توسعه دهنده وب، توسعه اتوماسیون برای ادغام سایت های شما با سیستم های خارجی برای نظارت یا وارد کردن محتوا است.

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

برای پوشش تمام آنچه که باید در مورد توسعه وب سرویس API بدانیم، از این بخش ها استفاده خواهیم کرد:

وب سرویس API چیست ؟
چگونه می توانم از وب سرویس API جوملا استفاده کنم؟
مجوز برای Web API
مجوزهای سرویس وب API
افزودن یک وب سرویس API به کامپوننت شما
خواندن داده ها از وب سرویس شما – افزودن نقطه پایانی GET به کامپوننت شما.
نوشتن داده از وب سرویس شما – افزودن یک نقطه پایانی POST به کامپوننت شما

در این فصل قصد داریم نحوه جستجو کردن وب سرویس جوملا و مجوز وب سرویس API جوملا چگونه کار می کند. در نهایت یک Web Services API به افزونه ی Simple Project Manager اضافه می کنیم.

الزامات فنی

برای این فصل به موارد زیر نیاز دارید :

ابزار خط فرمان cURL یا نصب PHP با پشتیبانی از cURL فعال
در غیر این صورت، می توانید از یک ابزار آنلاین مانند Postman یا HoppScotch.io برای تست تماس های API استفاده کنید.

می توانید فایل های کد این فصل را در GitHub پیدا کنید:

https://github.com/PacktPublishing/Developing-Extensions-for-Joomla-5/tree/chapter06

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

وب سرویس ها بوسیله هستند که به ماشین ها امکان برقراری ارتباط را میدهند. یک وب سرویس خوب مسیرهای روشنی را فراهم می کند که می توانیم آنها را در سرویس های خارجی ادغام کنیم. این مسیرها را نقاط پایانی (endpoints) می نامند. همچنین پاسخ هایی را به روشی قابل خواندن توسط ماشین (Machine-Readable) ارائه می کند که می توانیم آنها را نیز در این سرویس ها ادغام کنیم.

انواع مختلفی از وب سرویس های API مانند SOAP یا REST وجود دارند. جوملا یک REST APIرا پیاده سازی میکند، بنابراین تمام مفاهیم این فصل به این نوع API مربوط می شود.

برای استفاده از Web Service API، یک درخواست HTTP به این نقاط پایانی ارسال می کنیم و پاسخی با داده ها یا برخی پیام های مربوط به درخواست خود، دریافت می کنیم. درخواست های اصلی HTTP که می توانیم در وب سرویس استفاده کنیم به شرح زیر است:

GET : زمانی که می خواهید داده ها را از API بازیابی کنید، از این درخواست استفاده میکنید. یک مثال خوب در این مورد، زمانی است که می خواهید لیستی از مقالات را از سایت بازیابی کنید.
POST : زمانی که می خواهید داده های جدیدی ارسال کنید از درخواست POST استفاده می کنید. به عنوان مثال، زمانی که شما می خواهید با استفاده از Web Service API یک مقاله جدید در جوملا ایجاد کنید، یک درخواست POST ارسال می کنید.
PATCH : درخواستPATCH برای اصلاح جزئی داده ها در سایت مفید است. به عنوان مثال، برای تغییر عنوان یک مقاله در سایت جوملا، شما می توانید از یک درخواست PATCH استفاده کنید.
DELETE : این درخواست برای حذف داده ها از سایت استفاده می شود - به عنوان مثال، برای حذف یک مقاله.

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

اکنون که اصول وب سرویس API را می دانیم، بیایید یاد بگیریم که چگونه می توانیم از آنها برای بازیابی و ارسال داده های آن استفاده کنیم.

نحوه مصرف هر وب سرویس API

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

چاقوی ارتش سوئیس برای فراخوانی نقطه پایانی API،cURL است. این یک برنامه خط فرمان (command-line program) است که به طور گسترده برای توسعه دهندگان استفاده می شود. مهم نیست API را که می خواهید بررسی کنید، دستورات دستورcurl را در مستندات پیدا خواهید کرد.

نکته

اگر از یک سرویس آنلاین مانند Postman یا Hoppscotch استفاده می کنید، هر دو یک ابزار واردات/صادرات برای cURL ارائه می دهند، بنابراین می توانید از مثال های زیر با این سرویس ها استفاده کنید.

ما قصد داریم در این کتاب از PHP cURL استفاده کنید ، که به راحتی می تواند به یک تماس مستقیم تبدیل شود ، بنابراین می توانید از هر سیستمی برای اجرای مثال های این کتاب استفاده کنید.

بیایید با ایجاد اسکریپت PHP برای دریافت داده ها از API شروع کنیم، بنابراین پوشه Scripts/api/ را در پوشه کاری خود ایجاد کنید و سپس فایل Scripts/api/get.php را با محتوای زیر ایجاد کنید:

 
<?php 
if (extension_loaded('curl') == false) { 
throw new \Exception('curl not installed'); 
} 
$url = 'https://jsonplaceholder.typicode.com/todos/1'; 
$connection = curl_init($url); 
curl_setopt($connection, CURLOPT_RETURNTRANSFER, true); 
$response = curl_exec($connection); 
curl_close($connection); 
print_r(json_decode($response));

در این کد ابتدا ما بررسی کنید curl PHP ی افزونه در سرور نصب شده است. این یک ویژگی رایج است که به احتمال زیاد نصب خواهد شد، اما در هر صورت، بهتر است برای جلوگیری از خطاهای غیرقابل منتظره، بررسی کنیم. پس از آن، URL API را تعریف می کنیم و از آن برای شروع اتصال cURL استفاده می کنیم. این درخواست بلافاصله ارسال نمی شود، بنابراین ما درخواست را با استفاده از تابع curl_setopt ویرایش می کنیم. به طور پیش فرض، PHP cURL یک درخواست GET ارسال می کند.

ما از متد curl_setopt() برای تنظیم پارامتر CURLOPT_RETURNTRANSFER استفاده می کنیم. دریافت پاسخ در رشته ای که می توانیم در یک متغیر ذخیره کنیم باید true باشد. در غیر این صورت سرور آن را نشان خواهد داد.

URL ازAPI مورد درخواست ما در این مثال https://jsonplaceholder.typicode.com (این یک API آزمایشی برای اهداف آزمایشی است که می توانید در پروژه های خود از آن استفاده کنید.) در URL اصلی خود، دستورالعمل های بیشتری را ارائه می دهد. در مورد ما، چون ما Web Service API جوملا را معرفی نکرده ایم، ما از این API استفاده می کنیم تا بررسی کنیم که اسکریپت PHP ما کار می کند یا خیر.

هنگام اجرای این اسکریپت، این پیام را در اسکریپت خود خواهیم دید :

 
stdClass Object 
( 
[userId] => 1 
[id] => 1 
[title] => delectus aut autem 
[completed] => 
)

این فقط داده های یکی از موارد موجود در لیست کارها است. می توانید عدد 1 در URL را با عدد دیگری جایگزین کنید و در پاسخ داده های متفاوتی دریافت خواهید کرد. حتی می توانید شماره را حذف کنید و سپس لیستی از موارد انجام کار قابل دسترسی از طریق این API دریافت خواهید کرد.

اکنون که اصول وب سرویس ها را پوشش دادیم، در بخش بعدی بیایید ببینیم چگونه می توانیم از Web Service API جوملا استفاده کنیم.

چگونه می توانم از وب سرویس APIجوملا استفاده کنم؟

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

تمام هسته ی کامپوننت های جوملا یک نقطه پایانی برای بازیابی و اضافه کردن داده ها با استفاده از Web Service API دارند. شما لیستی از تمام نقاط پایانی را در جوملا در اسناد رسمی https://docs.joomla.org/J4.x:Joomla_Core_APIsخواهید یافت.

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

System -> Manage Plugins ، می توانید تمام سرویس های موجود را که براساس نوعوب سرویس فیلتر می شوند، ببینید.

یک مثال خوب از وب سرویس ها جوملا! وب سرویس محتوا هستند. با استفاده از این وب سرویس، می توانیم لیستی از مقالات منتشر شده در سایت جوملا با استفاده از لینک YourSite.com/api/index.php/v1/content/articles را دریافت کنیم.

این درخواست پاسخی مشابه با فرمت JSON به شما می دهد :

 
{ 
"links": { 
"self": "https://YourSite.com/api/index.php/v1/content/articles" 
}, 
"data": [ 
{ 
"type": "articles", 
"id": "11", 
"attributes": { 
"id": 11, 
"asset_id": 148, 
"title": "Typography", 
"alias": "typograpy", 
... 
}, 
{ 
"type": "articles", 
"id": "10", 
"attributes": { 
"id": 10, 
"asset_id": 147, 
"title": "New feature: Workflows", 
"alias": "new-feature-workflows", 
... 
} 
], 
"meta": { 
"total-pages": 1 
} 
}

این یک پاسخ JSON است که حاوی لیست درخواستی مقالات یک سایت جوملا است. در این پاسخ JSON، سه آبجکت وجود دارد :

links: حاوی پیوندهای مربوط به پاسخ است. در این مورد، حاوی لینکی است که ما درخواست کرده ایم. در صورت وجود ، ممکن است حاوی پیوند به صفحه بعدی نتایج باشد.
data: حاوی داده هایی است که ما در یک آرایه درخواست کرده ایم. در این مثال، می توانیم آرایه ای از اشیاء مقاله را با شناسه مقاله، عنوان، نام مستعار و سایر خصوصیات مشاهده کنیم.
meta: متا اطلاعات مربوط به پاسخ است. در این حالت، تعداد کل صفحاتی است که فهرست مقالات را در بر می گیرد.

در این قسمت، بخش مجوز را حذف کرده ایم. اگر این کوئری را در سایت خود انجام دهید، با پیغام خطای 403 forbidden مواجه خواهید شد. در جوملا، باید کاربر سایت با مجوزهای کافی برای مصرف Web Service API باشید. در بخش بعدی بیایید به نحوه گنجاندن مکانیسم مجوز در درخواست های خود بپردازیم.

مجوز برای API

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

جوملا با دو روش مختلف مجوز ارائه می شود:

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

مجوز برای وب سرویس جوملا توسط نوع پلاگین api-authorization اداره می شود، بنابراین امکان افزودن روش های احراز هویت بیشتر وجود دارد.

بیایید جزئیات بیشتری را در مورد این روش ها ببینیم.

مجوز اولیه

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

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

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

مجوز توکن جوملا

این روش مجوز روشی است که به طور پیش فرض برای Web Service API فعال شده است. با استفاده از این روش، کاربران می توانند یک توکن API تصادفی از خود تولید کنند که نمایه ای برای احراز هویت درخواست آنها استفاده می شود.

این روش به دلایل زیر امن تر است :

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

در این روش به صورت پیش فرض فقط کاربران گروه Super Users می توانند توکن API ایجاد کنند. برای اینکه به کاربران دیگر گروه های کاربری اجازه ایجاد و استفاده از توکن های API را بدهید، باید پیکربندی پلاگین User – Joomla API Token را ویرایش کنید و گروه هایی را که می خواهید اجازه داشته باشند را انتخاب کنید. هنگامی که کاربران می توانند یک نشانه API ایجاد کنند، می توانند این کار را از پروفایل کاربری خود انجام دهند، جایی که می توانند یک برگه جدید با توکن پیدا کنند. نمونه هایی از مجوز توکن را در بخش مطالعه بیشتر خواهید دید.

این دو روش مجوز، آنهایی هستند که با جوملا ارائه می شوند و برای اکثر پروژه های شما کافی خواهد بود. در صورت نیاز به روش های دیگر مجوز، می توانید فهرست افزونه های جوملا را بررسی کنید یا حتی خودتان یک افزونه مجوز توسعه دهید.

مجوزها بخشی از امنیت جوملا API هستند. اساساً برای تطبیق درخواست با یک کاربر است - ممکن است در هنگام مرور یک سایت و ورود به سیستم به آن فکر کنیم. بخش دیگری در مورد امنیت وجود دارد که پس از ورود به سیستم می توانید انجام دهید که در بخش بعدی خواهیم دید. چگونه مجوزهای وب سرویس API مدیریت می کنیم.

مجوزهای وب سرویس API

در جوملا، ورود به وب سرویس به طور پیش فرض به کاربران گروه Super Users محدود می شود. دلیل این امر این است که در حال حاضر، API امکان مدیریت کامل یک سایت جوملا را فراهم می کند، بنابراین یک مجوز گسترده تر برای بسیاری از سایت ها، خطر امنیتی ایجاد می کند.

ما می توانیم این مورد را در تب Permissions در پیکر بندی جهانی (Global Configuration) جوملا تغییر دهیم. وقتی به آنجا می روید، ممکن است متوجه مجوز جدیدی به نام ورود به وب سرویس ها شوید. این تنظیم تعیین می کند که آیا گروه کاربر می تواند از Web Services API استفاده کند یا خیر.

زمانی که تعداد گروه های کاربری که می توانند از Web Service API استفاده کنند، افزایش می دهید، تکنیک هایی وجود دارد که می توانید برای محدود کردن مقدار داده ای که هر گروه کاربر می تواند مصرف کند، استفاده کنید.

از آنجایی که هر نقطه پایانی Web Service API توسط یک افزونه کنترل می شود، ما می توانیم دسترسی به آن نقاط پایانی را به سادگی با لغو انتشار این افزونه ها محدود کنیم. بنابراین، به عنوان مثال، برای جلوگیری از دسترسی به نقطه پایانی تماس با https://YourSite.com//api/index.php/v1/contact ، ما پلاگین Web Services – Contact را لغو انتشار می کنیم. در آن لحظه نقطه پایانی را از API وب سرویس ما حذف خواهد کرد.

ممکن است فکر کنید که تنظیم مجوز سطح دسترسی یک افزونه وب سرویس، روی ثبت شده (registered) یا خاص (special)، آن نقطه پایانی را برای کاربرانی با آن سطح از مجوزها محدود می کند. با این وجود، من می ترسم که کار نکند، زیرا بررسی نقطه پایانی قبل از صدور مجوز انجام می شود. بنابراین استفاده از یک لیست کنترل دسترسی ( ACL ) کار خواهد کرد. گویی ما مورد را لغو انتشار می کنیم.

خبر خوب این است که Web Service API به مجوزها و ACL کامپوننت ای که به آن مربوط می شود احترام می گذارد. بنابراین، می توانیم ACL را برای وب سرویس کنترل کنیم، گویی ACL یک استاندارد برای کامپوننت است. برای جلوگیری از نمایش یک مخاطب در Web Service API برای افراد در گروه ثبت شده (registered) ، فقط باید سطح دسترسی آن مخاطب را به یک مورد محدودتر (مثلاً ویژه (special) ) تغییر دهیم.

وقتی می دانیم وب سرویس جوملا چگونه کار می کند، ما آماده ایم یک نقطه پایانی برای دسترسی به افزونه ی خود از طریق Web Service API اضافه کنیم.

افزودن یک وب سرویس API به کامپوننت شما

توسعه وب سرویس برای کامپوننت ما با استفاده از Joomla Framework ^TM بسیار آسان است. از آنجایی که ما از کلاس های جوملا استفاده کرده ایم و به جوملا MVC احترام گذاشته ایم، جوملا از بسیاری از موارد مراقبت خواهد کرد. برای تعریف وب سرویس خود، ابتدا باید نقاط ورودی را برای موجودیت هایی که می خواهیم در معرض نمایش بگذاریم تعریف کنیم و سپس مدل های ایجاد شده خود را با این نقاط ورودی متصل کنیم.

برای تعریف نقاط ورودی، ما باید یک پلاگین وب سرویس Web Service plugin ایجاد کنیم. (در فصل 8 نحوه ایجاد پلاگین ها را با جزئیات بیشتری خواهیم دید،) اما در حال حاضر یک پلاگین بسیار ساده را بررسی میکنیم.

توسعه پلاگین وب سرویس

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

بیایید با افزودن فایل مانیفست شروع کنیم، همانطور که برای کامپوننت خود در فصل 2 انجام دادیم. فایل src/plugins/webservice/spm/spm.xml را با محتوای زیر ایجاد کنید:

 
<?xml version="1.0" encoding="utf-8"?> 
<extension type="plugin" group="webservices" 
method="upgrade"> 
<name>plg_webservices_spm</name> 
<author>Carlos Cámara</author> 
<creationDate>January 2023</creationDate> 
<copyright>Copyright 2023 PiedPiper Inc.</copyright> 
<license>GNU General Public License version 2 or later; 
see LICENSE.txt</license> 
<authorEmail>این آدرس ایمیل توسط spambots حفاظت می شود. برای دیدن شما نیاز به جاوا اسکریپت دارید</authorEmail> 
<authorUrl>www.packt.com</authorUrl> 
<version>1.0.0</version> 
<description>PLG_WEBSERVICES_SPM_XML_DESCRIPTION 
</description> 
<files> 
<filename plugin="spm">spm.php</filename> 
</files> 
</extension>

این محتوا همان ساختاری را دارد که در فصل 2 کار کردیم. البته ممکن است متوجه شوید که در بخش extension ، نوع را با کلمه کلیدی type="plugin" جایگزین کرده ایم و همچنین ویژگی group را برای تنظیم پلاگین group="webservices" (که افزونه ما به آن تعلق دارد) اضافه کرده ایم.

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

وقتی مانیفست خود را داشتیم، می توانیم فایل اصلی افزونه خود را ایجاد کنیم. همانطور که حدس زده اید، در مسیر src/plugins/webservice/spm/spm.php خواهد بود و محتوای زیر را خواهد داشت :

 
<?php 
use Joomla\CMS\Plugin\CMSPlugin; 
use Joomla\Router\Route; 
class PlgWebservicesSpm extends CMSPlugin 
{ 
public function onBeforeApiRoute(&$router) 
{ 
$router->createCRUDRoutes( 
'v1/projects', 
'projects', 
['component' > 'com_spm'] 
); 
} 
}

این کد PHP کلاس Plugin را برای وب سرویس ایجاد می کند و نقاط انتهایی API را با استفاده از متد onBeforeApiRoute اضافه می کند. جوملا این روش را هنگام دریافت تماس API فراخوانی می کند تا نقطه پایانی را به مسیرهای ممکن اضافه کند.

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

استفاده از متد createCRUDRoutes برای افزودن نقاط پایانی وب سرویس ما

متد createCRUDRoutes چهار نوع اصلی درخواست HTTP ممکن را برای نقطه پایانی پروژه در سیستم ثبت میکند.

(GET, POST, PATCH, DELETE)

در این روش، چهار آرگومان مختلف را ارسال می کنیم:

نقطه پایانی که می خواهیم به API خود اضافه کنیم: v1/projects در کد قبلی
نام کنترل کننده ای که به درخواست رسیدگی می کند: projects
نام کامپوننت و سایر گزینه های مرتبط در URL
یک مقدار درست true / نادرست false که نشان می دهد آیا نقطه پایانی به مجوز نیاز دارد یا خیر (به طور پیش فرض True در نظر گرفته میشود)

برای نام کامپوننت و سایر گزینه های مرتبط، آرایه ای را ارسال می کنیم که نام گزینه، کلید key است و مقدار عنصر، مقدار آرایه است. در مثال ما، ['component' => ' com_spm']

یک مثال خوب برای نشان دادن این پارامتر زمانی است که می خواهیم نقطه پایانی را برای دسته بندی های پروژه خود ایجاد کنیم. در این صورت کد زیر را به متد onBeforeApiRouter اضافه می کنیم :

 
$router->createCRUDRoutes( 
v1/projects/categories', 
'categories', 
['component' => 'com_categories', 'extension' => 
'com_spm'], 
true 
);

در این کد، می توانید ببینید که چگونه گزینه 'extension' => 'com_spm' را پاس می کنیم تا فقط دسته ها را از کامپوننت خود دریافت کنیم.

شایان ذکر است که در مورد آخرین پارامتر متد createCRUDRoutes کمی بیشتر توضیح داده شود.

در قسمت های قبلی دیدیم که جوملا به طور پیش فرض در رابطه با مجوز API محدود کننده است (به طور پیش فرض فقط برای کاربران فوق العاده super users در دسترس است) و ما باید به گروه های کاربری دیگر اجازه ی دسترسی دهیم. اما زمانی که نقاط پایانی خود را تعریف می کنید، این گزینه را دارید که فقط با استفاده از این آخرین پارامتر، آنها را به طور کامل عمومی کنید. وقتی این پارامتر مجوز روی false تنظیم شود ، درخواست ها به نقطه پایانی شما برای هر کسی که نقطه پایانی را مصرف می کند در دسترس خواهد بود.

این امر ایجاد نقاط پایانی را بسیار ساده می کند، اما اگر بخواهیم فقط درخواست GET را برای نقاط پایانی خود ارائه دهیم، چگونه خواهد بود؟

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

افزودن درخواست های نقطه پایانی سفارشی به وب سرویس ما

متد createCRUDRoutes عالی است زیرا هنگام افزودن یک نقطه پایانی API، اکثر سناریوهای رایج را کنترل می کند، اما نقطه ضعف آن این است که چهار فعل درخواست HTTP را برای نقطه پایانی پیاده سازی می کند. پس چه اتفاقی می افتد زمانی که ما فقط می خواهیم یک نقطه پایانی GET داشته باشیم ؟

در آن سناریو، ما باید هر یک از درخواست های نقطه پایانی را با استفاده از کلاس Joomla\CMS\Route پیاده سازی کنیم.

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

در آن صورت، createCRUDRoutes با نیازهای ما مطابقت ندارد. بنابراین، ما این کد را به متدonBeforeApiRoute خود اضافه می کنیم :

 
$route = new Route( 
['GET'], 
'v1/invoices', 
'invoices.displayItem', 
['id' => '(\d+)'], 
['component' => 'com_spm'] 
); 
$router->addRoute($route);

این کد کمی پیچیده تر از متد createCRUDRoutes قبلی است ، اما کنترل بیشتری بر نقطه پایانی که اضافه می کنیم به ما می دهد. بیایید آرگومان هایی را که برای کلاس Route نیاز داریم ببینیم :

['GET'] : اولین پارامتر یک آرایه با تمام روش هایی است که نقطه پایانی ما پشتیبانی می کند. در این مورد، ما فقط روشGET را پاس می کنیم تا امکان بازیابی داده ها فراهم شود.
v1/invoices : این نقطه پایانی برای API ما است.
invoice.displayItem : در این پارامتر سوم، کنترلر و روشی که این نقطه پایانی را مدیریت می کند را تنظیم می کنیم.
['id' '> '(\d+)'] : این پارامتر قوانینی را برای پردازش URL نقطه پایانی ما تنظیم می کند. این معمولا یک عبارت منظم برای شناسایی متغیرها در URL است. در این مورد، نشان می دهیم که یک پارامتر id وجود خواهد داشت که با آن عبارت منظم خاص (یک عدد صحیح) مطابقت دارد.
['component' => 'com_spm'] : در نهایت، متغیرهای پیش فرض را برای مسیر اضافه می کنیم، مانند نام کامپوننت خود.

اگر بخواهیم نوع دیگری از درخواست را اضافه کنید، فقط باید کد قبلی را کپی کنید و فعل مناسب را برای نقطه پایانی تنظیم کنید. در کامپوننت خود، ما اجازه ایجاد فاکتورها را از Web Service API می دهیم. برای آن، می توانیم از همان نقطه پایانی استفاده کنیم و فقط در نوع درخواست تمایز قائل شویم. درست در زیر کد قبلی، این بلوک را اضافه کنید:

 
$route = new Route( 
['POST'], 
'v1/invoices', 
'invoices.add', 
[], 
['component' => 'com_spm'] 
); 
$router->addRoute($route);

این کد بسیار شبیه به کد قبلی است. ما به تازگی نوع درخواست را با POST جایگزین کرده ایم و روشی را که درخواست ما را مدیریت می کند، با استفاده از متد add از کنترلر فاکتور تنظیم کرده ایم. در این حالت نیازی به تنظیم قوانین برای درخواست نیست، بنابراین پارامتر چهارم را به عنوان یک آرایه خالی می گذاریم.

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

رسیدگی به درخواست در کامپوننت ما

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

وب سرویس از معماری خاص خود برای رسیدگی به درخواست ها استفاده می کند، بنابراین این کنترلر API همان چیزی نیست که ما برای backend کامپوننت یا قسمت frontend کامپوننت خود ایجاد کرده ایم. ما باید یک زمینه جدید برای کد خود ایجاد کنیم. ما قصد داریم این زمینه جدید را در پوشه src/component/api/components/com_spm/src/ در مخزن کد خود اضافه کنیم. در داخل این پوشه، ساختار کد سایر زمینه ها را تکرار می کنیم، بنابراین باید پوشه های زیر را ایجاد کنیم:

src/component/api/components/com_spm/src/Controller
src/component/api/components/com_spm/src/View

این ساختار کد بسیار شبیه به ساختار کد frontend و backend است و در اصل به این معنی است که جوملا فلسفه MVC را در وب سرویسAPI حفظ می کند.

ما همچنین باید این تغییرات را در فایل مانیفست کامپوننت خود منعکس کنیم. بنابراین، فایل src/component/spm.xml را ویرایش کنید و یک بخش &lt;api> جدید با محتوای زیر اضافه کنید:

 
<api> 
<files folder="api/components/com_spm"> 
<folder>src</folder> 
</files> 
</api>

خواندن داده ها از وب سرویس شما – افزودن نقطه پایانی GET به کامپوننت شما

اجازه دهید شروع به ایجاد ProjectsController کنیم تا لیست پروژه ها را در پایگاه داده خود دریافت کنیم. لطفا فایل src/component/api/components/com_spm/src/Controller/ProjectsController.php را با محتوای زیر ایجاد کنید:

 
<?php 
namespace Piedpiper\Component\Spm\Api\Controller; 
use Joomla\CMS\MVC\Controller\ApiController; 
class ProjectsController extends ApiController 
{ 
protected $contentType = 'Projects'; 
protected $default_view = 'Projects'; 
}

در این کد، فضای نام را برای کنترلر وب سرویس خود نشان می دهیم و کلاسی را ایجاد می کنیم که منطق آن را مدیریت می کند. ما کلاس ApiController جوملا را گسترش می دهیم ، که باعث صرفه جویی در مقدار زیادی از کدنویسی می شود زیرا این کلاس قبلاً متدهای اساسی مانند displayList و add را ارائه می دهد.

در داخل کلاس، باید متغیرهای $contentType و $default_view را با نام نهاد داده خود (Projects) تعریف کنیم.

ما در حال حاضر هیچ متدی را به کنترلر اضافه نمی کنیم زیرا کلاس ApiController تمام نیازهای ما را بر عهده می گیرد.

پس از این، ما نمای پروژه های خود را ایجاد می کنیم. بنابراین، فایل src/component/api/components/com_spm/src/View/Projects/JsonapiView.php را با محتوای زیر ایجاد کنید:

 
<?php 
namespace Piedpiper\Component\Spm\Api\View\Projects; 
use Joomla\CMS\MVC\View\JsonApiView as BaseApiView; 
class JsonapiView extends BaseApiView 
{ 
protected $fieldsToRenderList = [ 
 'id', 
 'title' 
]; 
}

در این کد، پس از تنظیم فضای نام برای نمای وب سرویس API، ما JsonApiView را از جوملا گسترش می دهیم (دوباره، تا از استفاده مجدد کد از فریم ورک استفاده کنیم.) کلاس برای view ی ما باید JsonapiView نامیده شود زیرا این کلاسی است که جوملا به دنبال آن است.

بنابراین، برای جلوگیری از سردرگمی با کلاس JsonApiView که از کد جوملا گسترش می دهیم، هنگام اعلام استفاده از فضای نام، از نام مستعار BaseApiView استفاده می کنیم.

زمانی که وارد کد کلاس شدیم، فقط باید $fieldsToRenderList را به عنوان یک آرایه حاوی نام فیلدهای جدول #__projects که می خواهیم در پاسخ خود وارد کنیم، اعلام کنیم.

و تمام!! با این فایل های ساده، یک نقطه پایانی GET به کامپوننت جوملا خود اضافه کرده اید و با استفاده از اسکریپت get.php که در ابتدای فصل کد گذاری کردیم، می توانید لیست پروژه ها را از لیست دریافت کنید. بنابراین فقط URL و نشانه خود را با اسکریپت تنظیم کرده و آن را اجرا کنید. در نتیجه لیست پروژه های سایت خود را مشاهده خواهید کرد.

ما مدل پروژه ها را در Web Service API کد گذاری نکرده ایم. پیاده سازی وب سرویس جوملا به ساختار کد پشتیبان افزونه شما متکی است. همانطور که در فصل 2 ، ما یک مدل برای بخش پشتیبان کامپوننت خود ایجاد کردیم و وب سرویس برای دریافت موارد از پایگاه داده به آن متکی است.

هنگام استفاده از متد createCRUDRoutes ، جوملا به طور خودکار نقاط پایانی را برای لیست و موارد جداگانه ایجاد می کند، بنابراین ما می توانیم هر پروژه ای را در سیستم خود با استفاده از نقطه پایانی v1/projects/1 بازیابی کنیم. این نقطه پایانی از طریق ProjectsController که ما به تازگی ایجاد کرده ایم هدایت می شود، و ما فقط باید یک ویژگی محافظت شده را به فایل src/component/api/components/com_spm/src/View/Projects/JsonapiView.php اضافه کنیم. بنابراین، لطفا این ویژگی را اضافه کنید:

 
protected $fieldsToRenderItem = [ 
'id', 
'title', 
'description' 
];

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

نوشتن داده از وب سرویس شما – افزودن یک نقطه پایانی POST به کامپوننت شما

ما تا به حال دو نقطه پایانی تعریف کرده ایم: v1/invoices وv1/projects

برای هر دو نقطه پایانی، ما نوع درخواست POST را فعال کرده ایم تا کاربران بتوانند پروژه ایجاد کنند (در هنگام استفاده ازcreateCRUDRoutes به طور پیش فرض) و فاکتورها ایجاد کنند (ما به صراحت مسیر POST را در پلاگین وب سرویس WebServices خود اضافه کردیم.)

در بخش قبل، کنترلر را برای مدیریت پروژه ها اضافه کردیم. جوملا Framework ^TM زمانی بسیار مفید است که ساختار آن را رعایت کنیم و شما فقط سعی کنید با استفاده از درخواست POST یک پروژه ایجاد کنید.

ما می توانیم این را با ایجاد یک اسکریپت post.php آزمایش کنیم، همانطور که با اسکریپت get.php انجام دادیم. بنابراین، فایل Scripts/api/post.php را با محتوای زیر ایجاد کنید:

 
<?php 
if (extension_loaded('curl') == false) { 
throw new \Exception('curl not installed'); 
} 
$url = 'https://YourSite.com/api/v1/projects/'; 
$data = array( 
'title' => 'Testing API', 
'alias' => 'testing-api', 
'description' => 'We are testing our API on this 
project.' 
); 
$connection = curl_init($url); 
curl_setopt($connection, CURLOPT_RETURNTRANSFER, true); 
curl_setopt($connection, CURLOPT_URL, $url); 
curl_setopt($connection, CURLOPT_POST, true); 
curl_setopt($connection, CURLOPT_POSTFIELDS, 
http_build_query($data)); 
$response = curl_exec($connection); 
curl_close($connection); 
if ($response === false) { 
echo 'Error: ' . curl_error($connection); 
} else { 
echo 'Project created!'; 
}

در این کد PHP، ما از کتابخانه curl PHP برای ارسال درخواست POST به سایت خود استفاده می کنیم. تفاوت اصلی با اسکریپت get.php این است که اکنون باید داده هایی را که می خواهیم برای ایجاد پروژه خود استفاده کنیم، اضافه کنیم.

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

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