آموزش نصب و راه اندازی وب هوک (webhooks) در BigBlueButton

آموزش نصب و راه اندازی وب هوک (webhooks) در BigBlueButton
این یک برنامه node.js است که به همه رویدادها در BigBlueButton گوش می دهد و درخواست های POST را با جزئیات مربوط به این رویدادها به هوک هایی که از طریق یک API ثبت شده اند ارسال می کند. هوک یک URL خارجی است که می تواند درخواست های HTTP POST را دریافت کند.
این هوک های وب به برنامه های شخص ثالث اجازه می دهد تا در رویدادهای مختلفی که در طول جلسه BigBlueButton رخ می دهد مشترک شوند. یک رویداد می تواند این باشد: یک جلسه ایجاد شد، یک کاربر ملحق شد، یک ارائه جدید آپلود شد، یک کاربر رفت، یک ضبط در حال پردازش است و بسیاری موارد دیگر.
شما می توانید کل لیست رویدادهایی را که تماس های وب هوک ایجاد می کنند را در این فایل مشاهده کنید.
نصب و راه اندازی
برای نصب وب هوک، دستور زیر را در سرور BigBlueButton خود اجرا کنید:
<span class="nv">$ </span><span class="nb">sudo </span>apt-get <span class="nb">install </span>bbb-webhooks
این برنامه سه تماس API جدید به API BigBlueButton اضافه می کند.
Hooks / ایجاد
یک webhooks جدید ایجاد می کند. این تماس بیتوان است: میتوانید چندین بار با همان پارامترها بدون عوارض جانبی آن را تماس بگیرید (دقیقاً مانند create
تماس برای جلسات).
می تواند به صورت اختیاری یک meetingID
پارامتر را دریافت کند: در صورت اطلاع، این webhooks فقط رویدادهای این جلسه را دریافت می کند. در غیر این صورت هوک جهانی خواهد بود و رویدادها را برای تمام جلسات در سرور دریافت می کند.
یک هوک در هر زمان قابل ثبت است. حتی قلابهای مخصوص meetingID
s را میتوان ثبت کرد حتی اگر هنوز ملاقاتی با آن شناسه وجود نداشته باشد. پس از ایجاد جلسه، هوک رویدادهای خود را دریافت خواهد کرد.
هوک ها به طور دائم در redis ذخیره می شوند و تا زمانی که قلاب به طور صریح از طریق API حذف نشود فعال می شوند.
پارامترها :
نام پارامتر | الزامی / اختیاری | تایپ کنید | شرح |
---|---|---|---|
callbackURL | ضروری | رشته | نشانی اینترنتی که یک تماس POST با رویدادها دریافت می کند. همان URL را نمی توان بیش از یک بار ثبت کرد. |
شناسه جلسه | اختیاری | رشته | A meetingID برای اتصال این هوک به یک جلسه خاص. در صورت عدم اطلاع، هوک رویدادها را برای همه جلسات دریافت خواهد کرد. |
شناسه رویداد | اختیاری | رشته | یک لیست eventID یا یک لیست جدا شده با کاما eventID برای اتصال این قلاب. در صورت عدم اطلاع، هوک همه رویدادها را دریافت خواهد کرد. (نسخه 2.5) |
دریافت خام | اختیاری | بولی | به طور پیش فرض نادرست است. وقتی getRaw=true، تماس POST دقیقاً حاوی همان پیامی است که در redis ارسال میشود، در غیر این صورت پیام پردازش میشود. |
پاسخ زمانی که یک webhooks با موفقیت ثبت شد :
<span class="nt"><response></span>
<span class="nt"><returncode></span>SUCCESS<span class="nt"></returncode></span>
<span class="nt"><hookID></span>1<span class="nt"></hookID></span>
<span class="nt"><permanentHook></span>false<span class="nt"></permanentHook></span>
<span class="nt"><rawData></span>false<span class="nt"></rawData></span>
<span class="nt"></response></span>
پاسخ زمانی که یک webhooks قبلاً ثبت شده است :
<span class="nt"><response></span>
<span class="nt"><returncode></span>SUCCESS<span class="nt"></returncode></span>
<span class="nt"><hookID></span>1<span class="nt"></hookID></span>
<span class="nt"><messageKey></span>duplicateWarning<span class="nt"></messageKey></span>
<span class="nt"><message></span>There is already a hook for this callback URL.<span class="nt"></message></span>
<span class="nt"></response></span>
پاسخ زمانی که در ثبت webhooks خطایی رخ داد :
<span class="nt"><response></span>
<span class="nt"><returncode></span>FAILED<span class="nt"></returncode></span>
<span class="nt"><messageKey></span>createHookError<span class="nt"></messageKey></span>
<span class="nt"><message></span>An error happened while creating your hook. Check the logs.<span class="nt"></message></span>
<span class="nt"></response></span>
Hooks/Destroy
هوک ایجاد شده قبلی را بردارید. برای شناسایی هوکی که باید برداشته شود، باید یک hookID
در پارامترها ارسال شود.
پارامترها :
نام پارامتر | الزامی / اختیاری | تایپ کنید | شرح |
---|---|---|---|
شناسه هوک | ضروری | عدد | شناسه هوکی که باید برداشته شود، همانطور که در تماس ایجاد هوک بازگردانده شده است. |
پاسخ زمانی که یک هوک با موفقیت برداشته شد :
<span class="nt"><response></span>
<span class="nt"><returncode></span>SUCCESS<span class="nt"></returncode></span>
<span class="nt"><removed></span>true<span class="nt"></removed></span>
<span class="nt"></response></span>
پاسخ زمانی که یک هوک پیدا نشد :
<span class="nt"><response></span>
<span class="nt"><returncode></span>FAILED<span class="nt"></returncode></span>
<span class="nt"><messageKey></span>destroyMissingHook<span class="nt"></messageKey></span>
<span class="nt"><message></span>The hook informed was not found.<span class="nt"></message></span>
<span class="nt"></response></span>
پاسخ زمانی که یک هوک در پارامترها ارسال نشده است :
<span class="nt"><response></span>
<span class="nt"><returncode></span>FAILED<span class="nt"></returncode></span>
<span class="nt"><messageKey></span>missingParamHookID<span class="nt"></messageKey></span>
<span class="nt"><message></span>You must specify a hookID in the parameters.<span class="nt"></message></span>
<span class="nt"></response></span>
پاسخ زمانی که در برداشتن هوک خطایی رخ داد :
<span class="nt"><response></span>
<span class="nt"><returncode></span>FAILED<span class="nt"></returncode></span>
<span class="nt"><messageKey></span>destroyHookError<span class="nt"></messageKey></span>
<span class="nt"><message></span>An error happened while removing your hook. Check the logs.<span class="nt"></message></span>
<span class="nt"></response></span>
Hooks/List
webhooks های ثبت شده را برمی گرداند. اگر a meetingID
مطلع شود، هوک های ایجاد شده بهطور خاص برای این جلسه به اضافه همه هوک های جهانی را برمیگرداند (زیرا آنها نیز رویدادهایی را برای این کار دریافت میکنند meetingID
). اگر نه meetingID
اطلاع داده شود، همه هوک های موجود را برمیگرداند (نه تنها هوک های سراسری، همانطور که انتظار میرود).
پارامترها :
نام پارامتر | الزامی / اختیاری | تایپ کنید | شرح |
---|---|---|---|
شناسه جلسه | اختیاری | رشته | شناسه جلسه برای محدود کردن هوک ها فقط به هوک هایی که رویدادهای این جلسه را دریافت میکنند بازگردانده میشود. شامل هوک هایی میشود که رویدادها را فقط برای این جلسه دریافت میکنند به اضافه همه هوک های جهانی. |
پاسخ زمانی که هوک ها ثبت شده اند :
<span class="nt"><response></span>
<span class="nt"><returncode></span>SUCCESS<span class="nt"></returncode></span>
<span class="nt"><hooks></span>
<span class="nt"><hook></span>
<span class="nt"><hookID></span>1<span class="nt"></hookID></span>
<span class="nt"><callbackURL></span><span class="cp"><![CDATA[http://postcatcher.in/catchers/abcdefghijk]]></span><span class="nt"></callbackURL></span>
<span class="nt"><meetingID></span><span class="cp"><![CDATA[my-meeting</meetingID]]></span>> <span class="c"><!-- a hook created for this meeting only --></span>
<span class="nt"><permanentHook></span>false<span class="nt"></permanentHook></span>
<span class="nt"><rawData></span>false<span class="nt"></rawData></span>
<span class="nt"></hook></span>
<span class="nt"><hook></span>
<span class="nt"><hookID></span>2<span class="nt"></hookID></span>
<span class="nt"><callbackURL></span><span class="cp"><![CDATA[http://postcatcher.in/catchers/1234567890]]></span><span class="nt"></callbackURL></span>
<span class="c"><!-- no meetingID means this is a global hook --></span>
<span class="nt"><permanentHook></span>false<span class="nt"></permanentHook></span>
<span class="nt"><rawData></span>false<span class="nt"></rawData></span>
<span class="nt"></hook></span>
<span class="nt"></hooks></span>
<span class="nt"></response></span>
پاسخ زمانی که هیچ هوکی ثبت نشده است :
<span class="nt"><response></span>
<span class="nt"><returncode></span>SUCCESS<span class="nt"></returncode></span>
<span class="nt"><hooks></hooks></span>
<span class="nt"></response></span>
قالب برگشت به تماس
همه هوک های ثبت شده از طریق HTTP POST با تمام اطلاعات مربوط به رویداد در بدنه این درخواست فراخوانی می شوند. درخواست با Content-type
تنظیم هدر HTTP ارسال می شود application/x-www-form-urlencoded
و محتوای موجود در بدنه فرمت زیر را دارد (وقتی getRaw=false):
<span class="nx">event</span><span class="o">=</span><span class="p">{</span><span class="dl">"</span><span class="s2">data</span><span class="dl">"</span><span class="p">:{</span><span class="dl">"</span><span class="s2">type</span><span class="dl">"</span><span class="p">:</span><span class="dl">"</span><span class="s2">event</span><span class="dl">"</span><span class="p">,</span><span class="dl">"</span><span class="s2">attributes</span><span class="dl">"</span><span class="p">:{},</span><span class="dl">"</span><span class="s2">event</span><span class="dl">"</span><span class="p">:{</span><span class="dl">"</span><span class="s2">ts</span><span class="dl">"</span><span class="p">:</span><span class="mi">0</span><span class="p">}}}</span>
<span class="nx">timestamp</span><span class="o">=</span><span class="mi">1415900488797</span>
این ویژگی timestamp
زمانی است که این تماس برگشتی برقرار شد. اگر برنامه web hooks سعی کند یک تماس برقرار کند و شکست بخورد، چندین بار دوباره تلاش میکند و همیشه از همان timestamp
استفاده میکند. timestamp
برای رویدادهای مختلف هرگز یکسان نخواهد بود و ارزش همیشه افزایش می یابد.
ویژگی event
یک نسخه رشته ای از تمام داده های رویداد است (همانطور که از redis دریافت می شود اگر getRaw=true، پردازش می شود اگر getRaw=false). داده ها برای انواع مختلف رویدادها متفاوت است، برای اطلاعات بیشتر اسناد را بررسی کنید.
این نمونه ای از داده های ارسال شده برای یک رویداد از بین رفته جلسه است که getRaw=false است:
<span class="nx">event</span><span class="o">=</span><span class="p">{</span><span class="dl">"</span><span class="s2">data</span><span class="dl">"</span><span class="p">:{</span><span class="dl">"</span><span class="s2">type</span><span class="dl">"</span><span class="p">:</span><span class="dl">"</span><span class="s2">event</span><span class="dl">"</span><span class="p">,</span><span class="dl">"</span><span class="s2">id</span><span class="dl">"</span><span class="p">:</span><span class="dl">"</span><span class="s2">meeting-ended</span><span class="dl">"</span><span class="p">,</span><span class="dl">"</span><span class="s2">attributes</span><span class="dl">"</span><span class="p">:{</span><span class="dl">"</span><span class="s2">meeting</span><span class="dl">"</span><span class="p">:{</span><span class="dl">"</span><span class="s2">internal-meeting-id</span><span class="dl">"</span><span class="p">:</span><span class="dl">"</span><span class="s2">44ea85d9684005d3b0af3c49e8a271a683cedb79-1532718208098</span><span class="dl">"</span><span class="p">,</span><span class="dl">"</span><span class="s2">external-meeting-id</span><span class="dl">"</span><span class="p">:</span><span class="dl">"</span><span class="s2">random-3800337</span><span class="dl">"</span><span class="p">}},</span><span class="dl">"</span><span class="s2">event</span><span class="dl">"</span><span class="p">:{</span><span class="dl">"</span><span class="s2">ts</span><span class="dl">"</span><span class="p">:</span><span class="mi">1532718316938</span><span class="p">}}}</span>
<span class="nx">timestamp</span><span class="o">=</span><span class="mi">1532718316953</span>
این همان رویداد برای یک هوک دیگر با getRaw=true است:
<span class="nx">event</span><span class="o">=</span><span class="p">{</span><span class="dl">"</span><span class="s2">envelope</span><span class="dl">"</span><span class="p">:{</span><span class="dl">"</span><span class="s2">name</span><span class="dl">"</span><span class="p">:</span><span class="dl">"</span><span class="s2">MeetingDestroyedEvtMsg</span><span class="dl">"</span><span class="p">,</span><span class="dl">"</span><span class="s2">routing</span><span class="dl">"</span><span class="p">:{</span><span class="dl">"</span><span class="s2">sender</span><span class="dl">"</span><span class="p">:</span><span class="dl">"</span><span class="s2">bbb-apps-akka</span><span class="dl">"</span><span class="p">}},</span><span class="dl">"</span><span class="s2">core</span><span class="dl">"</span><span class="p">:{</span><span class="dl">"</span><span class="s2">header</span><span class="dl">"</span><span class="p">:{</span><span class="dl">"</span><span class="s2">name</span><span class="dl">"</span><span class="p">:</span><span class="dl">"</span><span class="s2">MeetingDestroyedEvtMsg</span><span class="dl">"</span><span class="p">},</span><span class="dl">"</span><span class="s2">body</span><span class="dl">"</span><span class="p">:{</span><span class="dl">"</span><span class="s2">meetingId</span><span class="dl">"</span><span class="p">:</span><span class="dl">"</span><span class="s2">44ea85d9684005d3b0af3c49e8a271a683cedb79-1532718208098</span><span class="dl">"</span><span class="p">}}}</span>
<span class="nx">timestamp</span><span class="o">=</span><span class="mi">1532718316953</span>
علاوه بر این، تماس برگشتی با یک چکسام امضا میشود که در URL درخواست موجود است. اگر URL ثبت شده باشد http://my-server.com/callback
، چک سام را در http://my-server.com/callback?checksum=yalsdk18129e019iklasd90i
دریافت خواهد کرد.
نحوه ایجاد چکسام شبیه نحوه محاسبه چکسامها برای سایر فراخوانهای API BigBlueButton است (به . نگاهی بیندازید setConfigXML
).
sha1(<callback URL>+<data body>+<shared secret>)
جایی که:
<callback URL>
: نشانی وب اصلی پاسخ به تماس، که شامل چکسام نمیشود.<data body as a string>
: تمام داده هایی که در بدنه درخواست ارسال می شوند، به هم پیوسته اند&
، گویی که پارامترهایی در یک URL هستند.<shared secret>
: راز مشترک سرور BigBlueButton.
بنابراین، پس از دریافت تماس برگشتی، یک برنامه کاربردی میتواند چکسام را به صورت زیر تأیید کند:
- متن درخواست را مانند مثال زیر دریافت میکنید:
<span class="nx">event</span><span class="o">=</span><span class="p">{</span><span class="dl">"</span><span class="s2">data</span><span class="dl">"</span><span class="p">:{</span><span class="dl">"</span><span class="s2">type</span><span class="dl">"</span><span class="p">:</span><span class="dl">"</span><span class="s2">event</span><span class="dl">"</span><span class="p">,</span><span class="dl">"</span><span class="s2">attributes</span><span class="dl">"</span><span class="p">:{},</span><span class="dl">"</span><span class="s2">event</span><span class="dl">"</span><span class="p">:{</span><span class="dl">"</span><span class="s2">ts</span><span class="dl">"</span><span class="p">:</span><span class="mi">0</span><span class="p">}}}</span>
<span class="nx">timestamp</span><span class="o">=</span><span class="mi">1234567890</span>
And convert it to a string like in the example below:
<span class="nx">event</span><span class="o">=</span><span class="p">{</span><span class="dl">"</span><span class="s2">data</span><span class="dl">"</span><span class="p">:{</span><span class="dl">"</span><span class="s2">type</span><span class="dl">"</span><span class="p">:</span><span class="dl">"</span><span class="s2">event</span><span class="dl">"</span><span class="p">,</span><span class="dl">"</span><span class="s2">attributes</span><span class="dl">"</span><span class="p">:{},</span><span class="dl">"</span><span class="s2">event</span><span class="dl">"</span><span class="p">:{</span><span class="dl">"</span><span class="s2">ts</span><span class="dl">"</span><span class="p">:</span><span class="mi">0</span><span class="p">}}}</span>
<span class="nx">timestamp</span><span class="o">=</span><span class="mi">1234567890</span>
جزئیات بیشتر
- پاسخ به تماس همیشه برای یک رویداد در یک زمان و به ترتیب فعال می شود. آنها به همین ترتیب سفارش می شوند
آنها در redis pubsub ظاهر می شوند (که ممکن است دقیقاً به ترتیبی نباشد که توسط
timestamp
نشان داده شده است).مُهرهای زمانی (
timestamp
) نیز تقریباً همیشه سفارش داده میشوند، اما تضمینی نیست. - برنامه فرض می کند که رویدادها هرگز در pubsub تکرار نمی شوند. اگر اتفاقی بیفتد تماس های برگشتی نیز تکراری خواهند شد.
- هوک ها فقط در صورتی برداشته میشوند که تماسی برقرار
/hooks/destroy
شود یا اگر تماسهای برگشتی برای هوک نیز انجام نشود. - این برنامه از نقشههای داخلی استفاده میکند تا بفهمد رویدادها از redis به کدام جلسه رسیده است.
- انتظار می رود URL های خارجی با وضعیت HTTP 2xx پاسخ دهند (200 پیش فرض مورد انتظار خواهد بود).
هر چیزی که با این مقادیر متفاوت باشد خطا در نظر گرفته می شود و callback فراخوانی می شود.
- اگر در حالی که برنامه web hooks خاموش است، جلسه ای ایجاد شود، تماس های پاسخ هرگز راه اندازی نمی شوند
برای این جلسه برنامه باید رویداد ایجاد (
meeting_created_message
) را شناسایی کند.
امتحانش کن
ساده ترین راه برای آزمایش برنامه webhooks این است که هوک ها را با استفاده از API Mate در سرور BigBlueButton خود ثبت کنید و با استفاده از سرویس PostCatcher تماس ها را ضبط کنید.
مراحل را دنبال کنید:
- PostCatcher را باز کنید و روی “شروع آزمایش درخواست های POST خود را اکنون شروع کنید” کلیک کنید.
- شما را به یک URL مانند
http://postcatcher.in/catchers/5527e67ba4c6dd0300000738
منتقل میکند.این URL را ذخیره کنید تا بعدا استفاده کنید.
- API Mate را باز کنید و سرور و سکرت خود را پیکربندی کنید.
- در منوی «پارامترهای سفارشی»، فیلد «Custom API calls:» وجود دارد. این مقادیر را به آن اضافه کنید:
hooks/create
hooks/list
- در همان بخش منو، مقادیر زیر را به “پارامترهای سفارشی” اضافه کنید:
callbackURL=http://postcatcher.in/catchers/5527e67ba4c6dd0300000738
Modify this URL to the URL you got from PostCatcher earlier
- در API Mate، روی پیوند «تماس سفارشی: هوک/ایجاد» کلیک کنید. باید با موفقیت پاسخ دهد.
- در API Mate، روی پیوند «تماس سفارشی: hooks/list» کلیک کنید تا بررسی کنید که آیا هوک شما واقعاً ثبت شده است یا خیر.
- یک جلسه ایجاد کنید و با استفاده از API Mate به آن بپیوندید.
- کارهایی را در داخل جلسه انجام دهید و صفحه PostCatcher خود را بررسی کنید، باید ببینید که رویدادها در آن ظاهر می شوند.
همانطور که در جلسه خود تعامل دارید.
# webhooks # webhooks # webhooks
دیدگاهتان را بنویسید
برای نوشتن دیدگاه باید وارد بشوید.