معرفی API نسخه 5

در این پست شما رو با مهمترین کارکردهای API رکامندر آی‌آر نسخه ۵ آشنا می‌کنیم. مهمترین ویژگی‌های این نسخه پوشش بیشتر بر روی خدمات سرویس‌های لایه‌های پایین و هم چنین کاهش چشمگیر تعداد اندپوینت‌هاست.

مستندات این نسخه نیز همچون نسخه‌های قبلی توسط سواگر (swagger) تولید می‌شه. بسیاری از زبان‌های برنامه‌نویسی همچون جاوا، جاواسکریپت، پایتون، دات‌نت، پی‌اچ‌پی و … کد استاب کلاینت رو در اختیار دارین و این کمک می‌کنه طی کمترین زمان ممکنه سرویس‌های ما رو در سایت یا اپلیکیشن‌ها به کار بگیرین.

نسخه ۵ سرویس‌های رکامندر گروهی از اندپوینت‌های ویژه شخصی‌سازی را در اختیار شما قرار می‌دهد:

 

اندپوینت‌های ingest

اندپوینت‌های اینجست طیف متنوعی از عملیات ارسال، آپدیت و حذف آیتم‌ها و تگ‌ها رو انجام می‌دن. تصویر زیر اندپوینت‌های این گروه رو نمایش می‌ده:

برای ارسال، به روزآوری یا حذف می‌تونید از فرامین GET, POST, PUT, DELETE بر روی اندپوینت ingest استفاده کنید.

همچنین برای ارسال کامنت یک اندپوینت مجزا با فرمان POST را در اختیار دارین.

در ادامه به معرفی تک تک این اندپوینت‌ها همراه با مثال‌های متنوع می‌پردازیم.

ingest – GET

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

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

ingest – POST

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

می‌توانیم یک اینجست ساده ارسال کنیم با این مضمون که کاربر ۱۲۳۴۵ آیتم p_100 رو دیده:

{
"user-id": 12345,
"item-id": "p_100"
}

از این اندپوینت می‌تونید برای ارسال تگ‌های آیتم‌ها نیز استفاده کنید. در مثال زیر برای آیتم p_100 تگ‌های carpet, khaki, 9900$ رو ارسال کردیم:

{
"item-id": "p_100",
"tags": [
"carpet",
"khaki",
"9900$"
] }

در این مثال زیر با شناسه 12345 از کالایی با شناسه p_100 بازدید کرده. هم چنین کالای p-100 دارای تگ‌های carpet, khaki, 9900$ بوده.

نمونه جیسان ارسال شده را در اینجا نیز‌ مشاهده می‌کنید:

{
"user-id": 12345,
"item-id": "p_100",
"action": "visit",
"tags": [
"carpet",
"khaki",
"9900$"
] }

در مثال‌های بالا دیدیم برای ارسال اینجست‌های ساده مثل وقتی که کاربری آیتمی را می‌بیند یا اضافه کردن تگ‌های یک آیتم می‌توانیم از این اندپوینت استفاده کنیم.

ingest – PUT

برای ویرایش تگ‌ها کافیست از فرمان PUT استفاده کنیم.

 

به مثال‌ زیر توجه کنید. تگ‌های فرش و بختیاری را برای آیتم‌های p_100 و p_101 ثبت می‌کند. (تمام تگ‌های قبلی این آیتم‌ها را حذف می‌کند.)


{
"item-ids": [
"p_100",
"p_101"
],
"tags": [
"فرش",
"بختیاری"
] }

مثال زیر آیتم‌های p_100 و p_101 را از خروجی‌ها حذف می‌کند:


{
"item-ids": [
"p_100",
"p_101"
] }

ingest – DELETE

برای حذف تگ‌ها یا آیتم‌هایی که قبلا توسط اینجست‌هایی با فرامین GET, POST یا PUT به سرویس ارسال کرده‌ایم می‌تونیم از  اینسجت با فرمان DELETE استفاده کنیم:

مثالی که در تصویر بالا مشاهده می‌کنید، تگ‌هایی را از دو آیتم p_100 و  p_101 حذف می‌کند. اگر‌ آرایه tags را از body این مثال حذف کنیم، در این صورت دو آیتم p_100 و p_101 رو از تمام خروجی‌ها حذف می‌کند.

ingestComment – POST

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

به مثال زیر توجه کنید:

 

اندپوینت‌ history

این اندپوینت تاریخچه تعامل کاربر را بازیابی می‌کند:

 

نمونه‌ای از خروجی history را مشاهده می‌کنید:


{
"verboseHistory": {
"2018-08-20 23:47:51.275": "p206134",
"2018-08-20 23:48:28.297": "p132543",
"2018-08-20 23:48:34.404": "p68671",
"2018-08-20 23:48:48.656": "p223284",
"2018-08-20 23:49:19.018": "p37748",
"2018-08-20 23:50:05.069": "p100677",
"2018-08-20 23:50:13.334": "p231482"
},
"distinct": [
"p37748",
"p206134",
"p100677",
"p132543",
"p68671",
"p231482",
"p223284"
],
"frequent": {
"p100677": 1,
"p132543": 1,
"p206134": 1,
"p223284": 1,
"p231482": 1,
"p37748": 1,
"p68671": 1
},
"sortedFrequent": [
{
"item": "p37748",
"value": 1
},
{
"item": "p206134",
"value": 1
},
{
"item": "p100677",
"value": 1
},
{
"item": "p132543",
"value": 1
},
{
"item": "p68671",
"value": 1
},
{
"item": "p231482",
"value": 1
},
{
"item": "p223284",
"value": 1
}
],
"start": "",
"end": "",
"user-id": 4913994369424558000,
"history": {
"1534823405069": "p100677",
"1534823308297": "p132543",
"1534823359018": "p37748",
"1534823271275": "p206134",
"1534823314404": "p68671",
"1534823413334": "p231482",
"1534823328656": "p223284"
}
}

اندپوینت‌‌های query و wizard

دو اندپوینت کوئری و ویزارد طیف متنوعی از کارکردهای سرویس‌های ما را در اختیار شما قرار می‌دهند:

اندپوینت query با دو فرمان GET و POST برای فراخوانی انواع پیش‌بینی، تشابه‌آیتم‌ها، هیستوری، ترندها و … را در اختیار شما قرار می‌دهد.

query – GET

نگاهی به اندپوینت query با فرمان GET بندازیم:

به مستندات آنلاین توجه کنید. اگر بخواهیم ترند آیتم‌ها در دسته‌های سامسونگ و اپل را از سرویس دریافت کنیم، کافیست یک فراخوانی با فرمت زیر انجام دهیم:

که معادل این دستور GET است:

recommender.ir:port/query?count=10&formats=shuffled&formats=not-purchased&tags=apple&tags=samsung&widgets=trend

query – POST

همچنین می‌توانید اندپوینت query را با فرمان POST فراخوانی کنید:

مثال بالا ویجت‌های تشابه و ترند را با فرض دارا بودن تگ‌هایی معین فراخوانی می‌کند. خروجی بُر خورده است (شافل است).

نتیجه را ببینید:
{
"items": [
{
"item": "p341327",
"value": 12
},
{
"item": "p108623",
"value": 17
},
{
"item": "p219220",
"value": 12
},
{
"item": "p165571",
"value": 14
},
{
"item": "p26747",
"value": 15
},
{
"item": "p89786",
"value": 16
},
{
"item": "p131218",
"value": 12
}
] }

اندپوینت sort

هر گاه نیاز دارید تعدادی آیتم را بر اساس سلیقه کاربر مرتب کنید می‌توانید از این اندپوینت استفاده کنید:


{  "items": [

{ "item": "item21" },

"item": "item86" },

{ "item": "item89" },

{ "item": "item10" },

{ "item": "item75" },

{ "item": "item30" }]

}

اندپوینت‌های پردازش متن – text

ممکن است نیازمند دسته‌بندی خودکار انواع محتوا باشید. برای این منظور می‌توانید اندپوینت classify را صدا کنید. این اندپوینت با دو فرمان GET و POST در اختیار شماست:

خروجی را ملاحظه کنید:


{
"categories": {
"economy": "0.41",
"selfknowledge": "0.17",
"politics": "0.14",
"socialmedia": "0.13",
"productivity": "0.12"
}
}

0 پاسخ

برای ما بنویسید

دوست داریم نظر شما رو بدونیم

پاسخ دهید

نشانی ایمیل شما منتشر نخواهد شد. بخش‌های موردنیاز علامت‌گذاری شده‌اند *