اکشن‌ها

اکشن شخصی‌سازی شده

API خودتان را به موچت متصل کنید، ورودی‌ها را تعریف کنید و دسترسی ربات به پاسخ را کنترل کنید.

مرور کلی

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

مناسب برای

کاری که از طریق API قابل انجام است؛ مثل رهگیری سفارش فروشگاه اختصاصی، استعلام موجودی، بررسی وضعیت درخواست یا تغییر اشتراک در سامانهٔ شما.

اتصال فروشگاه یا سامانهٔ اختصاصی

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

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

برای شروع، مثال رهگیری سفارش غیر ووکامرسی را ببینید. برای فروشگاه ووکامرسی، اکشن آمادهٔ رهگیری سفارش راهنمای جداگانه دارد.

ساخت اکشن

اکشن جدید بسازید

در اکشن‌ها، ایجاد اکشن و سپس اکشن شخصی‌سازی شده را انتخاب کنید.

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

نام و توضیح زمان اجرا را وارد کنید و ذخیره و ادامه را بزنید.

نوع اکشن را انتخاب کنید

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

ورودی‌ها و درخواست را تنظیم کنید

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

پاسخ را آزمایش کنید

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

ذخیره و فعال کنید

ایجاد اکشن را بزنید، وضعیتش را در اکشن‌های من بررسی کنید و یک درخواست مناسب را در آزمایشگاه امتحان کنید.

تنظیمات عمومی

نام اکشن: نامی روشن برای کاری که انجام می‌دهد انتخاب کنید؛ مثلاً Get_Weather.

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

تنظیم نام Get_Weather و دستور پرسیدن نام شهر در صورت مشخص نبودن آن
نام اکشن و توضیح دقیق زمان اجرا برای نمونهٔ آب‌وهوا

API

اطلاعات موردنیاز اکشن

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

تنظیمکاربرد
نامنام متغیر؛ برای استفاده در قالب درخواست، نامی مانند city یا request_id انتخاب کنید
نوعمتن (string)، عدد (number)، مقدار منطقی (boolean) یا شیء (object)
توضیحمعنی ورودی و قالب موردانتظار؛ این توضیح به موچت کمک می‌کند سؤال درست بپرسد
اجباریمشخص می‌کند اجرای اکشن به این ورودی نیاز دارد
آرایهمشخص می‌کند ورودی فهرستی از مقادیر همان نوع است

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

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

درخواست API

روش درخواست را از GET، POST، PUT، PATCH یا DELETE انتخاب کنید و URL کامل API را وارد کنید. ورودی‌ها را با قالب دو آکولاد، مانند {{city}}، در بخش‌های درخواست قرار دهید:

بخشنمونه و کاربرد
URLقرار دادن متغیر در مسیر، مثل https://api.example.com/requests/{{request_id}}
پارامترهاجفت کلید و مقدار برای Query string؛ مثل city با مقدار {{city}}
هدرهدرهای موردنیاز API، مانند Authorization یا Accept
بدنهدادهٔ JSON برای روش‌هایی که بدنه می‌پذیرند
تنظیم درخواست API آب‌وهوا با متغیر city و پارامتر format
متغیر city در URL قرار می‌گیرد و format با مقدار j1 در پارامترها نمایش داده می‌شود.

می‌توانید نام متغیر را مستقیماً با دو آکولاد بنویسید یا با ایجاد متغیر، ورودی تعریف‌شده را انتخاب کنید. با واردکردن Query string در URL، پارامترهای آن خودکار به جدول پارامترها اضافه می‌شوند.

هر متغیری که استفاده می‌کنید باید در ورودی‌ها تعریف شده باشد. ورودی اختیاری‌ای را که ممکن است خالی بماند، در بخش الزامی مسیر یا هدر قرار ندهید؛ خالی‌بودن مقدارِ متغیرِ استفاده‌شده مانع ساخت درخواست می‌شود.

برای GET بدنه نفرستید. در روش‌های دیگر، بدنه باید JSON معتبر باشد. اگر مقدار یک فیلد فقط متغیر باشد، نوع واقعی مقدار حفظ می‌شود؛ برای مثال در بدنهٔ زیر، quantity می‌تواند عدد و enabled مقدار منطقی بماند:

بدنهٔ JSON با ورودی‌های تعریف‌شده
{
  "quantity": "{{quantity}}",
  "enabled": "{{enabled}}"
}

برای این نمونه، ورودی quantity را از نوع number و enabled را از نوع boolean تعریف کنید. مقدار شیء یا آرایه را هم به‌عنوان کل مقدار یک فیلد بگذارید؛ آن را وسط متن یا URL قرار ندهید. کوتیشن و خط جدید داخل متن هنگام ساخت JSON به‌درستی کدگذاری می‌شوند.

تست خروجی

  • مستقیم: برای تست زنده، مقادیر آزمایشی ورودی‌ها را بدهید و تست خروجی را بزنید. وضعیت HTTP و JSON برگشتی را بررسی کنید. این درخواست واقعی است و می‌تواند داده‌های سرویس را تغییر دهد.
  • دیتا فرضی: وقتی می‌خواهید ساختار پاسخ را دستی تعریف کنید، نمونهٔ JSON وارد کنید. این کار ساختار و انتخاب فیلدها را آماده می‌کند؛ در گفتگوی واقعی همچنان API فراخوانی می‌شود.

پاسخ API باید JSON با ریشهٔ شیء یا آرایه باشد. پاسخ HTML، متن ساده یا پاسخ خالی برای این اکشن مناسب نیست. پس از تغییر URL، ورودی‌ها یا ساختار پاسخ، تست را دوباره انجام دهید و فیلدهای مجاز را بازبینی کنید.

پاسخ JSON واقعی API آب‌وهوا با وضعیت HTTP 200 و دکمهٔ مرحله بعد
تست Get_Weather با city برابر London؛ پس از پاسخ موفق، مرحلهٔ بعد را باز کنید.

دسترسی دیتا

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

برای نمونه، اگر API علاوه بر status و tracking_url، یادداشت داخلی هم برمی‌گرداند، فقط فیلدهای لازم برای پاسخ کاربر را انتخاب کنید. جدول، فیلدهای سطح اول پاسخ را نشان می‌دهد. انتخاب یک شیء یا آرایه، تمام محتوای زیرمجموعهٔ آن را هم در دسترس قرار می‌دهد؛ اگر فقط بخشی از آن باید به موچت برسد، پاسخ API را طوری تنظیم کنید که دادهٔ موردنیاز در فیلدی جدا برگردد.

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

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

مثال‌ها

رهگیری سفارش در فروشگاه‌های غیر ووکامرسی

این نمونه، قرارداد پیشنهادی برای API فروشگاه شماست. آدرس و نام فیلدها را با API واقعی فروشگاه هماهنگ کنید؛ اگر چنین APIای ندارید، ابتدا توسعه‌دهندهٔ فروشگاه آن را پیاده‌سازی کند.

اکشن Track_Order را با دو ورودی اجباری از نوع string بسازید:

  • order_id: شمارهٔ سفارشی که مشتری می‌خواهد پیگیری کند.
  • customer_phone: شمارهٔ تلفن ثبت‌شده هنگام خرید، با قالب موردانتظار API فروشگاه.

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

روش را POST انتخاب کنید و آدرس API فروشگاه را وارد کنید:

نمونهٔ آدرس API فروشگاه
https://api.example.com/orders/track
بدنهٔ درخواست
{
  "order_id": "{{order_id}}",
  "customer_phone": "{{customer_phone}}"
}

هدر Content-Type را برابر application/json بگذارید و هدر احراز هویت موردنیاز API، مانند Authorization: Bearer YOUR_API_KEY، را با کلید سرویس فروشگاه تنظیم کنید. کلید را از مشتری در گفتگو نخواهید.

API فروشگاه باید شماره سفارش و تلفن ثبت‌شده را با اطلاعات همان سفارش تطبیق دهد و اجازهٔ دسترسی را بررسی کند. کلید سرویس، ارتباط موچت با API را مجاز می‌کند؛ هویت مشتری و مالکیت سفارش باید جداگانه بررسی شوند. در صورت نبود سفارش یا تطبیق‌نداشتن اطلاعات، API نباید جزئیات سفارش را برگرداند.

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

نمونهٔ پاسخ API فروشگاه
{
  "order_id": "ORD-12345",
  "status": "shipped",
  "tracking_code": "TRK-123456",
  "tracking_url": "https://shop.example.com/track/TRK-123456"
}

در دسترسی دیتا محدود، فقط فیلدهای لازم برای پاسخ، مانند order_id، status، tracking_code و tracking_url را انتخاب کنید. وضعیت سفارش در لحظه از API خوانده می‌شود و لازم نیست سفارش‌ها را در پایگاه دانش بارگذاری کنید.

با یک سفارش آزمایشی و اطلاعات درست، تست خروجی را اجرا کنید؛ سپس شماره سفارش ناموجود و تلفن نادرست را هم امتحان کنید تا هیچ جزئیاتی از سفارش نمایش داده نشود. در آزمایشگاه و کانال مورداستفاده بپرسید «سفارشم کجاست؟» و بررسی کنید موچت ورودی‌های لازم را می‌پرسد و فقط بر اساس نتیجهٔ API پاسخ می‌دهد.

دریافت آب‌وهوا

اکشن Get_Weather را با یک ورودی اجباری به نام city از نوع string و توضیح «نام شهری که کاربر آب‌وهوایش را می‌خواهد» بسازید. روش را GET و URL را این مقدار قرار دهید:

URL درخواست
https://wttr.in/{{city}}?format=j1
واردکردن URL، انتخاب متغیر city و اضافه‌شدن خودکار پارامتر format

بدنه لازم نیست. در تست زنده، مقدار city را London بگذارید و تست خروجی را بزنید.

تست زنده با London و دریافت پاسخ JSON با وضعیت موفق

پس از دریافت پاسخ، دسترسی دیتا محدود را انتخاب کنید و فقط current_condition را فعال کنید. این بخش اطلاعات آب‌وهوای فعلی، از جمله temp_C، FeelsLikeC و weatherDesc را دارد. فیلدهای nearest_area، request و weather را انتخاب نکنید تا اطلاعات اضافی و پیش‌بینی چندروزه به موچت فرستاده نشود.

در آزمایشگاه بپرسید «آب‌وهوای لندن الان چطور است؟». بررسی کنید اکشن با ورودی درست اجرا شود و پاسخ بر اساس دادهٔ برگشتی باشد. اگر فقط «آب‌وهوا چطور است؟» بپرسید، موچت باید شهر را از شما بپرسد.

تغییر اشتراک از طریق API خودتان

اگر سرویس شما API تغییر اشتراک دارد، اکشن Update_Subscription را با دو ورودی اجباری subscription_id و plan از نوع string بسازید. در زمان اجرا بنویسید که فقط پس از مشخص‌شدن اشتراک و طرح درخواستی کاربر، تغییر را انجام دهد.

برای APIای با قرارداد زیر، روش PATCH را انتخاب کنید و آدرس API خودتان را جایگزین کنید:

URL درخواست
https://api.example.com/subscriptions/{{subscription_id}}
بدنهٔ درخواست
{
  "plan": "{{plan}}"
}

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

نمونهٔ ساختار پاسخ API شما
{
  "subscription_id": "sub_123",
  "plan": "premium",
  "status": "active"
}

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

محدودیت‌ها

  • مهلت اجرای درخواست حداکثر ۳۰ ثانیه است.
  • پاسخ خام API حداکثر 1 MiB است. داده‌ای که پس از اعمال دسترسی به موچت می‌رسد باید حداکثر 20 KiB باشد؛ برای پاسخ‌های بزرگ، فیلدهای محدود انتخاب کنید.
  • پاسخ باید وضعیت موفق HTTP 2xx داشته باشد. تغییر مسیر خودکار دنبال نمی‌شود؛ URL نهایی API را وارد کنید.
  • در حالت دسترسی محدود، ریشهٔ پاسخ باید شیء JSON باشد. برای آرایهٔ ریشه، پاسخ را در API خودتان داخل یک شیء قرار دهید یا با رعایت سقف حجم از دسترسی کامل استفاده کنید.

رفع مشکل

مستندات موچت

در این صفحه