Rework Dirs

2024-09-01 18:34:55 +03:30
parent 84196c3034
commit 8c9be226a5
51 changed files with 0 additions and 92 deletions
--- a/Tools/TelegramBot/GettingStarted.md
+++ b/Tools/TelegramBot/GettingStarted.md
@@ -0,0 +1,172 @@
+# کد نویسی برای بات تلگرام
+ربات **تلگرام** (**telegram** bot) یک نوع حساب کاربری ویژه در **تلگرام** است که به صورت اتوماتیک پیام ها را ارسال و دریافت می نماید . کاربران از طریق ارسال دستورات گوناگون با ربات ها در ارتباط هستند و امکان مدیریت ربات ها از طریق API **تلگرام** و درخواست های HTTPS وجود دارد . عبارت bot برای ربات ها نمایش داده می شود.
+
+## ساخت بات با BotFather
+اولین مرحله برای کد نویسی بات تلگرام ساختن بات است. از طریق [BotFather](https://telegram.me/BotFather) بات را خواهیم ساخت. پیام `start/` را در BotFather وارد کنید سپس روی **newbot - create a new bot/** کلیک کنید. بعد از مشاهده پیام **Alright, a new bot. How are we going to call it? Please choose a name for your bot.** یک اسم برای بات خود وارد کنید. 
+سپس بعد از مشاهده پیام **Good. Now let's choose a username for your bot. It must end in bot. Like this, for example: TetrisBot or tetris_bot.** یک نام **خاص و Unique انگلیسی** که حتما در آخرش کلمه **bot** را دارد وارد کنید.
+
+زمانی که بات شما ساخته شد توکن بات را که زیر **Use this token to access the HTTP API** قرار دارد را کپی کنید و در محل امنی قرار دهید.
+
+## آماده سازی محیط کد نویسی
+به طور کلی از دو روش می توان برای بات های تلگرام برنامه نویسی کرد. 
+**روش اول: استفاده از Rest API رسمی تلگرام که نحوه استفاده از در سایت core.telegram.org/bots/api قابل دسترس است**
+**روش دوم: استفاده از پکیج هایی که کد های پایه بات را برای زبان برنامه نویسی مورد نظر شما ساخته اند**
+برخی از این پکیج های عبارت اند از:
+برای سی شارپ ([Telegram.Bot](https://www.nuget.org/packages/Telegram.Bot)) 
+	این پکیج از طریق کامند زیر در **Dotnet CLI** نصب می شود
+
+	dotnet add package Telegram.Bot --version 19.0.0
+
+برای پایتون ( [python-telegram-bot](https://pypi.org/project/python-telegram-bot/2.4/))
+این پکیج نیز از طریق کامند زیر قابل نصب است
+
+    pip install python-telegram-bot==2.4
+
+برای اینکه این آموزش بر Core و Universal بودن تاکید دارد ما از از طریق روش اول برای بات خود کد نویسی هر چند این روش کمی سخت تر است اما اگر به خوبی این روش را یادبگرید خود می توانید کتابخانه مانند دو نمونه بالا بنوسید
+
+## کد نویسی برای بات
+پروژه ای با زبان مورد نظر خود ایجاد کنید و کتابخانه هایی مورد نیاز برای **Rest API** را روی پروژه نصب یا Import کنید. 
+برای مثال اگر از زبان برنامه نویسی سی شارپ استفاده می کنید باید **RestSharp** را نصب کنید و نحوه کار با آن را بلد باشید و اگر از پایتون استفاده می کنید باید کتابخانه **Request** را نصب و Import کنید.
+
+**قبل از شروع به این نکات درباره API تلگرام توجه کنید.**
+
+ تلگرام به حروف بزرگ و کوچک در API حساس است
+ تلگرام فقط از **POST** و **GET** پشتیبانی می کند
+ همه درخواست ها باید کاملا با **UTF-8** باشند
+ تلگرام از هر 4 روش رایج ارسال درخواست **(application/json, multipart/form-data ,QueryString, application/x-www-form-urlencoded)** پشتیبانی می کند
+**پیشنهاد:** من به شما پیشنهاد می کنم از QueryString یا application/json استفاده کنید.
+
+### روش QueryString چیست؟
+در این روش پارامتر های تابع که می خواهیم اجرا کنیم به عنوان QueryString در Url گذاشته می شوند مانند:
+
+	https://test.ir/APIFunction?param1=inp1&param2=inp2
+
+همانطور که در مثال بالا آشکار است هر چه بعد از **?** قرا ر می گیرد **Query String** است. 
+پارامتر 1 یا **param1** اسم متغیر اول ماست و **inp1** ورودی متغیر **param1** است.
+سپس پارامتر های ورودی با علامت **&** جدا شده اند. و پارمتر دوم یا **param2** و ورود آن قرار گرفته است.
+
+### روش application/json
+در این روش Url فقط به آدرس تابع اشاره دارد نه به ورود های آن مانند:
+
+    https://test.ir/APIFunction
+
+   در این روش پارامتر ها به عنوان Json در بدنه ارسال می شوند. مانند زیر 
+
+    {
+        "Body":{
+            "param1":"inp1",
+            "param2":"inp2",
+    },
+
+البته ارسال بدنه با توجه به کتابخانه که برای API استفاده می کنید. متفاوت مثلا برای **RestSharp** از Request.AddBody باید استفاده کنید.
+
+## استاندارد های استفاده از API تلگرام
+**آدرس پایه API:** 
+
+    https://api.telegram.org/bot<token>/<FuncName>
+
+**توکن:** به جای **<token>** توکنی را که از بات فادر گرفتید قرار دهید
+**نام تابع:** تابعی که می خواهید فراخوانی کنید را به جای **<Funcname>** قرار دهید
+
+**موفق بودن یا نا موفق بودن درخواست**
+اگر درخواست شما **موفقیت آمیز** باشد با **OK:True**  مواجه می شوید و جواب درخواست را به عنوان **Result** به شما برگردانده می شود
+**مثال:**
+
+	{
+	"ok":true,
+	"result":[]
+	}
+
+اگر درخواست شما **ناموفق** باشد. **OK: False** می شود و شما پارامتر به عنوان **Result** نخواهید داشت همچنین **error_code** و **description** را به ترتیب برای شماره خطا و توصیف خطا دریافت خواهید کرد. 
+**مثال: **
+
+	{
+	"ok":false,
+	"error_code":404,
+	"description":"Not Found" 
+	}
+
+**بروزرسانی بات:**
+هر بار که پیامی برای بات ارسال می شود را می توان با **getUpdate** بدست آورد. برای بدست آوردن لیست آپدیت می توانید Url زیر را GET کنید
+
+	https://api.telegram.org/bot<token>/getUpdates
+
+این درخواست لیستی از Update ها بر می گرداند. 
+برای مشاهده شئ Update به https://core.telegram.org/bots/api#update مراجعه کنید
+
+**دریافت اطلاعات کلی بات:**
+برای دریافت اطلاعات کلی از آدرس زیر استفاده کنید
+
+    https://api.telegram.org/bot<token>/getMe
+
+**جواب:**
+
+    {
+      "ok": true,
+      "result": {
+        "id": 6775339167,
+        "is_bot": true,
+        "first_name": "ForDocumentPack",
+        "username": "ForDocumentPackBot",
+        "can_join_groups": true,
+        "can_read_all_group_messages": false,
+        "supports_inline_queries": false
+      }
+    }
+
+## ساخت پروژه ساده
+می خواهیم یک پروژه کد نویسی کنیم که زمانی که بات روشن می شود یک پیام خوش آمد گویی ارسال کند.
+برای این کار از طریق تابع **getUpdates** پیام هایی که بات داده شده است را مشاهده می کنیم مانند زیر:
+
+	{
+      "ok": true,
+      "result": [
+        {
+          "update_id": 529754041,
+          "message": {
+            "message_id": 1,
+            "from": {
+              "id": 407692495,
+              "is_bot": false,
+              "first_name": "Mahdiyar",
+              "last_name": "Abdollahi",
+              "username": "Mdr_abdollahi",
+              "language_code": "en"
+            },
+            "chat": {
+              "id": 407692495,
+              "first_name": "Mahdiyar",
+              "last_name": "Abdollahi",
+              "username": "Mdr_abdollahi",
+              "type": "private"
+            },
+            "date": 1697995311,
+            "text": "/start",
+            "entities": [
+              {
+                "offset": 0,
+                "length": 6,
+                "type": "bot_command"
+              }
+            ]
+          }
+        }
+      ]
+    }
+
+**نکته: get_updates را در حلقه بی نهایت بی اندازید تا همیشه بروزرسانی شود**
+**نکته: بررسی کنید تا به کسانی که به آنها پاسخ داده اید دوباره پاسخ ندهید.**
+**نکته: اگر به جای getUpdates از** [WebHooks](https://core.telegram.org/bots/api#getting-updates) **استفاده کنید نیاز به بررسی پاسخ های تکراری نیست**
+
+برای ارسال پیام نیاز به **chat_id** داریم.
+
+	result => message => chat => id
+
+بعد از دریافت **chat_id** می توانیم با تابع **sendMessage** پیام برای کاربر ارسال کنید. 
+
+	https://api.telegram.org/bot<token>/sendMessage
+
+**نکته: حتما باید پارامتر chat_id و text ارسال شود**
+**نکته: حتما باید بصورت POST ارسال شود و پارامتر ها به صورت application/json باشد**
+
+شما می توانید تمامی تابع های API تلگرام را از سایت تلگرام مشاهده کنید -> https://core.telegram.org/bots/api
--- a/Tools/TelegramBot/LocalTelegramBotServer.md
+++ b/Tools/TelegramBot/LocalTelegramBotServer.md
@@ -0,0 +1,41 @@
+# آموزش اجرای سرور بات تلگرام 
+در این سند قصد داریم که سرور بات تلگرام را به  صورت لوکال بالا بیاوریم. توجه داشته باشید که شما می توانید از سرور های پیشفرض تلگرام به آدرس **api.telegram.org** استفاده کنید اما اگر قصد دارید که از قابلیت های ویژه مانند اتصال webhook لوکال استفاده نیاز به این سند دارید.
+[کاربرد های سرور لوکال تلگرام](https://github.com/tdlib/telegram-bot-api#usage)
+
+**این آموزش فقط برای سیستم های بر پایه Ubuntu 22.04 تست شده است**
+
+## مرحله اول: نصب وابستگی ها
+یک سری نرم افزار ها و پکیج ها را باید قبل از اجرای سرور نصب کرد
+**اوپن اس اس ال - Open SSL**
+
+	sudo apt-get install libssl-dev
+
+**کامپایلر سی پلاس پلاس نسخه 14 ما از g++ 14 استفاده خواهیم کرد**
+
+    sudo add-apt-repository ppa:ubuntu-toolchain-r/test
+    sudo apt update
+    sudo apt install g++
+
+**زی لیب - zlib**
+
+	sudo apt install zlib1g
+
+**جی پرف - gperf**
+
+	sudo apt install gperf
+
+**سی میک - cmake**
+
+	sudo apt install cmake
+
+## مرحله دوم: نصب
+برای نصب دستورات زیر را در ترمینال وارد کنید
+
+	git clone --recursive https://github.com/tdlib/telegram-bot-api.git
+    cd telegram-bot-api
+    mkdir build
+    cd build
+    cmake -DCMAKE_BUILD_TYPE=Release ..
+    cmake --build . --target install
+
+```
--- a/Tools/TelegramBot/WebHooks.md
+++ b/Tools/TelegramBot/WebHooks.md
@@ -0,0 +1,53 @@
+
+# استفاده از Web Hooks در گرفتن پیام های بات تلگرام
+**توجه: پیش نیاز این سند Getting Started.MD است**
+
+دو روش برای دریافت پیام ارسالی به بات در تلگرام وجود دارد. **Get Updates Function** و **Web Hooks** روش **Get Updates Function** را در سند قبلی استفاده و بررسی کردیم. برای درک Web Hook باید اول Get Updates را خوب متوجه شویم
+
+## روش اول: Get Updates
+در این روش که در سندی قبل از آن استفاده کردیم. شما به تلگرام مراجعه می کنید و تلگرام همه پیام هایی تاریخ بات را برای شما می فرستد در این روش چند چالش وجود دارد
+
+ **در هر درخواست تمامی پیام ها ارسال می شود این به معنی  است که در یک بات با مخاطبان متوسط هر درخواست شامل صد ها هزار پیام است که قبلا به آن پاسخ داده اید و به آن ها دیگر نیازی ندارید**
+
+ **باید بررسی کنید که به کدام پیام پاسخ داده شده و به کدام پاسخ نداده شده است**
+
+ **باید از حلقه بی نهایت استفاده کنید تا همیشه از تلگرام درخواست کند. پیاده سازی حلقه بی نهاییت در بسیاری از نرم افزار ها مانند وب سایت بسیار چالش بر انگیز یا غیر ممکن است.**
+
+راه کار بهتر روش Web Hooks است.
+
+## روش دوم: Web Hooks
+در این روش به جای اینکه مانند روش **Get Updates** شما به تلگرام مراجعه کنید. تلگرام به شما مراجعه می کند. **پیام های جدید را که قبلا دریافت نکرده اید** به شما می دهد. این روش هر سه مشکل **Get Updates** را بر طرف می کند. البته این روش نیز بی نقص نیست و چالش به همراه دارد. مانند:
+
+ **چون تلگرام باید برای شما چیزی ارسال کند نمی توان از این روش در فضای Local استفاده کرد**
+
+ **محدودیت توسط تلگرام برای این روش اعمال شده است که ممکن است رفع این محدودیت ها هزینه بر یا وقت گیر باشد**
+
+
+### محدودیت های Web Hooks
+
+ **اگر از وب هوکس استفاده کنید دیگر نمی توانید از getUpdates استفاده کنید**
+ **فقط پورت های 443, 80, 88, 8443 برای اینکار قابل استفاده اند**
+ **فقط تلگرام به سایت هایی که دارای SSL هستند. پیام ها را ارسال می کند**
+
+## تنظیم از Web Hooks
+برای تنظیم وب هوک از طریق  تابع **setWebhook** آدرسی که می خواهیم به آن پیام ها ارسال شود را به عنوان **Url** ارسال می کنیم
+
+	https://api.telegram.org/bot<token>/setWebhook
+
+**نکنه: حتما از متد POST استفاده کنید و Url را با روش application/json بفرستید**
+
+برای مشاهده پارامتر های اختیاری Web Hooks به لینک زیر مراجعه کنید 
+[https://core.telegram.org/bots/api#setwebhook](Web%20Hooks)
+
+## پاک کردن Web Hooks
+اگر به هر دلیلی خواستید وب هوک را پاک کنید یا از get Updates استفاده کنید با استفاده از تابع زیر وب هوکس پاک شده و Get Updates دوباره فعال می شود
+
+	https://api.telegram.org/bot<token>/deleteWebhook
+
+## مشاهده وضعیت Web Hooks
+با تابع زیر می توان وضعیت وب هوک، سرعت پاسخ دهی، آخرین خطا ها، آخرین هشدار ها و... را مشاهده کرد
+
+	https://api.telegram.org/bot<token>/getwebhookinfo
+
+[برای مشاهده اطلاعات دریافتی از این تابع کلیک کنید](https://core.telegram.org/bots/api#webhookinfo)
+