Skip to content

Panel API

Jump to bottom
Hamed Saeedi edited this page Jan 12, 2019 · 10 revisions

API پنل تحت وب

سایت متن کاوی دو مدل API ارائه می‌کند. بخش اصلی API ها مربوط به پردازش متن است که لیست آن‌ها در آدرس https://api.text-mining.ir قابل مشاهده است و مستندات این API ها نیز در آدرس https://docs.text-mining.ir قرار دارد و در حال تکمیل است.

بخش دوم API‌ها مربوط به پنل تحت وب متن کاوی است که برچسب زنی پیکره‌ها در آن انجام می‌شود. این پنل در آدرس https://app-text-mining.ir قرار دارد و مستندات مربوط به API این پنل در این صفحه ویکی که در آن هستید نگهداری می‌شود.

احراز هویت

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

https://app.text-mining.ir/api/auth/login

درخواست باید از نوع POST باشد و اطلاعات زیر نیز در Body به صورت Json ارسال شود

{
   Email: "YOUR_TEXTMINING_ACCOUNT_EMAIL",
   Password : "YOUR_TEXTMINING_ACCOUNT_PASSWORD"
}

در صورت موفقیت آمیز بودن، کد 200 به همراه توکنJWT بازگردانده می‌شود. از این توکن، در احراز هویت سایر API های پنل تحت وب استفاده می‌شود. در غیر اینصورت کد خطای 400 به همراه پیام خطا بازگردانده می‌شود.

ثبت‌نام در سامانه

برای ثبت‌نام در سامانه در صورتی که حساب کاربری وجود نداشته باشد، از متد زیر در API می‌توان استفاده کرد

https://app.text-mining.ir/api/auth/register

درخواست باید از نوع POST باشد و اطلاعات زیر نیز در Body به صورت Json ارسال شود

{
   Email: "YOUR_EMAIL",
   Password : "YOUR_PASSWORD",
   ConfirmPassword : "RETYPE_YOUR_PASSWORD",
}

در صورت موفقیت آمیز بودن، کد 200 به همراه پیام موفقیت بازگردانده می‌شود. در غیر اینصورت کد خطای 400 به همراه پیام خطا بازگردانده می‌شود. در صورتی که مدل ارسالی ایرادی داشته باشد نیز خطای 400 به همراه توضیحات خطا در قالب message برگردانده می‌شود.

API برچسب زنی پیکره NER

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

  • دریافت یک جمله تصادفی جدید از پیکره برای برچسب زنی
  • برچسب زدن یک کلمه در جمله
  • دریافت برچسب‌های استاندارد NER

احراز هویت برای API برچسب زنی پیکره

در هر یک از دو متد اشاره شده در بالا، به همراه درخواست باید Header مربوط به Authorization از نوع Bearer Token ارسال شود و در آن مقدار دریافتی توکن بعد از استفاده از متد login که در بخش احراز هویت توضیح داده شد قرار گیرد.

دریافت یک جمله تصادفی جدید از پیکره برای برچسب زنی

برای این کار به آدرس زیر یک درخواست ارسال کنید. این درخواست همانطور که در بالا توضیح داده شد باید توکن احراز هویت داشته باشد.

https://app.text-mining.ir/api/ner/GetRandomSentence

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

{
    "sentenceId": "8028e32b-e00c-e911-9e31-ac220b2bc74b",
    "words": [
        {
            "WordId": "649c7032-3b05-4988-b734-158a6f62ec5d",
            "NerTagId": "7dc3ce92-8259-46ec-a252-049283f668b7",
            "Word": "برای",
            "WordOrder": 1,
            "Tag": "O"
        },
        {
            "WordId": "8accc0b0-9b32-420d-b906-505ea1682877",
            "NerTagId": "7fd0f2d6-9d82-4482-9f06-6d9681afb102",
            "Word": "نمونه",
            "WordOrder": 2,
            "Tag": "O"
        },
...
}

در خروجی بالا، sentenceId شناسه جمله‌ای که به صورت تصادفی به کاربر اختصاص یافته است. این شناسه بعداً در زمان برچسب زنی با متد TagWord که در ادامه توضیح داده می‌شود استفاده می‌شود. در ادامه این خروجی آرایه‌ای از کلمات جمله، به صورت پشت سر هم می‌آید. در هر یک از عناصر این آرایه، خود کلمه در Word و ترتیب آن در جمله که عددی می‌باشد و از عدد ۱ شروع می‌شود با WordOrder مشخص است و تگ فعلی این کلمه نیز با Tag مشخص شده است که یکی از حالات زیر می‌باشد:

  • B-PER برای تگ شروع شخص
  • I-PER برای تگ شخص
  • B-ORG برای تگ شروع سازمان
  • I-ORG برای تگ سازمان
  • B-LOC برای تگ شروع مکان
  • B-LOC برای تگ مکان
  • B-EVE برای تگ شروع رویداد
  • I-EVE برای تگ رویداد
  • B-DAT برای تگ شروع تاریخ و زمان
  • I-DAT برای تگ تاریخ و زمان
  • O برای تگ سایر موارد غیر از موارد بالا

علاوه بر موارد بالا، شناسه کلمه نیز در اطلاعات خروجی هر آیتم آرایه کلمات با WordId مشخص می‌شود که بعداً در زمان برچسب زنی با متد TagWord که در ادامه توضیح داده می‌شود استفاده خواهد شد.

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

  • Invalid authentication method این خطا به صورت موقت ارائه می‌شود و بعداً با کد خطای دیگری جایگزین می‌شود. معنی آن این است که توکن که در Header درخواست برای احراز هویت به روش JWT ارسال شده نامعتبر است
  • Invalid user data به معنی آن است که اطلاعات موجود در توکن احراز هویت، قابل شناسایی نیست

در سایر حالات خطا، عبارت کلی An error occurred and we logged it, for security reasons we can't share more details بازگردانده می‌شود که به آن معنی است که خطا لاگ شده است و مدیر سیستم از آن مطلع می‌شود.

برچسب زدن یک کلمه در جمله

برای این کار به آدرس زیر یک درخواست ارسال کنید. این درخواست همانطور که در بالا توضیح داده شد باید توکن احراز هویت داشته باشد.

https://app.text-mining.ir/api/ner/tagword

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

{
	SentenceId: "8028e32b-e00c-e911-9e31-ac220b2bc74b",
	WordId:"649c7032-3b05-4988-b734-158a6f62ec5d",
	UserTag:"I-PER"
}

در صورت موفقیت آمیز بودن ثبت تگ برای کلمه، کد 200 برگردانده می‌شود و در غیر اینصورت یکی از پیام‌های خطای زیر به همراه کد خطای 400 بازگردانده خواهد شد:

  • Invalid model مدل ورودی غیرمعتبر است. مدل را از جهت وجود همه فیلدها به همان اسم اشاره شده در نمونه بالا مجدداً بررسی کنید.
  • Model is not valid. All fields are required مدل نامعتبر است و بعضی از فیلدهای آن مقدار ندارند یا مقدارشان غیرمتعبر است.
  • Invalid authentication method این خطا به صورت موقت ارائه می‌شود و بعداً با کد خطای دیگری جایگزین می‌شود. معنی آن این است که توکن که در Header درخواست برای احراز هویت به روش JWT ارسال شده نامعتبر است
  • Invalid user data به معنی آن است که اطلاعات موجود در توکن احراز هویت، قابل شناسایی نیست
  • SentenceId is in incorrect format شناسه جمله که در قالب یک داده GUID باید ارسال شود غیر معتبر است.
  • WordId is in incorrect format شناسه کلمه که در قالب یک داده GUID باید ارسال شود غیر معتبر است.
  • Sentence Not found جمله مورد نظر شما پیدا نشد. یعنی شناسه جمله در بانک اطلاعاتی موجود نیست
  • Sentence is not assigned to you جمله برای برچسب زنی به شما محول نشده است. وقتی کاربر درخواست یک جمله تصادفی می‌کند، آن جمله برای برچسب‌زنی به وی اختصاص داده می‌شود. یک کاربر نمی‌تواند جملاتی که به خودش محول نشده است را برچسب زنی کند.
  • Invalid tag name عنوان تگ ارسالی شما نامعتبر است و یکی از تگ‌های استاندارد نیست

در سایر حالات خطا، عبارت کلی An error occurred and we logged it, for security reasons we can't share more details بازگردانده می‌شود که به آن معنی است که خطا لاگ شده است و مدیر سیستم از آن مطلع می‌شود

دریافت برچسب‌های استاندارد NER

این متد نیازی به احراز هویت ندارد و با فراخوانی آدرس زیر قابل دسترس است.

https://app.text-mining.ir/api/ner/standardtags

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

{
    "NerStandardTags": [
        {
            "Title": "B-PER",
            "Color": "#8bc34a",
            "PersianName": "شروع شخص",
            "Description": "بخش ابتدایی (آغازین) یک موجودیت از نوع شخص، مثال: «آقای» در عبارت «آقای دکتر فراهانی» یا «مهدی» در عبارت «مهدی حسنی» یا «علی» و «مجتبی» در  عبارت «علی مجتبی را دوست دارد» (چون علی و مجتبی دو شخص یا موجودیت مجزا و غیر وابسته هستند)",
            "Shortcut": "alt+p"
        },
        {
            "Title": "I-PER",
            "Color": "#4caf50",
            "PersianName": "شخص",
            "Description": "اسم، فامیل یا لقب شخص (بغیر از اولین کلمه عبارت منتسب به آن شخص). مثال: «دکتر» و «فراهانی» در عبارت «آقای دکتر فراهانی» یا «حسنی» در عبارت «مهدی حسنی»",
            "Shortcut": "p"
        },
...
}

خروجی این متد، آرایه‌ای از تگ‌های استاندارد است که در آن تگ انگلیسی استاندارد با Title و اسم فارسی تگ با PersianName و مثال استفاده از تگ با Description و رنگ بک گراند تگ با Color و همچنین کلید میانبر تگ با Shortcut مشخص شده است

تگ‌های استاندارد NER

چه در زمان دریافت جمله تصادفی و چه در زمان ثبت یک تگ (برچسب) برای کلمات آن جمله، یکی از تگ‌های زیر مورد استفاده قرار می‌گیرد:

  • B-PER برای تگ شروع شخص
  • I-PER برای تگ شخص
  • B-ORG برای تگ شروع سازمان
  • I-ORG برای تگ سازمان
  • B-LOC برای تگ شروع مکان
  • B-LOC برای تگ مکان
  • B-EVE برای تگ شروع رویداد
  • I-EVE برای تگ رویداد
  • B-DAT برای تگ شروع تاریخ و زمان
  • I-DAT برای تگ تاریخ و زمان
  • O برای تگ سایر موارد غیر از موارد بالا
Clone this wiki locally