آموزش نصب و راه اندازی وب هوک (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 فقط رویدادهای این جلسه را دریافت می کند. در غیر این صورت هوک جهانی خواهد بود و رویدادها را برای تمام جلسات در سرور دریافت می کند.

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

هوک ها به طور دائم در 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

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

وبلاگ

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

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

Hooks / ایجاد

Hooks/Destroy

Hooks/List

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

جزئیات بیشتر

امتحانش کن

دیدگاهتان را بنویسید لغو پاسخ

آخرین اطلاعیه ها

وبلاگ

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

Hooks / ایجاد

Hooks/Destroy

Hooks/List

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

جزئیات بیشتر

امتحانش کن

دیدگاهتان را بنویسید لغو پاسخ