متدهای وب سرویس پوش نوتیفیکیشن (بخش اول)
در مقاله قبل در مورد مقدمه و معرفی وب سرویس پوش نوتیفیکیشن صحبت کردیم در این مقاله قصد داریم در مورد متدهای API پوش نوتیفیکیشن (بخش اول) صحبت کنیم.
درگاه‌های بفرست
در ادامه به تشریح درگاه‌های بفرست می‌پردازیم. در مطالعه مستندات درگاه‌ها لطفا به این نکات دقت کنید.
- پیش از آدرس هریک از درگاه‌ها، Request method آن درگاه مشخص شده است.
- AID و CHID در آدرس هر یک از درگاه‌ها می‌بایست با مقادیر معتبر جایگزین شوند.
- فیلد errorCode در پاسخ درگاه‌ها، نمایانگر نتیجه کلی درخواست است. مقدار ۰ به معنای انجام موفقیت آمیز درخواست است. در صورت بروز خطا مقدار مرتبط با آن خطا در errorCode و پیامی در رابطه با آن خطا در فیلدی با نام message دریافت خواهید کرد.
ساخت رشته auth
auth رشته‌ای است که به منظور تشخیص هویت کاربر در درخواست‌هایی که به بفرست ارسال می‌کند استفاده می‌شود. این توکن با استفاده از آدرس درگاهی که قصد فراخوانی آن را دارید و API Key تولید می‌شود و به روش زیر ساخته می شود:
- ابتدا آدرس درگاهی که قصد فراخوانی آن را دارید به دو بخش (پروتکل + دامنه + پورت) و آدرس پس از دامنه تقسیم کنید. برای مثال در آدرس https://gw.bef.rest/xapi/2/publish/AID/CHID بخش اول https://gw.bef.rest و بخش دوم xapi/2/publish/AID/CHID/ خواهد بود. بخش دوم آدرس را addr بنامید.
- رشته‌ای با فرمت [addr][apikey] شکل دهید. دقت داشته باشید که addr و apikey به هم چسبیده باشند و هیچ کاراکتر دیگری میان آنها وجود نداشته باشد.
- در مرحله آخر رشته بدست آمده از کنار هم قرار دادن addr و API Key را با استفاده از الگوریتم MD5 هش کنید. رشته به دست آمده AUTH token است.
ارسال پیام به کانال
POST: https://api.bef.rest/xapi/2/publish/AID/CHID
با فراخوانی این درگاه می‌توانید همانطور که در بخش شروع کنیم دیدید، به کاربر (CHID) پیامی را ارسال کنید.
– Headers:
X-BF-AUTH : رشته auth باید با استفاده از این هدر ارسال شود.
X-BF-TTL : این هدر برای مشخص کردن مدت زمانی که می خواهید پیام شما در صف فعال بماند به ثانیه است. حداکثر مقدار ممکن برای این هدر ۱۲۰۹۶۰۰، معادل ۱۴ روز می‌باشد. به عنوان مثال اگر شما مقدار این پارامتر برای یک پیام را ۳۶۰۰ وارد کنید، درصورتی که کاربر مورد نظر آنلاین نباشد، این پیام تا یک ساعت در صف پیام‌های کاربر فعال باقی می‌ماند و در صورتی که کاربر بعد از گذشت یک ساعت برخط نشود، پیام به او نخواهد رسید.
– Parameters:
در ارسال درخواست به این درگاه، بدنه درخواست می‌بایست به صورت raw حاوی پیامی باشد که می‌خواهید به کاربر ارسال شود.
– Response:
- فیلد messageId در entity شناسه‌ای است که بفرست به پیام ارسال شده نسبت داده است.
- فیلد channelId در entity نشانگر (CHID) ای است که پیام به وی ارسال شده است.
- subscribers تعداد کاربران متصل با استفاده از (CHID) مشخص شده در درخواست است.
{
“errorCode”: 0,
“entity”: {
“messageId”: “xxx”,
“channelId”: “zzz”,
“subscribers”: 0
}
}
بررسی وضعیت پیام
GET: https://api.bef.rest/xapi/2/message-status/AID/MESSAGE-ID
با فراخوانی این درگاه می‌توانید از وضعیت پیامی که از پیش ارسال شده است اطلاع پیدا کنید.
– Headers:
X-BF-AUTH : رشته auth باید با استفاده از این هدر ارسال شود.
– Response:
- مقدار فیلد status در entity نشانگر وضعیت پیام ارسال شده است. D به معنای دریافت شده، Q به معنای صف شده (کاربر در اولین اتصال، پیام را دریافت خواهد کرد) و E به معنای منقضی شدن پیام است (کاربر پس از ارسال پیام، آنلاین نشده است و پیام پس از گذشت زمان پیش فرض که ۱۰ روز است منقضی شده است).
{
“errorCode”: 0,
“entity”: {
“status”: “D/Q/E”
}
}
ارسال پیام گروهی
POST: https://api.bef.rest/xapi/2/multi-publish/AID
با فراخوانی این درگاه می‌توانید پیامی را به چندین (CHID) ارسال کنید.
– Headers:
X-BF-AUTH : رشته auth باید با استفاده از این هدر ارسال شود.
X-BF-TTL : مقدار این هدر مشخص کننده مدت زمانی (ثانیه) است که پیام در صورت برخط نبودن کاربر در صف باقی خواهد ماند. حداکثر مقدار ممکن ۱۲۰۹۶۰۰، معادل ۱۴ روز است. به عنوان مثال اگر از مقدار ۳۶۰۰ برای این هدر استفاده کنید، در صورتی که کاربر مورد نظر برخط نباشد، پیام ارسال شده تا یک ساعت در صف پیام‌های کاربر، فعال باقی خواهد ماند و در صورتی که کاربر بعد از گذشت یک ساعت برخط نشود، پیام از صف پیام‌های وی حذف خواهد شد.
X-BF-CH : با استفاده از این هدر، کانال‌های دریافت کننده را مشخص می‌کنید. شناسه کانال‌ها می‌بایست با استفاده از کاراکتر کاما (,) از یکدیگر جدا شوند. برای مثال اگر قصد دارید پیامی را به کانال‌هایی که با شناسه‌های ۱، ۲ و ۳ ارسال کنید می‌بایست مقدار ۱,۲,۳ در هدر X-BF-CH قرار داده شود.
نکته: رشته‌ای که در هدر X-BF-CH قرار داده می‌شود می‌تواند حداکثر ۶ کیلوبایت باشد. در صورتی که رشته‌ای بزرگتر از ۶ کیلوبایت در این هدر قرار گیرد پاسخی با کد ۴۱۳ دریافت خواهید کرد.
– Parameters:
در ارسال درخواست به این درگاه، بدنه درخواست می‌بایست به صورت raw حاوی پیامی باشد که می‌خواهید به کانال‌های مشخص شده ارسال شود.
– Response:
- مقدار ۰ در فیلد errorCode نشانگر آن است که عملیات انتشار در تاپیک مشخص شده در درخواست با موفقیت انجام شده است. در صورت بروز خطا فیلد
- message به پاسخ افزوده خواهد شد که حاوی پیام خطای رخ داده است.
- فیلد messageId در entity شناسه پیام ارسال شده را نشان می‌دهد.
{
“errorCode”: 0,
“entity”: {
“messageId”: “xyz”
}
}
در مقاله بعد در مورد متدهای وب سرویس پوش نوتیفیکشن بخش دوم صحبت خواهیم کرد.