متدهای وب سرویس پوش نوتیفیکیشن (بخش دوم)
در مقاله قبل در مورد مقدمه و معرفی وب سرویس پوش نوتیفیکیشن و متدهای آن (بخش اول) صحبت کردیم در این مقاله متدهای 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 است.
بررسی وضعیت تاپیک
GET: https://api.bef.rest/xapi/2/topic-status/AID/TOPIC-NAME
با فراخوانی این درگاه میتوانید وضعیت هر یک از تاپیکهای خود در بفرست را بررسی کنید.
– Headers:
X-BF-AUTH : رشته auth باید با استفاده از این هدر ارسال شود.
– Response:
- مقدار ۰ در فیلد errorCode نشانگر آن است که بررسی وضعیت تاپیک بدون مشکل انجام شده است و پاسخ دریافت شده قابل استفاده است.
- فیلد messages در پاسخ، نشان دهنده تعداد کل پیامهای منتشر شده در تاپیک است.
- فیلد activeMessages در پاسخ، نشان دهنده تعداد پیامهای فعال تاپیک است.
- فیلد onlineChannels در پاسخ، نشان دهنده تعداد کاربران برخط است پیامهای تاپیک را دریافت میکنند.
- فیلد deliveries در پاسخ، نشان دهنده تعداد تجمیعی دریافتهای پیامهای تاپیک است.
{
“errorCode”: 0,
“entity”: {
“name”: “topic”,
“messages”: 1,
“activeMessages”: 0,
“onlineChannels”: 79,
“deliveries”: 21
}
}
بررسی وضعیت پیام تاپیک
GET: https://api.bef.rest/xapi/2/topic-msg-status/AID/TOPIC-NAME/MID
با فراخوانی این درگاه میتوانید وضعیت هر یک از پیامهای تاپیکهای خود در بفرست را بررسی کنید.
– Headers:
X-BF-AUTH : رشته auth باید با استفاده از این هدر ارسال شود.
– Response:
- مقدار ۰ در فیلد errorCode نشانگر آن است که بررسی وضعیت پیام تاپیک بدون مشکل انجام شده است و پاسخ دریافت شده قابل استفاده است.
- فیلد message در پاسخ، نشان دهنده متن پیام منتشر شده در تاپیک است.
- فیلد created در پاسخ، نشان دهنده Unix timestamp ارسال پیام تاپیک است.
- فیلد ttl در پاسخ، نشان دهنده مدت زمان اعتبار (ثانیه) پیام تاپیک است.
- فیلد status در پاسخ، نشان دهنده وضعیت پیام است. مقدار ACTIVE گویای این مطلب است که کاربرانی که هنوز پیام تاپیک را دریافت نکردهاند، پس از اتصال، پیام را دریافت خواهند کرد. مقدار EXPIRED نیز نشان دهنده این است که مدت اعتبار پیام تاپیک به پایان رسیده است.
- فیلد deliveries در پاسخ، نشان دهنده تعداد تجمیعی دریافتهای پیامهای تاپیک است.
{
“errorCode”: 0,
“entity”: {
“message”: “a sample message”,
“created”: 1454409003,
“ttl”: 120,
“status”: “ACTIVE”,
“deliveries”: 100
}
}
بررسی وضعیت کانال
GET: https://api.bef.rest/xapi/2/channel-status/AID/CHID
با فراخوانی این درگاه میتوانید آماری در مورد یک کانال (کاربر) خود دریافت کنید.
– Headers:
X-BF-AUTH : رشته auth باید با استفاده از این هدر ارسال شود.
– Response:
- فیلد storedMessages اشاره به تعداد پیامهای صف شده کانال دارد.
- فیلد subscribers نشان دهنده تعداد کاربران متصل به کانال مشخص شده است.
- فیلد publishedMessages نشان دهنده تعداد پیامهایی است که تاکنون برای کاربر با (CHID) مشخص شده ارسال شده است.
“errorCode”: 0,
“entity”: {
“storedMessages”: 1,
“subscribers”: 2,
“publishedMessages”: 3
}
}
اتصال کانال به بفرست
GET: https://gw.bef.rest/subscribe/AID/CHID/SDK-VERSION
با فراخوانی این درگاه اتصالی از نوع persistent در اختیار خواهید داشت که میتوانید پیامهای ارسالی را بر روی آن دریافت کنید.
– Headers:
X-BF-AUTH : رشته auth باید با استفاده از این هدر ارسال شود.
X-BF-TOPICS : لیست تاپیک هایی که کاربر میخواهد پیامهای آنها را دریافت کند. تاپیکها میبایست با کاراکتر دش (-) از یکدیگر جدا شوند. همه کاربران حین subscription به صورت پیشفرض در تاپیکی به نام all سابیکرایب میشوند که در صورت نیاز به ارسال پیام به همه کاربران، میتوان با publish کردن بر روی تاپیک all این کار را انجام داد.
– Response:
به دلیل از نوع persistent بودن اتصال درخواست subscription، پاسخی که دریافت میکنید از نوع Handshaking است. صرفا پیامهای ارسالی در خروجی این اتصال دریافت خواهند شد.
برای دریافت راهنمای کامی این وب سرویس و همچنین نمونه کدها از این لینک اقدام نمایید