با توجّه به فراهم شدن امکان ایجاد بازو (ربات) در پیام رسان قدرتمند سروش، در این صفحه قصد داریم کانال هایی که در سروش به آموزش ساخت بازو می پردازند را معرّفی کنیم. یکی از اوّلین کانال ها در این زمینه، کانال baazoo می باشد: https://splus.ir/baazoo
کانال بازو (baazoo) در پیام رسان سروش، اقدام به انتشار کتاب آموزش ساخت ربات (بازو) برای سروش نموده که در فصل های جداگانه، به صورت ساده و کاربردی و از سطح کاملاً مبتدی، روش های طراحی و ایجاد بات های کاربردی سروش را به کاربران مبتدی آموزش می دهد. اگر قصد دارید یک بازوساز سروش شوید، مطالعه ی کتاب منتشر شده در این کانال را به شما پیشنهاد می کنیم: https://splus.ir/baazoo
کلمـات کـلیدی:
آموزش روش ساخت ربات برای پیام رسان سروش,شیوه ی ایجاد بات سروش پی اچ پی,دانلود ربات های کاربردی پیام رسان سروش,چگونه برای سروش ربات (بازو) بسازیم؟,آموزش مبتدی ساخت ربات سروش,کتاب ساخت آسان ربات برای پیام رسان سروش ایرانی,سریع ترین روش ایجاد ربات در سروش,ربات بات بازو پیام رسان ایرانی سروش مرج دانلود بهترین آموزش,دریافت جزوه آموزشی کار با ربات در سروش,چطور براس سروش ربات بنویسیم؟,ربات نویسی سروش,تدریس آموزش ساختن ربات برای سروش,سورس کد ربات های سروش دانلود دریافت,آموزش بازو سازی پیام رسان های داخلی سروش,ارسال متن در ربات سروش دریافت فایل عکس متن سروش ربات بازو
* * * * * * * * * * * * * * * * * * * * * * * * *
خلاصهی مطالب کتاب
' '''.''' 'نوع این پیام: ' '''.''' $data['''''''type''''''']; '''.''' '
';
' '''.''' 'نوع این پیام: ' '''.''' $data['''''''type'''''''] '''.''' '
'; }= {{anchor|RefHeadingToc2245855047956}} انواع پیامهای دریافتی از کاربران =
' . 'شناسهی کاربر موردنظر: ' . $data['from'] . '
' . 'نوع این پیام: ' . $data['type'] . '
'; if($data['type'] == 'START'){ echo 'کاربر وارد شد'; }elseif($data['type'] == 'STOP'){ echo 'کاربر خارج شد'; }elseif($data['type'] == 'TEXT'){ echo 'کاربر متن فرستاد'; }elseif($data['type'] == 'FILE'){ echo 'کاربر فایل فرستاد'; }elseif($data['type'] == 'LOCATION'){ echo 'کاربر موقعیت جغرافیایی فرستاد'; } echo '
ساختار پیام:
'; ob_flush();// چاپ آنی نتیجه flush();// چاپ آنی نتیجه }
* * * * * * * * * * * * * * * * * * * * * * * * *
خلاصهی مطالب کتاب
'''بسم الله الرّحمن الرّحیم'''
{{clear}}
[[Image:Image1.png|center]]فصل 1
'''(ویرایش آبان 1397)'''
'''توجّه: فایلهای مربوط به هر فصل، در کانال سروش baazoo موجود است: [http://splus.ir/baazoo http://splus.ir/baazoo] '''[[Image:Image14.png]]
: {{anchor|RefHeadingToc9432739651354}}
__NOTOC__
== '''فهرست مطالب''' ==
[[#RefHeadingToc24231831846541|پیشنیاز دوره]]
[[#RefHeadingToc24251831846541|]]
[[#RefHeadingToc24271831846541|نصب نرمافزار XAMPP در سیستم شخصی]]
[[#RefHeadingToc24291831846541|اجرا و پیکربندی XAMPP]]
[[#RefHeadingToc24311831846541|پیکربندی فایل php.ini برای اجرای بازوها]]
[[#RefHeadingToc25691831846541|اجرا و آزمایش Apache]]
[[#RefHeadingToc24351831846541|آزمایش اوّلین بازو (ربات)]]= {{anchor|RefHeadingToc24231831846541}} پیشنیاز دوره =
برای ایجاد یک بازو (ربات) در پیامرسان سروش، باید تا حدودی با برنامهنویسی آشنا باشید. در این دوره قصد داریم از زبان php استفاده کنیم. توصیه میشود قبل از شروع، حتماً اصول اوّلیهی کار با زبان php را بیاموزید.
'''توجّه: در این دوره از واژهی فارسی « بازو » بهجای ربات استفاده میگردد. بازو = ربات'''= {{anchor|RefHeadingToc24251831846541}} اجرای بازوها (رباتها) در مکانهای مختلف =
# اجرا روی سیستم شخصی در زمان ایجاد، آزمایش و توسعهی بازو (ربات)
# اجرا روی هاست یا سرور وبـسایت در مراحل نهایی جهت استفادهی رسمی و عمومی
در مراحل اوّلیه، بازوها را در سیستم شخصی خودمان اجرا و آزمایش خواهیم کرد و پس از تکمیل فرایند ساخت، به فضای اجارهای (هاست) یا سرور منتقل و در آنجا اجرا مینماییم. برای اجرای بازوهای ایجادشده به زبان php در سیستم شخصی، اگرچه نرمافزارهای مختلفی ازجمله: EasyPHP, Wamp, Xampp و… وجود دارند، اما شدیداً توصیه میکنیم از نرمافزارXAMPP استفاده شود تا با خطاهای حین کار مواجه نشوید.
= {{anchor|RefHeadingToc24271831846541}} نصب نرمافزار XAMPP در سیستم شخصی =
نرمافزار XAMPP بهراحتی، تمامی بستههای Apache + MariaDB + PHP + Perl را در سیستم شما نصب خواهد نمود. ابتدا XAMPP را از نشانی [https://www.apachefriends.org/ https://www.apachefriends.org] دریافت (Download) نمایید:
توجّه: اگر از قبل، بستههای Apache, MariaDB, PHP, Perl یا EasyPHP, Wamp یا IIS و هرگونه نرمافزار مشابه را در سیستم خود نصب کردهاید، آن را حذف یا غیرفعّال نمایید. (یا تغییر پورت و...)
سپس XAMPP را نصب میکنیم:
درصورتیکه با تصویر بالا سمت چپ مواجه شدید، فقط کافیست آنتیویروس خود را موقتاً غیر فعّال نمایید تا XAMPP با سرعت بالاتری نصب گردد. البته این کار اجباری نیست.
'''مهم:''' درصورتیکه با تصویر بالا سمت راست مواجه شدید، حتماً باید سطح UAC ویندوزتان را موقتاً کاهش دهید و پس از نصب XAMPP، به حالت اوّلیه بازگردانید. برای این کار، ابتدا منوی استارت ویندوز را گشوده و در بخش جستجوی آن، عبارت uac را تایپ نمایید. گزینهی Change User Account Control Settings یافته میشود. آن را باز نموده و طبق تصویر بعد، سطح آن را به پایینترین حد، کاهش داده، Ok و Yes را بفشارید:
سپس دوباره مراحل نصب را از ابتدا شروع میکنیم. فقط کافیست در تمامی مراحل نصب، کلیدهای Ok,Yes, Next و Finish را بفشارید. پس از پایان نصب، حتماً uac را به حالت قبل برگردانید.
نشانی پوشهی نصب XAMPP را به خاطر داشته باشید. بعداً با محتویات این پوشه سروکار داریم.
مهم:''' درصورتیکه ابتدای نصب، سطح UAC ویندوز را کاهش داده بودید، پس از اتمام مراحل نصب، مجدداً سطح UAC را به حالت اوّل بازگردانید. این کار برای حفظ امنیت سیستمعامل شما ضروری است:
= {{anchor|RefHeadingToc24291831846541}} اجرا و پیکربندی XAMPP =
از حالا به بعد، تنظیمات دلخواه را بهوسیلهی XAMPP Control Panel انجام خواهیم داد.
برای اجرای آن در ویندوز، فقط کافیست منوی استارت را گشوده و در بخش جستجو، چند حرف از عبارت xampp را تایپ نموده، سپس روی XAMPP Control Panel کلیک نمایید. البته میتوانید این برنامه را به هر روش دلخواه دیگر نیز اجرا نمایید.
بهتر است برای راحتتر شدن دسترسی به XAMPP Control Panel، یک میانبر از آن را روی صفحهی دسکتاپ قرار دهید و یا با کلیکراست روی آن، در مکان دلخواه سنجاق (Pin) کنید.
سپس آن را اجرا نمایید.
طبق تصویر قبل، از روبروی عبارت Apache، دکمهی Config را باز نموده و با کلیک بر روی هریک از گزینههای Apache (httpd.conf) و PHP (php.ini)، فایلهای مربوط به تنظیمات آپاچی و پیاچپی را جداگانه باز کنید.
ابتدا باید مکان پوشهی public_html یا همان www که صفحهی نخست وبـسایت در آن قرار میگیرد را بهدلخواه، تنظیم نماییم. برای انجام این کار، در فایل httpd.conf، عبارت DocumentRoot را جستجو نمایید تا به بخشی از فایل برسید که در تصویر نشان داده شده:
اکنون آدرسهای
"/xampp/htdocs"
که دو بار تکرار شدهاند را با نشانی پوشهی موردنظر خودتان در سیستم، جایگزین نمایید. بهعنوانمثال:
"D:\website\www\"
دقّت داشته باشید که در نام و آدرس پوشه، حروف بزرگ و کوچک باهم تفاوت دارند.
سپس فایل httpd.conf را ذخیره (Save) نمایید.
در طول این دوره، قرار است فایلهای موردنیازمان را در پوشههای website و www قرار دهیم. شما نیز سعی کنید یک ساختار مشابه ایجاد نمایید تا بتوانید بهراحتی مثالها را اجرا کنید. پس اکنون مثلاً در درایو D، یک پوشه به نام website ایجاد نمودهایم که در آینده با آن کار خواهیم داشت و در آن یک پوشه به نام www نیز ایجاد و نشانی آن را در فایل httpd.conf ثبت نمودیم تا صفحهی اوّل وبسایتمان در www قرار گیرد. توجّه داشته باشید که در آینده، جهت امنیت وبسایت، فایلهایی را که بخواهیم از دسترس مستقیم دیگران خارج کنیم، در www قرار نمیدهیم؛ بلکه در پوشهی website قرار خواهیم داد.
= {{anchor|RefHeadingToc24311831846541}} پیکربندی فایل php.ini برای اجرای بازوها =
اکنون نوبت به تغییر در فایل php.ini میرسد. ابتدا تعدادی از افزونههای موردنیاز برای اجرای بازوها (رباتها) را بررسی میکنیم که در صورت غیرفعّال بودن، آنها را فعّال نماییم. در فایل php.ini تکتک به دنبال افزونههای زیر میگردیم و اگر ابتدای نام آنها علامت ''';''' (نقطهویرگول) وجود داشت، آن را برمیداریم تا فعّال گردد:
extension=openssl
extension=php_openssl.dll
extension=curl
همچنین امکان fopen را بررسی میکنیم تا مطمئن شویم فعّال (On) باشد:
allow_url_fopen='''On'''
و مقادیر تنظیمشده برای حدّاکثر زمانهای زیر را با افزودن علامت ''';''' در ابتدایشان، غیرفعّال مینماییم تا بازوها هیچگاه متوقّف نشوند (وگرنه بعداًً با خطای ...'''Fatal error''': Maximum execution time of مواجه خواهید شد):
''';'''max_execution_time=30
''';'''max_input_time=60
سپس فایل php.ini را ذخیره (Save) میکنیم.
توجّه داشته باشید که تغییر تنظیمات فوق، برای اجرای بازوهای سروش، ضروری میباشد.
= {{anchor|RefHeadingToc25691831846541}} اجرا و آزمایش Apache =
اکنون در پنجرهی XAMPP Control Panel، روبروی Apache، کلید Start را میفشاریم تا به وضعیت سبزرنگ درآید. میتوانید سایر گزینهها از قبیل MySQL و… را نیز اگر لازم داشتید، Start کنید.
اگر مشکلی وجود نداشته باشد، زمینهی عبارت Apache مثل تصویر بعد، به رنگ سبز درخواهد آمد و کلید Start به Stop تبدیل میگردد. امّا درصورت بروز مشکل در اجرای آپاچی، در بخش پایینی پنجره، گزارش مربوط به مشکل را بررسی و برای یافتن روش حل آن در اینترنت جستجو نمایید.
برای آزمایش آپاچی، فایل index.php را در پوشهی www ایجاد و کد زیر را درون فایل ذخیره میکنیم:
<?php
echo "Ok 123";
سپس مرورگر اینترنتی خود را گشوده و نشانی [http://127.0.0.1/ http://127.0.0.1] یا [http://localhost/ http://localhost] را در نوار آدرس مرورگر، وارد مینماییم. طبق تصویر بعد، فایل index.php در پوشهی www، اجرا شده و خروجی را در مرورگر میبینیم:
= {{anchor|RefHeadingToc24351831846541}} آزمایش اوّلین بازو (ربات) =
خب الآن میتوانیم بازوها را روی سیستم شخصی خود، اجرا و آزمایش کنیم. ابتدا طبق راهنمای سروش که در نشانی [https://soroush-app.ir/developer.html https://soroush-app.ir/developer.html] موجود است، کتابخانهی آماده برای زبان php را از نشانی [https://github.com/soroush-app/bot-php-sdk/archive/master.zip https://github.com/soroush-app/bot-php-sdk/archive/master.zip] دریافت میکنیم. '''جهت جلوگیری از بروز برخی مشکلات، نام پوشهی examples را به examples2 تغییر دهید.''' البتّه سعی خواهد شد تا تمامی فایلهای موردنیاز این دوره به همراه مثالها در کانال سروش ما [https://splus.ir/baazoo https://splus.ir/baazoo] قرار گیرد.
اکنون پوشههای src و examples2 را درون پوشهی www قرار میدهیم و البتّه الآن باید از composer استفاده کنیم؛ امّا نگران نباشید: برای آسانتر شدن کار شما، پوشهی مربوطه (vendor) را نیز در کانال سروش [https://splus.ir/baazoo https://splus.ir/baazoo] قرار خواهیم داد. کافیست با مراجعه به کانال baazoo در سروش، فایلهای مربوط به هر فصل از کتاب را دریافت نمایید. پوشهی vendor را نیز درون پوشهی www قرار میدهیم.
خب حالا آپاچی فعّال است و فایلها و پوشهها نیز در جای خود قرارگرفتهاند. اکنون اوّلین مرحله از ایجاد یک بازو (ربات) در سروش را طی خواهیم کرد. در نرمافزار سروش به نشانی MrBot یا [https://splus.ir/mrbot https://splus.ir/mrbot] میرویم. دکمهی «شروع» را میزنیم. سپس «ایجاد بات» و یک شناسهی (ID) دلخواه را وارد میکنیم که قرار است نشانی ربات ما باشد. اگر شناسهی موردنظرمان پذیرفته شد، آدرس و توکن به ما اعلام میشود. همین الآن توکن را در جایی ذخیره کنید؛ چون بعداً با آن کار داریم. توکن! Token ، به خاطر سپردید؟ همان عبارت طولانی.
دکمههای دیگری نیز در صفحهی MrBot سروش ظاهر شده که نام و عکس و پروفایل و پیام آغازین بازو را میتوانید بهدلخواه، وارد کنید. فعلاً برای ما مهم نیست؛ فقط آدرس و توکن را لازم داشتیم که گرفتیم.
اکنون به پوشهی www خودمان بازمیگردیم و با استفاده از یک نرمافزار ویرایشگر دلخواه، فایل echo_bot.php را از داخل پوشهی examples2 باز میکنیم. (قبلاً هم گفتیم که نام پوشهی examples را به examples'''2''' تغییر دهید). در ابتدای فایل echo_bot.php (شاید سطر 5)، متغیّر توکن را میبینیم:
$bot_token '''=''' '''''''your bot token'''';'''
مقدار آن را با توکن خودمان جایگزین میکنیم. همان توکنی که از MrBot گرفته بودیم. دقّت کنید تا کامل و بدون تغییر، در یک سطر، بین دو علامت ' ' جایگزین شود. مثال:
$bot_token '''=''' '''''''a0iZ2QD8i9RFpoQkLuFe4vgDLg5QaNa88PCT6eMy580q ''...ادامه دارد... '''''';'''
فایل echo_bot.php را ذخیره (Save) نموده و در مرورگر وب با نشانی زیر، اجرا میکنیم:
[http://127.0.0.1/examples2/echo_bot.php http://127.0.0.1/examples][http://127.0.0.1/examples2/echo_bot.php 2][http://127.0.0.1/examples2/echo_bot.php /echo_bot.php]
توجّه: باید به اینترنت متّصل باشید. همینطور که مرورگر در حال اجراست، در پیامرسان سروش به آدرس بازو (ربات) خودمان وارد میشویم. همان آدرس یا شناسهای که در MrBot انتخاب کرده بودیم. فقط کافیست در فضای شخصی خود، علامت@ به همراه همان شناسه را در یک پیام بنویسید و سپس روی آن کلیک کنید.
پس از ورود به آدرس بازوی ایجادشده توسّط خودتان در سروش، دکمهی شروع را بزنید و با ارسال چند پیام، بازو را امتحان کنید. خواهید دید که این ربات (بازو) وظیفه دارد تا پیام خودتان را برایتان تکرار کند. این وظیفه را در همان فایل echo_bot.php به او دادهایم. توجّه: همچنان باید به اینترنت متّصل باشید و مرورگر وب با نشانی
[http://127.0.0.1/examples2/echo_bot.php http://127.0.0.1/examples][http://127.0.0.1/examples2/echo_bot.php 2][http://127.0.0.1/examples2/echo_bot.php /echo_bot.php] در حال اجرا باشد، تا ربات شما کار کند. در همین وضعیت، حتّی میتوانید نشانی بازوی خود (...@) را به دوستانتان نیز بدهید تا امتحان کنند.
تبریک میگوییم. شما اوّلین بازو (ربات) خود را راهاندازی نمودهاید. امّا این بازوها تا زمانی پاسخ میدهند که سیستم شما به اینترنت متّصل و فایل این بات ( echo_bot.php ) نیز درون مرورگرتان در حال اجرا باشد. فعلاً به این روش، بازوهایمان را اجرا و آزمایش خواهیم نمود؛ ولی درنهایت، بازوها را به یک فضای اجارهای (هاست) یا سرور، منتقل خواهیم کرد تا بهصورت دائم در دسترس عموم کاربران سروش باشد.
البته فعلاً برای آزمایش، بازوها را با آپاچی اجرا میکنیم، امّا در آینده میتوانید از روشهای دیگر استفاده نمایید.
'''نکاتی که باید با دقّت بخوانید و به خاطر داشته باشید'''
# عملیات ثبت و تغییر بازوها را در MrBot : مستربات [https://splus.ir/mrbot https://splus.ir/mrbot] انجام میدادیم.
# برای هر بازو که میخواهیم راهاندازی کنیم، یک شناسه در MrBot ثبت میکنیم و یک توکن مخصوص به همان بازو را گرفته و در فایل php آن قرار میدهیم.
# توکنها محرمانه هستند و نباید آن را به دیگران بدهیم. در صورت لو رفتن توکن یک بازو، سریعاً به MrBot رفته و از مسیر «صفحه اصلی» ، «بروزرسانی بات» ، انتخاب بات موردنظر ، «بروزرسانی توکن» ، توکن بازوی موردنظرمان تغییر خواهد یافت.
# در صورت تغییر دادن توکن بازو در MrBot ، باید توکن درجشده در فایل php همان بازو را نیز جدید نماییم؛ وگرنه هرگز کار نخواهد کرد.
# افرادی که آشنایی کامل دارند، میتوانند بهجای استفاده از WAMPP، از هر نرمافزار مشابه دیگر استفاده کنند و یا بازوها را در هاست یا سرور خود نیز اجرا نمایند. امّا به تنظیمات php.ini توجّه گردد.
# در فصلهای بعدی، فقط از واژهی «بازو» استفاده خواهیم کرد. پس: '''بازو''' = ربات = بات = Robot = bot
# درون کانال ما در سروش به نشانی '''baazoo''' ( [https://splus.ir/baazoo https://splus.ir/baazoo] ) میتوانید فایلهای مورداستفاده در هر فصل این کتاب را دریافت نمایید.
با توجّه به تقبّل هزینههای تولید این کتاب جهت کمک به پیشرفت پیامرسانهای داخلی از سوی مرکز jdf.scr.ir ، خواهشمندیم شما نیز در صورت تمایل، از آن مرکز '''حمایت''' فرمایید:
[[Image:Image17.png]][http://scr.ir/pardakht/?hemayat=sbot http://scr.ir/pardakht/?hemayat=sbot]
'''صلوات'''
* * * * * * * * * * * * * * * * * * * * * * * * *
'''بسم الله الرّحمن الرّحیم'''
{{clear}}
[[Image:Image1.png|center]]فصل 2
'''(ویرایش آبان 1397)'''
'''توجّه: فایلهای مربوط به هر فصل، در کانال سروش baazoo موجود است: [http://splus.ir/baazoo http://splus.ir/baazoo][[Image:Image14.png]] '''
: {{anchor|RefHeadingToc9432739651354}}
'''فهرست مطالب'''[[#RefHeadingToc24231831846541|ساختار چینش فایلها و پوشهها]]
[[#RefHeadingToc2237855047956|طریقهی کارکرد بازوها]]
[[#RefHeadingToc2239855047956|پیامهای بازو (بات) و کاربر]]
[[#RefHeadingToc2241855047956|ایجاد شیء و شروع کار (کلاس Client)]]
[[#RefHeadingToc2243855047956|دریافت پیامهای کاربران (متدهای getMessages و getData)]]
[[#RefHeadingToc2245855047956|انواع پیامهای دریافتی از کاربران]]= {{anchor|RefHeadingToc24231831846541}} ساختار چینش فایلها و پوشهها =
در فصل 1 توانستیم بازوی (ربات) آزمایشی echo_bot.php را راهاندازی نماییم. در این فصل قصد داریم خودمان بازو بسازیم. امّا ابتدا باید یاد بگیریم که بازوها چگونه کار میکنند. بازوهای php سروش از کتابخانههای آمادهای بهره میگیرند که توسّط تیم سروش و دیگران، ایجاد گردیده و کار را برای ما بسیار آسان خواهند کرد. در ابتدای این فصل، میآموزیم که چگونه آن کتابخانهها را به درون فایل بازوی خودمان اضافه کنیم.
کتابخانههای موردنیاز ما درون دو پوشهی src و vendor قرار دارند. نکتهی اوّل: همیشه پوشههای src و vendor در کنار یکدیگر باشند و نام آنها را نیز تغییر ندهید. برای استفاده از کتابخانهها، فقط کافیست فایل autoload.php از درون پوشهی vendor را از طریق include یا require به ابتدای فایل بازوی خودمان اضافه کنیم. به فصل قبل برمیگردیم. ابتدای فایل echo_bot.php (شاید سطر 3) را ببینید:
require dirname(__FILE__) '''.''' ''''/../'''vendor'''/'''autoload.php'''';'''
کد بالا، عمل افزودن کتابخانهها به ربات (بازو) را انجام میدهد. به نحوهی آدرسدهی دقّت کنید. بخش dirname(__FILE__) بیانگر پوشهای است که فایل بازوی ما (echo_bot.php) در آن قرار دارد. بعد از آن، علامت '''../''' را میبینید که به معنی رفتن به یک پوشه بالاتر (www) است. سپس آدرس به سمت پوشهی vendor و فایل autoload.php رفته است. به تصویر بعد دقّت کنید:
[[Image:Image3.png]][[Image:.png|thumb|
'''تصویر ۱. نحوهی آدرسدهی'''
]]در تصاویر قبل، ساختار قرارگیری فایلها و پوشهها، طبق آزمایش فصل 1 را مشاهده مینمایید. امّا هر چیزی که درون پوشهی www قرار گرفته باشد، میتواند توسّط کاربران وبسایت شما، مشاهده و یا اجرا شود. پس برای افزایش سطح امنیت بازو، بهتر است فایلها و پوشههایی که وجود آنها در www الزامی نیست را در خارج از آن، یعنی در پوشهی website قرار دهیم. سپس بهوسیلهی include یا require از آنها استفاده کنیم.
[[Image:.png|thumb|
'''تصویر ۲. ساختار پوشهها و روش صحیح آدرسدهی'''
]]اکنون طبق مطالبی که آموختیم، پوشههای src و vendor را به خارج از www منتقل خواهیم کرد و ابتدای فایلهای درون پوشهی examples2 را نیز باید تغییر دهیم تا بتوانند فایل autoload.php از مکان جدیدش پیدا کنند.توجّه: همیشه دو پوشهی src و vendor را در کنار یکدیگر قرار دهید. سپس از فایل autoload.php بهره بگیرید. پس در آینده، اوّلین کاری که برای ساخت هر بازو انجام میدهید، افزودن فایل autoload.php از طریق include یا require خواهد بود.
ممکن است در فصلهای بعدی کتاب، چینش پوشهها در سیستم من و سیستم شما، متفاوت باشد. پس باید خودتان ابتدای فایل بازوها را بررسی و درصورتیکه لازم بود، نشانی autoload.php را طبق ساختار پوشههای خودتان، اصلاح کنید.
require dirname(__FILE__) '''.''' ''''/../../'''vendor'''/'''autoload.php'''';'''
هرزمان با پیغام خطا یا هشدار require مواجه شدید، بدانید که مشکل از آدرسدهی اشتباه است و طبق آموزشهایی که گفته شد، مسیر را اصلاح نمایید.
خب یک مثال دیگر بزنیم: اگر ساختار پوشهها دقیقاً شبیه به تصویر قبلی بوده و فقط فایل بازو را در خود پوشهی www قرار دهیم، چگونه آدرسدهی کنیم؟ پاسخ: ازآنجاکه مکان www ، یک سطح از examples2 بالاتر است، پس یکی از علامتهای ../ را در مثال قبل، برمیداریم.
پس تا اینجای فصل آموختیم که:
# بهتر است فقط فایلهایی که باید در مرورگر اجرا شوند را درون www قرار دهیم و سایر فایلها را خارج از آن بگذاریم تا امنیت بازو و وبسایت ما حفظ گردد.
# در بازوهایمان از کتابخانههایی استفاده میکنیم که در دو پوشهی src و vendor قرار دارند و از طریق include یا require کردن فایل vendor'''/'''autoload.php از آن کتابخانهها بهره میگیریم.
# اوّلین کار در ساخت در بازو (ربات)، افزودن همان کتابخانههاست که باید دقّت کنیم تا اگر آدرسدهی اشتباه بود، آن را اصلاح نماییم.
# قبل از مطالعهی بقیهی فصل، موارد قبلی را تمرین کنید.
= [[Image:.png|thumb|تصویر ۳. شیوهی کارکرد بازوها
]]{{anchor|RefHeadingToc2237855047956}} طریقهی کارکرد بازوها =
حالا میدانیم همهی کارهایی که یک ربات (بازو) انجام میدهد، در مکان دیگری جدا از سرور پیامرسان سروش انجام میشود. سرور اصلی سروش، فقط بین بازوی ساختهشده توسّط شما و کاربران عادی سروش، ارتباط برقرار میکند.
همانطوری که در تصویر میبینید، سیستم سمت راست، همان سیستم شماست که اکنون بازوها را روی آن اجرا میکنید و در آینده نیز، سرور یا فضای وبسایت شما خواهد بود. در سمت چپ، یکی از کاربران عادّی سروش است.= {{anchor|RefHeadingToc2239855047956}} پیامهای بازو (بات) و کاربر =
پیامها ممکن است از طرف یک کاربر بهسوی بازوی ما و یا از طرف بازوی ما بهسوی یک کاربر خاص ارسال شوند. حالا این سؤال پیش میآید که وقتی چندین کاربر در حال استفاده از بازو هستند، بازو چگونه پیامهای هرکدام از کاربران از یکدیگر تشخیص میدهد و پاسخها را اشتباهی به کاربر دیگری نمیفرستد؟
پاسخ بسیار ساده است. هر کاربر، یک شناسهی مخصوص دارد که همیشه همراه با پیامهای او، شناسهاش نیز ارسال میگردد. بازو نیز باید به همراه هر پیامی که میفرستد، شناسهی کاربر موردنظر را نیز ارسال کند تا آن پیام به دست همان کاربر برسد. (شناسهی هر کاربر در رباتهای مختلف، متفاوت است.)
پس متوجّه شدیم که شناسه، یک بخش جدانشدنی از همهی پیامهاست؛ که در پیامهای کاربر، بهنوعی نشانی فرستنده و در پیامهای بازو، نشانی گیرنده را مشخّص کرده است. (این شناسه، id انتخابی درون سروش نیست!)
حالا میدانیم که پیامها علاوه بر اینکه انواع مختلف دارند (مثل: متن، عکس، فایل و...)، از چندین بخش تشکیل میشوند که یک بخش آن، شناسهی کاربر موردنظر است. گیج شدید؟ نگران نباشید. این مبحث را هنوز شروع نکردهایم؛ به همین خاطر کمی گیجکننده است.
= {{anchor|RefHeadingToc2241855047956}} ایجاد شیء و شروع کار (کلاس Client) =
به کمک کتابخانههایی که قبلاً توضیح دادیم و class Client که در اختیار ما قرار دادهاند، هر نوع عملیات دریافت یا ارسال انواع پیام را انجام خواهیم داد. نکته: اگر با روش شیءگرا آشنا نیستید، اصلاً نگران نباشید. در این دوره فرض را بر این گرفتهایم که همه مبتدی هستیم!
در روش شیءگرا، تعدادی از تابعها را درون یک بستهبندی قرار میدهیم و آن بستهبندی را class مینامیم. هروقت آن class را (به شیوهی خاص) در یک متغیّر بریزیم، آن متغیّر را شیء مینامیم و میگوییم یک شیء ایجاد کردیم.
هرکدام از تابعهایی که درون کلاس (class) وجود دارند را مِتُد میگوییم. اکنون برای استفاده از همان تابعها (متدها)، علامت '''<-''' و نام شیء را به قبل از نام متد (تابع) اضافه میکنیم تا بتوانیم از آن متد استفاده نماییم. (و این بود آموزش شیءگرایی در 30 ثانیه!)
مثلاً قبلاً یک تابع به نام ()add داشتهایم که دو عدد را باهم جمع میکرده:
echo add(5,9);
اکنون فرض میکنیم یک کلاس (class) به نام math برای ما ساختهاند که یکی از متدهایش، همان add است:
$test = new math();
echo $test '''->''' add(5,9);
در مثال قبل، test$ همان شیء است که با دستور new از کلاس math ایجاد کردیم. البته ممکن است خود کلاس نیز هنگام ایجاد شدن، پارامتر (آرگومان) بگیرد. یا اینکه مکان کلاس در یک فضای نام دیگر باشد و قبل از آن، با علامت / اضافه شود. امّا مهم نیست. شما فقط یکبار لازم دارید این کار را انجام دهید که همان را نیز میتوانید از کد زیر، حفظ نموده و همیشه در همهی رباتها همین را استفاده نمایید.
ابتدا توکن بازوی خود را که طبق آموزش فصل 1 از مستربات گرفتهایم، در متغیّر bot_token$ ریخته و سپس طبق کد زیر، توکن را بار کلاس Client داده و یک شیء به نام bot$ ایجاد میکنیم:
$bot_token = '''''''a0iZ2QD8i9RFpoQkLuFe4vgDLg5QaNa88PCT6eMy580q ''...ادامه دارد...''' ''';'''
'''$bot''' '''=''' new Soroush\Client($bot_token);
اکنون میتوانیم از متدهای مختلف استفاده کنیم که هرکدام از این متدها، کار مشخّصی را در بازو انجام میدهد. بهعنوانمثال، یک متد برای دریافت پیام کاربران و یکی برای ارسال عکس به کاربران و دیگری برای تغییر دکمههای سفارشی پایین صفحهی بازو و…
= {{anchor|RefHeadingToc2243855047956}} دریافت پیامهای کاربران (متدهای getMessages و getData) =
پیامهایی که کاربران مختلف بهسوی بازو میفرستند، در سرور سروش جمع میشوند و بهمحض برقراری ارتباط بازوی ما با سرور سروش، تکتک برای بازو ارسال میشوند. تا زمانی که بازو در حال اجرا باشد، پیامها را میگیرد و به صورتی شبیه آرایهی چندبُعدی، در اختیار ما قرار میدهد. متد getMessages این کار را برای ما انجام میدهد:
$messages '''=''' '''$bot''' '''->''' '''getMessages()''';
امّا ازآنجاییکه کاربران همیشه در حال استفاده از بازو هستند، پیامهای کاربران تمامی ندارد و همچنان پیامهای جدیدتری به انتهای این آرایه اضافه میگردد. پس راهحل چیست؟ پاسخ: از یک حلقهی foreach استفاده میکنیم تا همواره پیامهای جدیدتر کاربران را خوانده و پاسخ دهیم. این حلقه هیچگاه متوقّف نمیشود، مگر اینکه اجرای فایل php بازو، متوقّف گردد.
'''foreach'''($messages as $message){''' //...'''
هر یک پیام، با متد getData به یک آرایهی انجمنی (هش) تبدیل میشود که شامل عناصر مختلفی است:
$data '''=''' $message '''->''' '''getData'''();
یکی از این عناصر، «نوع پیام» و یکی دیگر، همان «شناسهی کاربر مورد» نظر است که قبلاً به آن اشاره کردیم.
echo 'شناسهی کاربر موردنظر: ' '''.''' $data['''''''from''''''']
'''.''' '' '''.''' 'نوع این پیام: ' '''.''' $data['''''''type''''''']; '''.''' '
';
تا الآن متوجّه شدیم که چگونه باید پیامها را از هم تفکیک و تکتک به هرکدام رسیدگی نماییم. مجموع کدهای قبل بهصورت زیر شد؛ که البته هنوز برای آزمایش آن زود است. کمی دیگر صبر کنید!
$bot_token = '''''''a0iZ2QD8i9RFpoQkLuFe4vgDLg5QaNa88PCT6eMy580q ''...ادامه دارد...''' ''';'''
'''$bot''' '''=''' new Soroush\Client($bot_token);
$messages '''=''' '''$bot''' '''->''' '''getMessages()''';
'''foreach'''($messages as $message){
$data '''=''' $message '''->''' '''getData'''();
echo 'شناسهی کاربر موردنظر: ' '''.''' $data['''''''from'''''''] '''.''' '' '''.''' 'نوع این پیام: ' '''.''' $data['''''''type'''''''] '''.''' '
'; }= {{anchor|RefHeadingToc2245855047956}} انواع پیامهای دریافتی از کاربران =
در مرحلهی قبل، توانستیم نوع پیام را پیدا کنیم که در data['type']$ بود. در سروش فقط 5 نوع پیام میتواند از سوی کاربران ارسال شود. پس همیشه مقدار data['type']$ برابر با یکی از این 5 کلمه (رشته) است:
* '''START''': موقع زدن دکمهی «شروع» در صفحهی بات (بازو) توسّط کاربر
* '''STOP''': موقع زدن دکمهی «متوقف کردن بات» در بالای بات (بازو) توسّط کاربر
* '''TEXT''': موقع آمدن یک پیام متنی و مقدار data['body']$ نیز حاوی آن متن است.
* '''FILE''': موقع آمدن یک فایل که مقادیر مخصوص به خود را دارد و مقدار data['body']$ در صورت کپشندار بودن فایل ارسال میشود.
* '''LOCATION''': موقع آمدن موقعیت جغرافیایی
اکنون میتوانیم درون حلقهی foreach ، اجزای هر پیام را بررسی و نسبت به نوع هر پیام، با استفاده از دستورات شرطی (ifelse)، عمل مخصوص به آن نوع پیام را انجام دهیم.
if($data['type'] '''==''' ''''START''''){
echo 'کاربر وارد شد';
}elseif( ''//…''
اکنون با توجّه به چینش جدید پوشهها، یک بازوی جدید در فایل log.php در مکان www میسازیم (utf-8) و کدهای صفحهی بعد را در آن مینویسیم. '''توجّه: '''فایلهای هر فصل در کانال سروش baazoo@ قابل دریافت است.
<?php
require dirname(__FILE__) . '/../vendor/autoload.php';// بررسی گردد
$bot_token = 'your bot token';// توکن بازوی شما
$bot = new Soroush\Client($bot_token);
$messages = $bot -> getMessages();
foreach($messages as $message){
$data = $message -> getData();
echo '' . 'شناسهی کاربر موردنظر: ' . $data['from'] . '
' . 'نوع این پیام: ' . $data['type'] . '
'; if($data['type'] == 'START'){ echo 'کاربر وارد شد'; }elseif($data['type'] == 'STOP'){ echo 'کاربر خارج شد'; }elseif($data['type'] == 'TEXT'){ echo 'کاربر متن فرستاد'; }elseif($data['type'] == 'FILE'){ echo 'کاربر فایل فرستاد'; }elseif($data['type'] == 'LOCATION'){ echo 'کاربر موقعیت جغرافیایی فرستاد'; } echo '
ساختار پیام:
'; print_r($data); echo '
'; ob_flush();// چاپ آنی نتیجه flush();// چاپ آنی نتیجه }
در فایل log.php ، توکن بات (بازوی) خودتان را جایگزین و اجرا نمایید. [http://127.0.0.1/log.php http://127.0.0.1/log.php]
آنگاه در پیامرسان سروش به آدرس بازوی خود وارد شوید و انواع مختلف پیام را به آن بفرستید و در مرورگرتان، نتایج را ببینید و به سایر مقادیر و عناصر آرایه نیز توجّه فرمایید.
'''توجّه: فایلهای مربوط به هر فصل، در کانال سروش baazoo موجود است: [http://splus.ir/baazoo http://splus.ir/baazoo][[Image:Image6.png]] '''
با توجّه به تقبّل هزینههای تولید این کتاب جهت کمک به پیشرفت پیامرسانهای داخلی از سوی مرکز jdf.scr.ir ، خواهشمندیم شما نیز در صورت تمایل، از آن مرکز '''حمایت''' فرمایید:
[http://scr.ir/pardakht/?hemayat=sbot http://scr.ir/pardakht/?hemayat=sbot][[Image:Image17.png]]
'''صلوات'''
* * * * * * * * * * * * * * * * * * * * * * * * *
'''بسم الله الرّحمن الرّحیم'''
{{clear}}
[[Image:Image1.png|center]]فصل 3
'''(ویرایش آبان 1397)'''
'''توجّه: فایلهای مربوط به هر فصل، در کانال سروش baazoo موجود است: [http://splus.ir/baazoo http://splus.ir/baazoo][[Image:Image14.png]] '''
'''فهرست مطالب'''[[#RefHeadingToc29412379132256|شیوهی انتقال پیامهای کاربران به بازو]]
[[#RefHeadingToc29432379132256|اجزای پیامهای کاربران به بازو]]
[[#RefHeadingToc29452379132256|بررسی پیام نوع START از کاربر به بازو]]
[[#RefHeadingToc29552379132256|بررسی پیام نوع STOP از کاربر به بازو]]
[[#RefHeadingToc29652379132256|بررسی پیام نوع TEXT از کاربر به بازو]]
[[#RefHeadingToc29752379132256|بررسی پیام نوع LOCATION از کاربر به بازو]]
[[#RefHeadingToc29892379132256|بررسی پیام نوع FILE از کاربر به بازو]]
[[#RefHeadingToc29912379132256|- دستهبندی فایلهای ارسالی از کاربر به بازو]]= {{anchor|RefHeadingToc29412379132256}} شیوهی انتقال پیامهای کاربران به بازو =
[[Image:.png|thumb|
'''تصویر 1: چرخهی انتقال پیامهای کاربران به بازو و تکتک خواندن و پاسخدادن به هر کاربر'''
]]همانطور که در تصویر مقابل میبینید، کاربران زیادی در حال استفاده از بازوی (بات) شما هستند و انواع مختلف پیام را برای بازو ارسال میکنند.سرور سروش، تمامی پیامها را میگیرد بهنوبت بهسوی بازوی شما میفرستد. اگر بازو در حال اجرا باشد، پیامها را یکییکی میگیرد و پاسخ میدهد. اما اگر مثلاً دیروز ارتباط بازوی شما قطع شده باشد و یا اجرای آن را متوقّف نموده باشید، تمامی پیامها در سرور سروش نگهداری میگردد و بهمحض اینکه ارتباط برقرار شود یا بازو را اجرا کنید، بازو همهی پیامهای روز گذشتهی کاربران را دریافت خواهد نمود.
اگر به صف دقّت کنید، متوجّه خواهید شد که پیامها باید یکییکی، هرکدام در یک چرخش حلقهی foreach بررسی و پاسخ داده شوند. برخی مواقع نیاز داریم کاربر، چندین پیام ارسال کند تا بتوانیم خدمتی به او ارائه کنیم. بهعنوانمثال، بازویی ساختهایم که دو عدد را از کاربر بگیرد و حاصلجمع آن دو عدد را در پاسخ به او اعلام کند. خب کاربر مجبور است دو عدد را در دو پیام جداگانه به بازو بفرستد. امّا اگر در تصویر بالا به صف پیامها دقّت کنید، آنگاه ممکن است بین دو پیام آن کاربر، پیامهای دیگری متعلق به کاربران دیگر نیز قرار گیرد. پس ما باید عدد اوّل را در جایی ذخیره کنیم تا زمانی که عدد دوم از همان کاربر برسد. برای ذخیره میتوانیم از پایگاهداده و یا یک آرایهی چندبُعدی مثل user_data[$user_id][$data_name]$ استفاده کنیم. در فصلهای آینده، در این مورد توضیح خواهیم داد.
= {{anchor|RefHeadingToc29432379132256}} اجزای پیامهای کاربران به بازو =
در فصل قبل، تا حدودی با ساختار پیامهای ارسالی از سوی کاربران به بازو، آشنا شدیم. فهمیدیم که هر یک پیام، شامل اجزای مختلفی میباشد که یکی از آن اجزا، '''''''type''''''' است. مقدار data['''''''type''''''']$ به ما نشان میدهد که کاربر چه نوع پیامی برای بازو (ربات) ارسال نموده است. نوع پیام کاربر به بازو، همیشه یکی از این 5 حالت است:START''' یا '''STOP''' یا '''TEXT''' یا '''FILE''' یا '''LOCATION و هیچگاه خارج از این 5 حالت نخواهد بود.
در مثال پایانی فصل 2 آموختیم که قبل از هرچیز، باید نوع پیام را تشخیص دهیم و برای هر نوع پیام، عملکرد مخصوص به خودش را داشته باشیم. نوع پیام در حلقهی foreach، برابر با مقدار data['''''''type''''''']$ بود:
'''foreach'''($messages as $message){
$data '''=''' $message '''->''' '''getData'''();
if($data['type'] '''==''' ''''START''''){
echo 'کاربر وارد شد';
}elseif($data['type'] == ''''STOP''''){
echo 'کاربر خارج شد';
}elseif($data['type'] == ''''TEXT''''){
echo 'کاربر متن فرستاد';
}elseif($data['type'] == ''''FILE''''){
echo 'کاربر فایل فرستاد';
}elseif($data['type'] == ''''LOCATION''''){
echo 'کاربر موقعیت جغرافیایی فرستاد';
}
}
هر نوع پیام، اجزای مخصوص به خودش را دارد که سایر عناصر آرایهی data$ را تشکیل خواهند داد. اما این اجزا با هم متفاوتاند. مثلاً در نوع TEXT، فقط یک پیام متنی از سوی کاربر فرستاده شده، امّا در نوع FILE، یک فایل ارسال شده که سایر اجزای پیام نیز متفاوت خواهند بود. مثلاً data[''''fileSize'''']$ برابر با اندازهی فایل خواهد بود؛ امّا در پیامهای نوع TEXT، اصلاً چنین جزئی نداشتیم.
پس حالا میدانیم که عناصر آرایهی data$ برای هرکدام از نوعهای START یا STOP یا TEXT یا FILE یا LOCATION، متفاوت خواهد بود. این عناصر را همان اجزای پیام مینامیم. البته اجزایی هم وجود دارند که بین همهی نوعهای پیام، مشترکاند؛ مثل: from که همان شناسهی کاربر فرستنده است، یا time که مُهر زمان ارسال پیام از کاربر به سرور سروش را نشان میدهد و یا type که نوع پیام را مشخص میکند و… که در ادامه معرّفی خواهیم کرد.
اکنون قصد داریم هریک از این 5 حالت START''' یا '''STOP''' یا '''TEXT''' یا '''FILE''' یا '''LOCATION را جداگانه بررسی کنیم. برای درک بهتر اجزای هر نوع پیام، از فایل log2.php که همراه این فصل است، استفاده نمایید.= {{anchor|RefHeadingToc29452379132256}} بررسی پیام نوع START از کاربر به بازو =
زمانیکه یک کاربر سروشی در صفحهی مربوط به ربات (بازوی) شما، دکمهی «شروع» یا همان استارت را بفشارد، نوع پیام یا همان مقدار data['''''''type''''''']$ برابر با '''START '''، برای بازو ارسال میگردد.
هرگاه این نوع پیام را دریافت کردیم، میتوانیم یک پیام خوشآمدگویی یا معرّفی برای کاربر تازهوارد، ارسال کنیم و دکمههای کیبورد سفارشی مخصوص به صفحهی آغازین بازو را برای او به نمایش درآوریم. حتّی اگر نیاز باشد، شناسهی او را در یک پایگاهداده ذخیره کنیم تا بعداً بتوانیم تعداد افراد متصل به بازو (بات) را شمارش نماییم.
ساختار پیام نوع '''START''' و اجزای آن شبیه به مثال زیر است:
Array(
[from] => cUHPDyF7D5vvZ14IOfyF0R_uLvoSLyn44zeMVvtGBfoYS7IRpE-NkyfGLUA
[body] =>
[type] => '''START'''
[time] => 1541185421379
)== {{anchor|RefHeadingToc29472379132256}} عنصر 'type' ==
همیشه (در همهی 5 نوع پیام کاربر) وجود دارد و بیانگر نوع پیام است. مثلاً در اینجا پیام از نوع START است.
== {{anchor|RefHeadingToc29492379132256}} عنصر 'from' ==
عنصر from نیز در همهی 5 نوع پیام کاربر، وجود دارد. مقدار آن برابر با شناسهی کاربر موردنظر است. بعداً برای ارسال پاسخ به کاربر نیز از همین عنصر استفاده خواهیم نمود تا مشخّص کنیم که گیرندهی پیام ما چه کسی است. هر کاربر سروش، شناسهی مخصوص به خود را دارد و البته شناسهی او در هر بازو نیز متفاوت است. یعنی آقای فلان در هنگام استفاده از دو بازوی متفاوت، دو شناسهی متفاوت دارد. پس شناسهی هر کاربر فقط برای همان بازو، معتبر است. توجّه داشته باشید که این شناسهها، با شناسهای که ما در نرمافزار سروش برای خودمان انتخاب کردهایم، هیچ ربطی ندارند. بدین ترتیب، حریم شخصی کاربران، حفظ میگردد و از طریق بازوها در سروش، هویت واقعی هیچکس قابلکشف نخواهد بود.== {{anchor|RefHeadingToc29512379132256}} عنصر 'time' ==
عنصر time نیز در همهی 5 نوع پیام کاربر، وجود دارد. مقدار آن برابر با مُهر زمان رسیدن پیام به سرور سروش است. پس ممکن است اگر دیروز بازوی ما قطع بوده باشد و امروز وصل گردد، پیامهای دیروز کاربران که در سرور سروش نگهداری شده را امروز دریافت کند و عنصر time آن پیامها، زمان دیروز را نشان خواهد داد. برای تبدیل این عدد به تاریخ و ساعت، میتوانید آن را در پارامتر (آرگومان) دوم تابع ()date قرار دهید. البته برای گرفتن تاریخ هجریشمسی، باید از تابع ()jdate و کتابخانهی jdf.php در [http://jdf.scr.ir/ http://jdf.scr.ir] استفاده نمایید.
== {{anchor|RefHeadingToc29532379132256}} عنصر 'body' ==
در پیامهای از نوع START، مقدار عنصر body خالی است و هیچ کاربرد خاصی ندارد.
= {{anchor|RefHeadingToc29552379132256}} بررسی پیام نوع STOP از کاربر به بازو =
زمانیکه یک کاربر سروشی درون ربات (بازوی) شما، روی نوار بالایی کلیک نموده و دکمهی «متوقّف کردن بات» را بفشارد، نوع پیام یا همان مقدار data['''''''type''''''']$ برابر با '''STOP '''، برای بازو ارسال میگردد.
اکثر اجزای آن تقریباً شبیه به پیام START است. هرگاه نوع پیام STOP را دریافت کردیم، میتوانیم هر نوع متغیر یا داده در پایگاهداده یا عنصری در آرایه که برای آن کاربر ایجاد کرده بودیم را حذف نماییم تا منابع سیستم، بیهوده اِشغال نشود. اگر کاربری STOP کرده باشد، هیچ پیامی از بازو دریافت نخواهد کرد. پس بیهوده برای او پاسخ نفرستید. ساختار پیام نوع '''STOP''' و اجزای آن شبیه به مثال زیر است:
Array(
[from] => cUHPDyF7D5vvZ14IOfyF0R_uLvoSLyn44zeMVvtGBfoYS7IRpE-NkyfGLUA
[body] =>
[type] => '''STOP'''
[time] => 1541185485226
)== {{anchor|RefHeadingToc29572379132256}} عنصر 'type' ==
همیشه (در همهی 5 نوع پیام کاربر) وجود دارد و بیانگر نوع پیام است. مثلاً در اینجا پیام از نوع STOP است.
== {{anchor|RefHeadingToc29592379132256}} عنصر 'from' ==
عنصر from نیز در همهی 5 نوع پیام کاربر، وجود دارد. مقدار آن برابر با شناسهی کاربر موردنظر است. دربارهی 'from'، در بخش مربوط به نوع پیام START بهطور مفصّل، توضیح دادهشد. میتوانید از آنجا مطالعه نمایید.
== {{anchor|RefHeadingToc29612379132256}} عنصر 'time' ==
عنصر time نیز در همهی 5 نوع پیام کاربر، وجود دارد. مقدار آن برابر با مُهر زمان رسیدن پیام به سرور سروش است. درمورد 'time'، در بخش مربوط به نوع پیام START، کاملاً توضیح داده شد. میتوانید از آنجا مطالعه نمایید.
== {{anchor|RefHeadingToc29632379132256}} عنصر 'body' ==
در پیامهای از نوع STOP، مقدار عنصر body خالی است و هیچ کاربرد خاصی ندارد.
= {{anchor|RefHeadingToc29652379132256}} بررسی پیام نوع TEXT از کاربر به بازو =
زمانیکه یک کاربر سروشی در صفحهی مربوط به ربات (بازوی) شما، یک متن بنویسد و ارسال کند، نوع پیام یا همان مقدار data['''''''type''''''']$ برابر با '''TEXT '''، برای بازو ارسال میگردد و مقدارdata[''''body'''']$ برابر با متن کاربر خواهد بود. (همچنین اگر در بازو از دکمههای کیبورد سفارشی استفاده کنید و کاربر روی آن دکمهها کلیک کند نیز پیامی که به بازو ارسال میگردد، از نوع TEXT خواهد بود.)
پیامهای متنی که از کاربر دریافت میکنید، میتوانند شامل شکلک (ایموجی) و حتّی چندسطری باشند. برای استفاده یا ذخیرهی پیامهای متنی، دقت داشته باشید که هرنوع کاراکتری میتواند در آن وجود داشته باشد؛ پس حتماً آن را از فیلترهای لازم عبور دهید تا ازنظر امنیتی دچار مشکل نشوید.
ساختار پیام نوع '''TEXT''' و اجزای آن شبیه به مثال زیر است:
Array(
[from] => cUHPDyF7D5vvZ14IOfyF0R_uLvoSLyn44zeMVvtGBfoYS7IRpE-NkyfGLUA
[[Image:Image3.png]][body] => شعار هر روز ما
مرگ بر امریکا
[type] => '''TEXT'''
[time] => 1541185421478
)== {{anchor|RefHeadingToc29672379132256}} عنصر 'body' ==
در پیامهای از نوع TEXT، مقدار عنصر body یا همان data[''''body'''']$ برابر با متن ارسالشده از طرف کاربر خواهد بود. همانطور که مثال بالا میبینید، پیامی که کاربر به بازو ارسال کرده، چندسطری نوشته شده و در آن از شکلک (ایموجی) نیز استفاده نموده است. پس باید مواظب باشید؛ چون کاربر میتواند هر کاراکتری ازجمله: ? >" ! /.. < { ] ( = - + ' \ $ @ : , ~ . ^ ; & * _ | # و… را در بین متن پیام خود استفاده نموده باشد. حتماً در صورت لزوم، متن پیام را از فیلترهای مناسب عبور دهید تا ازنظر امنیتی دچار مشکل نشوید.
اگر نیاز به مطالعهی پیامهای متنی باشد (مثلاً در بازوی پشتیبانی وبسایت)، برای نمایش پیامهای متنی نیز میتوانید از روشهایی برای شبیهسازی محیط پیامرسان سروش استفاده کنید تا پیامها را بهتر ببینید.
(نکته: همچنین اگر در بازو از دکمههای کیبورد سفارشی استفاده کنید و کاربر روی آن دکمهها کلیک کند نیز پیامی که به بازو ارسال میگردد، از نوع TEXT خواهد بود. درمورد کیبورد سفارشی، در فصلهای بعد، مفصّل بحث خواهد شد؛ فقط این را بدانید که با فشردن آن دکمهها، دستورات دریافتی در پیامهایی از نوع TEXT به بازو میرسند و مقدار data['''''''body''''''']$ برابر با دستور مربوطه خواهد بود.)
== {{anchor|RefHeadingToc29692379132256}} عنصر 'type' ==
همیشه (در همهی 5 نوع پیام کاربر) وجود دارد و بیانگر نوع پیام است. مثلاً در اینجا پیام از نوع TEXT است.
== {{anchor|RefHeadingToc29712379132256}} عنصر 'from' ==
عنصر from نیز در همهی 5 نوع پیام کاربر، وجود دارد. مقدار آن برابر با شناسهی کاربر موردنظر است. دربارهی 'from'، در بخش مربوط به نوع پیام START بهطور مفصّل، توضیح داده شد. میتوانید از آنجا مطالعه نمایید.
== {{anchor|RefHeadingToc29732379132256}} عنصر 'time' ==
عنصر time نیز در همهی 5 نوع پیام کاربر، وجود دارد. مقدار آن برابر با مُهر زمان رسیدن پیام به سرور سروش است. درمورد 'time'، در بخش مربوط به نوع پیام START، کاملاً توضیح داده شد. میتوانید از آنجا مطالعه نمایید.
= {{anchor|RefHeadingToc29752379132256}} بررسی پیام نوع LOCATION از کاربر به بازو =
زمانیکه یک کاربر سروشی در صفحهی مربوط به ربات (بازوی) شما، یک موقعیت مکانی ارسال کند، نوع پیام یا همان مقدار data['''''''type''''''']$ برابر با '''LOCATION '''، برای بازو ارسال میگردد.
مقادیر data['''''''longitude''''''']$ و data['''''''latitude''''''']$ را خواهیم داشت که برابر با طول و عرض جغرافیایی هستند.
ساختار پیام نوع '''LOCATION''' و اجزای آن شبیه به مثال زیر است:
Array(
[from] => cUHPDyF7D5vvZ14IOfyF0R_uLvoSLyn44zeMVvtGBfoYS7IRpE-NkyfGLUA
[body] =>
[type] => '''LOCATION'''
[time] => 1541185421379
[latitude] => 35.705553132681416
[longitude] => 51.35423647239804
)== {{anchor|RefHeadingToc29772379132256}} عنصر 'latitude' ==
عنصر latitude یا مقدار data['''''''latitude''''''']$ ، برابر با عرض جغرافیایی مکان ارسالشده توسّط کاربر است.
== {{anchor|RefHeadingToc29792379132256}} عنصر 'longitude' ==
عنصر longitude یا مقدار data['''''''longitude''''''']$ ، برابر با طول جغرافیایی مکان ارسالشده توسّط کاربر است.== {{anchor|RefHeadingToc29812379132256}} عنصر 'type' ==
همیشه (در همهی 5 نوع پیام کاربر) وجود دارد و بیانگر نوع پیام است. در اینجا پیام از نوع LOCATION است.
== {{anchor|RefHeadingToc29832379132256}} عنصر 'from' ==
عنصر from نیز در همهی 5 نوع پیام کاربر، وجود دارد. مقدار آن برابر با شناسهی کاربر موردنظر است. دربارهی 'from'، در بخش مربوط به نوع پیام START بهطور مفصّل، توضیح داده شد. میتوانید از آنجا مطالعه نمایید.
== {{anchor|RefHeadingToc29852379132256}} عنصر 'time' ==
عنصر time نیز در همهی 5 نوع پیام کاربر، وجود دارد. مقدار آن برابر با مُهر زمان رسیدن پیام به سرور سروش است. درمورد 'time'، در بخش مربوط به نوع پیام START، کاملاً توضیح داده شد. میتوانید از آنجا مطالعه نمایید.
== {{anchor|RefHeadingToc29872379132256}} عنصر 'body' ==
در پیامهای از نوع LOCATION، معمولاً مقدار عنصر body خالی است و کاربرد خاصی ندارد.
= {{anchor|RefHeadingToc29892379132256}} بررسی پیام نوع FILE از کاربر به بازو =
زمانیکه یک کاربر سروشی در صفحهی مربوط به ربات (بازوی) شما، یک فایل (صوتی، فیلم، تصویر، کتاب، زیپ و...) ارسال کند، نوع پیام یا همان مقدار data['''''''type''''''']$ برابر با '''FILE '''، برای بازو ارسال میگردد. هرنوع فایلی که کاربر به بازو بفرستد، شامل نوع FILE میگردد. باز هم تأکید میکنیم: هرنوع فایل؛ فیلم، آهنگ، عکس، صدای ضبطشده، کتاب pdf، نرمافزار apk یا exe، فشرده rar zip 7z و هر نوع فایل دیگر که کاربر به بازو بفرستد، مقدار data['''''''type''''''']$ برابر با '''FILE '''خواهد شد. امّا برای راحتتر شدن کار، عنصر data['''''''fileType''''''']$ نیز وجود دارد که مشخّص میکند فایل موردنظر در کدام دستهبندی قرار میگیرد. عکس، فیلم، تصویر متحرّک، صدای ضبطشده و یا سایر فایلها. نکته: اجزای پیام FILE، نسبت به هرکدام از دستهبندیهای fileType ، متفاوت است. عناصری که بین همهی دستهبندیهای فایل، مشترکاند بهصورت زیر است:
Array(
[from] => ...
[body] => ...
[type] => '''FILE'''
[time] => ...
[fileName] => ...
['''fileType'''] => ...
[fileSize] => ...
[fileUrl] => ...
)
امّا عناصر دیگری نیز هستند که وجودشان بستگی به دستهبندی یا همان مقدار data['''''''fileType''''''']$ دارد. مثل:
'''thumbnailUrl, imageWidth, imageHeight''' :عناصر اضافهتر برای دستهبندیهای عکس و تصویر متحرّک
'''thumbnailUrl, fileDuration, thumbnailWidth, thumbnailHeight''' :عناصر اضافهتر برای دستهبندی فیلم
'''fileDuration''' :عناصر اضافهتر برای دستهبندی پیامهای صوتی ضبطشده= {{anchor|RefHeadingToc29912379132256}} - دستهبندی فایلهای ارسالی از کاربر به بازو =
پس اگر پیام کاربر، یک فایل باشد، مقدار data['''''''type''''''']$ برابر با '''FILE''' است. آنگاه عنصر data['''''''fileType''''''']$ را نیز خواهیم داشت که دستهبندی فایل را مشخّص مینماید و فایلها را در چند دستهبندی زیر قرار میدهد:
'''IMAGE''' : عکسها (تصاویر ثابت) _ مثل تصاویر jpg و png و...
'''GIF''' : تصاویر متحرّک _ تصاویر با پسوند gif
'''VIDEO''' : ویدئو (فیلم، کلیپ) _ مثل mp4 و...
'''PUSH_TO_TALK''' : پیامهای صوتی ضبطشده (مثل m4a)
'''ATTACHMENT''' : سایر فایلها (هر نوع فایل معمولی دیگر)
== {{anchor|RefHeadingToc29932379132256}} * اجزای مشترک در همهی دستهبندیهای فایل ==
== {{anchor|RefHeadingToc29952379132256}} عنصر 'type' ==
همیشه (در همهی 5 نوع پیام کاربر) وجود دارد و بیانگر نوع پیام است. در اینجا پیام از نوع FILE است.
== {{anchor|RefHeadingToc29972379132256}} عنصر 'from' ==
عنصر from نیز در همهی 5 نوع پیام کاربر، وجود دارد. مقدار آن برابر با شناسهی کاربر موردنظر است. دربارهی 'from'، در بخش مربوط به نوع پیام START بهطور مفصّل، توضیح داده شد. میتوانید از آنجا مطالعه نمایید.
== {{anchor|RefHeadingToc29992379132256}} عنصر 'time' ==
عنصر time نیز در همهی 5 نوع پیام کاربر، وجود دارد. مقدار آن برابر با مُهر زمان رسیدن پیام به سرور سروش است. درمورد 'time'، در بخش مربوط به نوع پیام START، کاملاً توضیح داده شد. میتوانید از آنجا مطالعه نمایید.
== {{anchor|RefHeadingToc30012379132256}} عنصر 'body' ==
در پیامهای از نوع FILE، مقدار عنصر body یا همانdata[''''body'''']$ ، برابر با «عنوان»، یعنی '''توضیحات''' نوشتهشده در زیر فایل است. اگر فایل، هیچگونه توضیحاتی نداشت، عنصر data[''''body'''']$ نیز وجود '''ندارد'''.
== {{anchor|RefHeadingToc30032379132256}} عنصر 'fileName' ==
مقدار data[''''fileName'''']$ برابر با نام واقعی فایل ارسالشده میباشد. مثلاً Clip97.mp4
== {{anchor|RefHeadingToc30052379132256}} عنصر 'fileType' ==
مقدار data[''''fileType'''']$ بیانگر دستهبندی فایل است.
== {{anchor|RefHeadingToc30072379132256}} عنصر 'fileSize' ==
مقدار data[''''fileSize'''']$ برابر با حجم فایل برحسب بایت میباشد.
== {{anchor|RefHeadingToc30092379132256}} عنصر 'fileUrl' ==
مقدار data[''''fileUrl'''']$ ، حاوی نشانی کدشدهی فایل است که در آینده برای دریافت و ذخیرهی فایل از آن نشانی استفاده خواهیم کرد. درواقع، اکنون فقط مشخّصات فایل را از سرور سروش گرفتهایم. در آینده اگر خواستیم با استفاده از متد مخصوص، خود فایل را نیز دریافت و در سیستم یا سرور بازو، ذخیره میکنیم.
:
::
:: '''نکته:''' اجزای (عناصر) بالا بهصورت مشترک، در همهی پیامهای نوع FILE ، وجود دارند. البتّه اگر فایل هیچگونه توضیحاتی نداشت، عنصر data[''''body'''']$ نیز وجود ندارد. در ادامه نیز اجزایی معرّفی میشوند که وجود آنها بستگی به مقدار data[''''fileType'''']$ دارد.
:: درحالیکه مقدار data[''''type'''']$ برابر با '''FILE''' است، مقدار data[''''fileType'''']$ نیز مشخّص میکند فایل موردنظر در کدام دستهبندی قرار میگیرد. عکس - تصویر متحرّک - فیلم - پیغام صوتی ضبط شده - سایر...
فایل بازوی log2.php به همراه این فصل در کانال [http://splus.ir/baazoo http://splus.ir/baazoo] منتشر میگردد. آن را اجرا و تعدادی فایل مختلف را به بازو ارسال کنید. سپس نتایج را ببینید و ساختار پیامهای نوع فایل را بهتر بشناسد.== {{anchor|RefHeadingToc30132379132256}} * اجزای اضافهتر در دستهبندیهای IMAGE و GIF ==
اگر مقدار data[''''fileType'''']$ برابر با IMAGE یا GIF بود، علاوه بر عناصری که بهعنوان اجزای مشترک ذکر شد، چند عنصر دیگر نیز در آرایهی data$ خواهیم داشت:
Array(
[from] => cUHPDyF7D5vvZ14IOfyF0R_uLvoSLyn44zeMVvtGBfoYS7IRpE-NkyfGLUA
[body] => پیام امروز مدیر
[type] => '''FILE'''
[time] => 1541263742962
[fileName] => Karbala.jpg یا loading.gif
[fileType] => '''IMAGE''' یا '''GIF'''
[fileSize] => 52765
[fileUrl] => 5YbtEPiMey9oqvsiz9uDXjYJJKP6yVU_YTGxjKWgf14pgGLmCZW ...ادامه
[thumbnailUrl] => zHGhcjUxVLWky7PgFPaqACc9jddV9Yck6C8JzkzBiyl0taDmx ...ادامه
[imageWidth] => 810
[imageHeight] => 605
)== {{anchor|RefHeadingToc30152379132256}} عنصر 'thumbnailUrl' ==
مقدار data[''''thumbnailUrl'''']$ ، حاوی نشانی کدشدهی یک تصویر پیشنمایش کوچک و کمحجم از فایل است که در آینده برای دریافت و ذخیرهاش از آن نشانی استفاده خواهیم کرد. ممکن است تصویر اصلی، بسیار بزرگ و پرحجم باشد؛ به همین خاطر از این تصویر پیشنمایش که عکس ثابت بسیار کوچک و غیرشفّاف است،در برخی موارد استفاده خواهیم نمود. (پیشنمایش، فقط یک عکس ثابت است که قبل از باز کردن یا دانلود عکس بزرگ اصلی، برای کاربر نمایش داده میشود.
نشانی خود تصویر اصلی با کیفیت واقعی، از طریق مقدار data['''''''fileUrl''''''']$ در دسترس است.== {{anchor|RefHeadingToc30172379132256}} عنصر 'imageWidth' ==
مقدار data[''''imageWidth'''']$ برابر با عرض تصویر برحسب پیکسل (px) است.
== {{anchor|RefHeadingToc30192379132256}} عنصر 'imageHeight' ==
مقدار data[''''imageHeight'''']$ برابر با ارتفاع تصویر برحسب پیکسل (px) است.
:
::
== {{anchor|RefHeadingToc30212379132256}} * اجزای اضافهتر در دستهبندی VIDEO ==
اگر مقدار data[''''fileType'''']$ برابر با VIDEO بود، علاوه بر عناصری که بهعنوان اجزای مشترک ذکر شد، چند عنصر دیگر نیز در آرایهی data$ خواهیم داشت:
Array(
[from] => cUHPDyF7D5vvZ14IOfyF0R_uLvoSLyn44zeMVvtGBfoYS7IRpE-NkyfGLUA
[body] => کلیپ درسی
[type] => '''FILE'''
[time] => 1541264500289
[fileName] => Clip97.mp4
[fileType] => '''VIDEO'''
[fileSize] => 42289530
[fileUrl] => y9oqvsi5YbMez9KPGL6yVutEPiDXjYJJU_YTGxpgmCZWjKWgf14 ...ادامه
[thumbnailUrl] => jUxVzHGFPahcLWy7Pgq9jddV9kBiyl0taDmxYcACck6C8Jzkz ...ادامه
[fileDuration] => 549280
[thumbnailWidth] => 960
[thumbnailHeight] => 720
)== {{anchor|RefHeadingToc30232379132256}} عنصر 'thumbnailUrl' ==
مقدار data[''''thumbnailUrl'''']$ حاوی نشانی کدشدهی یک تصویر پیشنمایش کوچک و کمحجم از فایل ویدئو است که در آینده برای دریافت و ذخیرهاش از آن نشانی استفاده خواهیم کرد. (پیشنمایش، فقط یک عکس ثابت است که قبل از باز کردن ویدئو، برای کاربر نمایش داده میشود.) ممکن است ویدئوی اصلی، بسیار بزرگ و پرحجم باشد؛ به همین خاطر از این تصویر پیشنمایش که یک عکس ثابت بسیار کوچک و غیرشفّاف است،در برخی موارد استفاده خواهیم نمود. نشانی خود ویدئوی اصلی با کیفیت واقعی، از طریق مقدار data['''''''fileUrl''''''']$ در دسترس است.== {{anchor|RefHeadingToc30252379132256}} عنصر 'fileDuration' ==
مقدار data[''''fileDuration'''']$ برابر با مدّتزمان فیلم برحسب میلیثانیه میباشد. (هزارم ثانیه)== {{anchor|RefHeadingToc30272379132256}} عنصر 'thumbnailWidth' ==
مقدار data[''''thumbnailWidth'''']$ برابر با عرض تصویر پیشنمایش، برحسب پیکسل (px) است که معمولاً با عرض کادر ویدئوی اصلی نیز مساوی است.
== {{anchor|RefHeadingToc30292379132256}} عنصر 'thumbnailHeight' ==
مقدار data[''''thumbnailHeight'''']$ برابر با ارتفاع تصویر پیشنمایش، برحسب پیکسل (px) است که معمولاً با ارتفاع کادر ویدئوی اصلی نیز مساوی است.== {{anchor|RefHeadingToc30312379132256}} * اجزای اضافهتر در دستهبندی PUSH_TO_TALK ==
اگر مقدار data[''''fileType'''']$ برابر با PUSH_TO_TALK بود، علاوه بر عناصری که بهعنوان اجزای مشترک ذکر شد، یک عنصر دیگر نیز در آرایهی data$ خواهیم داشت:
Array(
[from] => cUHPDyF7D5vvZ14IOfyF0R_uLvoSLyn44zeMVvtGBfoYS7IRpE-NkyfGLUA
[body] => پیام امروز مدیر
[type] => '''FILE'''
[time] => 1541272890259
[fileName] => Payam.m4a
[fileType] => '''PUSH_TO_TALK'''
[fileSize] => 1068442
[fileUrl] => qvy9osi5PGDbMez9KjYJXYutEpPL6yViJU_YgmCZgf14WTGxjKW ...ادامه
[fileDuration] => 187855
)== {{anchor|RefHeadingToc30332379132256}} عنصر 'fileDuration' ==
مقدار data[''''fileDuration'''']$ برابر با مدّتزمان پیام صوتی برحسب میلیثانیه میباشد. (هزارم ثانیه)
== * اجزای اضافهتر در دستهبندی ATTACHMENT ==
اگر مقدار data[''''fileType'''']$ برابر با ATTACHMENT باشد، فقط همان عناصری که بهعنوان اجزای مشترک ذکر شد را دارد و هیچگونه عنصر اضافهتری ندارد.
Array(
[from] => cUHPDyF7D5vvZ14IOfyF0R_uLvoSLyn44zeMVvtGBfoYS7IRpE-NkyfGLUA
[body] => جزوه ریاضی
[type] => '''FILE'''
[time] => 1541264251122
[fileName] => jozve.pdf
[fileType] => '''ATTACHMENT'''
[fileSize] => 71322
[fileUrl] => osiqvy95PGDbMezEpP9KjYJXYutyViJU_YgmWTGxL6jKWCZgf14 ...ادامه
)
'''توجّه: فایلهای مربوط به هر فصل، در کانال سروش baazoo موجود است: [http://splus.ir/baazoo http://splus.ir/baazoo][[Image:Image6.png]] '''
با توجّه به تقبّل هزینههای تولید این کتاب جهت کمک به پیشرفت پیامرسانهای داخلی از سوی مرکز jdf.scr.ir ، خواهشمندیم شما نیز در صورت تمایل، از آن مرکز '''حمایت''' فرمایید:
[[Image:Image17.png]]'''http://scr.ir/pardakht/?hemayat=sbot'''
'''صلوات'''
* * * * * * * * * * * * * * * * * * * * * * * * *
* * * * * * * * * * * * * * * * * * * * * * * * *
* * * * * * * * * * * * * * * * * * * * * * * * *
* * * * * * * * * * * * * * * * * * * * * * * * *
* * * * * * * * * * * * * * * * * * * * * * * * *
* * * * * * * * * * * * * * * * * * * * * * * * *
نشانی کوتاه این صفحه: