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

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

این یک برنامه node.js است که به همه رویدادها در BigBlueButton گوش می دهد و درخواست های POST را با جزئیات مربوط به این رویدادها به هوک هایی که از طریق یک API ثبت شده اند ارسال می کند. هوک یک URL خارجی است که می تواند درخواست های HTTP POST را دریافت کند.

این هوک های وب به برنامه های شخص ثالث اجازه می دهد تا در رویدادهای مختلفی که در طول جلسه BigBlueButton رخ می دهد مشترک شوند. یک رویداد می تواند این باشد: یک جلسه ایجاد شد، یک کاربر ملحق شد، یک ارائه جدید آپلود شد، یک کاربر رفت، یک ضبط در حال پردازش است و بسیاری موارد دیگر. 

شما می توانید کل لیست رویدادهایی را که تماس های وب هوک ایجاد می کنند را در این فایل مشاهده کنید.

نصب و راه اندازی

برای نصب وب هوک، دستور زیر را در سرور BigBlueButton خود اجرا کنید:

$ sudo apt-get install bbb-webhooks

این برنامه سه تماس API جدید به API BigBlueButton اضافه می کند.

Hooks / ایجاد

یک webhooks جدید ایجاد می کند. این تماس بی‌توان است: می‌توانید چندین بار با همان پارامترها بدون عوارض جانبی آن را تماس بگیرید (دقیقاً مانند createتماس برای جلسات).

 می تواند به صورت اختیاری یک meetingIDپارامتر را دریافت کند: در صورت اطلاع، این webhooks فقط رویدادهای این جلسه را دریافت می کند. در غیر این صورت هوک جهانی خواهد بود و رویدادها را برای تمام جلسات در سرور دریافت می کند.

یک هوک در هر زمان قابل ثبت است. حتی قلاب‌های مخصوص meetingIDs را می‌توان ثبت کرد حتی اگر هنوز ملاقاتی با آن شناسه وجود نداشته باشد. پس از ایجاد جلسه، هوک رویدادهای خود را دریافت خواهد کرد.

هوک ها به طور دائم در redis ذخیره می شوند و تا زمانی که قلاب به طور صریح از طریق API حذف نشود فعال می شوند.

پارامترها :

پاسخ زمانی که یک webhooks با موفقیت ثبت شد :

<response>
  <returncode>SUCCESS</returncode>
  <hookID>1</hookID>
  <permanentHook>false</permanentHook>
  <rawData>false</rawData>
</response>

پاسخ زمانی که یک webhooks قبلاً ثبت شده است :

<response>
  <returncode>SUCCESS</returncode>
  <hookID>1</hookID>
  <messageKey>duplicateWarning</messageKey>
  <message>There is already a hook for this callback URL.</message>
</response>

پاسخ زمانی که در ثبت webhooks خطایی رخ داد :

<response>
  <returncode>FAILED</returncode>
  <messageKey>createHookError</messageKey>
  <message>An error happened while creating your hook. Check the logs.</message>
</response>

Hooks/Destroy

هوک ایجاد شده قبلی را بردارید. برای شناسایی هوکی که باید برداشته شود، باید یک hookIDدر پارامترها ارسال شود.

پارامترها :

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

<response>
  <returncode>SUCCESS</returncode>
  <removed>true</removed>
</response>

پاسخ زمانی که یک هوک پیدا نشد :

<response>
  <returncode>FAILED</returncode>
  <messageKey>destroyMissingHook</messageKey>
  <message>The hook informed was not found.</message>
</response>

پاسخ زمانی که یک هوک در پارامترها ارسال نشده است :

<response>
  <returncode>FAILED</returncode>
  <messageKey>missingParamHookID</messageKey>
  <message>You must specify a hookID in the parameters.</message>
</response>

پاسخ زمانی که در برداشتن هوک خطایی رخ داد :

<response>
  <returncode>FAILED</returncode>
  <messageKey>destroyHookError</messageKey>
  <message>An error happened while removing your hook. Check the logs.</message>
</response>

Hooks/List

webhooks های ثبت شده را برمی گرداند. اگر a meetingIDمطلع شود، هوک های ایجاد شده به‌طور خاص برای این جلسه به اضافه همه هوک های جهانی را برمی‌گرداند (زیرا آنها نیز رویدادهایی را برای این کار دریافت می‌کنند meetingID). اگر نه meetingIDاطلاع داده شود، همه هوک های موجود را برمی‌گرداند (نه تنها هوک های سراسری، همانطور که انتظار می‌رود).

پارامترها :

پاسخ زمانی که هوک ها ثبت شده اند :

<response>
  <returncode>SUCCESS</returncode>
  <hooks>
    <hook>
      <hookID>1</hookID>
      <callbackURL><![CDATA[http://postcatcher.in/catchers/abcdefghijk]]></callbackURL>
      <meetingID><![CDATA[my-meeting</meetingID]]>> <!-- a hook created for this meeting only -->
      <permanentHook>false</permanentHook>
      <rawData>false</rawData>
    </hook>
    <hook>
      <hookID>2</hookID>
      <callbackURL><![CDATA[http://postcatcher.in/catchers/1234567890]]></callbackURL>
      <!-- no meetingID means this is a global hook -->
      <permanentHook>false</permanentHook>
      <rawData>false</rawData>
    </hook>
  </hooks>
</response>

پاسخ زمانی که هیچ هوکی ثبت نشده است :

<response>
  <returncode>SUCCESS</returncode>
  <hooks></hooks>
</response>

قالب برگشت به تماس

همه هوک های ثبت شده از طریق HTTP POST با تمام اطلاعات مربوط به رویداد در بدنه این درخواست فراخوانی می شوند. درخواست با Content-typeتنظیم هدر HTTP ارسال می شود application/x-www-form-urlencodedو محتوای موجود در بدنه فرمت زیر را دارد (وقتی getRaw=false):

event={"data":{"type":"event","attributes":{},"event":{"ts":0}}}
timestamp=1415900488797

این ویژگی timestampزمانی است که این تماس برگشتی برقرار شد. اگر برنامه web hooks سعی کند یک تماس برقرار کند و شکست بخورد، چندین بار دوباره تلاش می‌کند و همیشه از همان timestamp استفاده می‌کند. timestamp برای رویدادهای مختلف هرگز یکسان نخواهد بود و ارزش همیشه افزایش می یابد.

ویژگی eventیک نسخه رشته ای از تمام داده های رویداد است (همانطور که از redis دریافت می شود اگر getRaw=true، پردازش می شود اگر getRaw=false). داده ها برای انواع مختلف رویدادها متفاوت است، برای اطلاعات بیشتر اسناد را بررسی کنید.

این نمونه ای از داده های ارسال شده برای یک رویداد از بین رفته جلسه است که getRaw=false است:

event={"data":{"type":"event","id":"meeting-ended","attributes":{"meeting":{"internal-meeting-id":"44ea85d9684005d3b0af3c49e8a271a683cedb79-1532718208098","external-meeting-id":"random-3800337"}},"event":{"ts":1532718316938}}}
timestamp=1532718316953

این همان رویداد برای یک هوک دیگر با getRaw=true است:

event={"envelope":{"name":"MeetingDestroyedEvtMsg","routing":{"sender":"bbb-apps-akka"}},"core":{"header":{"name":"MeetingDestroyedEvtMsg"},"body":{"meetingId":"44ea85d9684005d3b0af3c49e8a271a683cedb79-1532718208098"}}}
timestamp=1532718316953

علاوه بر این، تماس برگشتی با یک چک‌سام امضا می‌شود که در 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.

بنابراین، پس از دریافت تماس برگشتی، یک برنامه کاربردی می‌تواند چک‌سام را به صورت زیر تأیید کند:

• متن درخواست را مانند مثال زیر دریافت میکنید:

event={"data":{"type":"event","attributes":{},"event":{"ts":0}}}
timestamp=1234567890

And convert it to a string like in the example below:

event={"data":{"type":"event","attributes":{},"event":{"ts":0}}}
timestamp=1234567890

جزئیات بیشتر

• پاسخ به تماس همیشه برای یک رویداد در یک زمان و به ترتیب فعال می شود. آنها به همین ترتیب سفارش می شوند

  آنها در 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

نصب و راه اندازی سرویس BigBlueButton