Pabal API

Pabal API (MTProto)

សម្រាប់ពេលបង្កើតកម្មវិធីអតិថិជនដែលភ្ជាប់ទៅម៉ាស៊ីនមេតាមរបៀបដូចកម្មវិធី៖ ព័ត៌មានការតភ្ជាប់ សោសាធារណៈរបស់ម៉ាស៊ីនមេ លំហូរការផ្ទៀងផ្ទាត់ update និងវិសាលភាពដែលគាំទ្រ។

កម្មវិធី Pabal ទំនាក់ទំនងជាមួយម៉ាស៊ីនមេតាម MTProto 2.0។ សូមអានឯកសារនេះ ពេលបង្កើតកម្មវិធីដែលភ្ជាប់តាមរបៀបដូចគ្នា — កម្មវិធីផ្សេង ស្វ័យប្រវត្តិកម្មដែលដំណើរការជាគណនីមនុស្ស ឬកម្មវិធីអតិថិជនសម្រាប់ការស្រាវជ្រាវ។ បើអ្នកបង្កើតបូត Bot API ដែលសាមញ្ញជាង គឺគ្រប់គ្រាន់ហើយ។

សូមអានឯកសាររបស់ Telegram ផងដែរ

ដោយសារ Pabal អនុវត្តតាមពិធីការសាធារណៈរបស់ Telegram និយមន័យលម្អិតនៃពិធីការ និង method គឺផ្អែកលើឯកសារ MTProto និង API methods។ ឯកសារនេះកត់ត្រាភាពខុសគ្នា និងវិសាលភាពដែលគាំទ្រ ពេលភ្ជាប់ទៅម៉ាស៊ីនមេ Pabal។

ព័ត៌មានការតភ្ជាប់

ធាតុ	តម្លៃ
អាសយដ្ឋាន	`122.34.175.215`
ច្រក (port)	`8443` (TCP)
DC	DC 1 ដល់ 5 ប្រើអាសយដ្ឋានដូចគ្នាទាំងអស់។ អាចភ្ជាប់តាម DC ណាក៏បាន ហើយជាធម្មតាប្រើ 2
ពិធីការ	MTProto 2.0, API layer 216
របៀបដឹកជញ្ជូន	Abridged, Intermediate, Padded Intermediate, Full — នីមួយៗរួមទាំងការបិទបាំង (obfuscated2)
សោសាធារណៈរបស់ម៉ាស៊ីនមេ	server-key.pem · fingerprint `8724853375441383205`
api_id · api_hash	មិនត្រូវបានពិនិត្យទេ។ ដាក់តម្លៃណាក៏បាន

ការដឹកជញ្ជូនតាម HTTP តាម WebSocket និង MTProxy មិនទាន់មាននៅឡើយទេ។ នាឡិការបស់ឧបករណ៍អតិថិជនត្រូវតែត្រឹមត្រូវ — ដោយសារលេខសារ MTProto បង្កើតចេញពីពេលវេលា បើនាឡិកាខុសច្រើន ម៉ាស៊ីនមេនឹងបោះចោលសារ។

សោសាធារណៈរបស់ម៉ាស៊ីនមេ

ពេលភ្ជាប់ជាលើកដំបូង កម្មវិធីអតិថិជន MTProto អ៊ិនគ្រីបការផ្លាស់ប្តូរ auth key ដោយសោសាធារណៈ RSA របស់ម៉ាស៊ីនមេ។ កម្មវិធីអតិថិជន Telegram បង្កប់សោសាធារណៈរបស់ Telegram ក្នុងខ្លួន ដូច្នេះដើម្បីភ្ជាប់ទៅ Pabal ត្រូវដាក់សោនេះជំនួស (ឬបន្ថែម)។ សោនេះការពារកុំឲ្យម៉ាស៊ីនមេផ្សេងក្លែងខ្លួនជាម៉ាស៊ីនមេ Pabal។

curl -s -o server-key.pem https://pabal.me/docs/server-key.pem

សោនេះត្រូវបានបង្កើតតែម្តង ពេលម៉ាស៊ីនមេបើកជាលើកដំបូង ហើយមិនផ្លាស់ប្តូរទេ។ សូមពិនិត្យថាតម្លៃ Loaded RSA key … (fingerprint …) ក្នុង log របស់ម៉ាស៊ីនមេ ដូចនឹង fingerprint ខាងលើ។

ការភ្ជាប់ដោយ Telethon

នេះជាឧទាហរណ៍នៃការចូលគណនីមនុស្ស ហើយផ្ញើ និងទទួលសារ ដោយប្រើ Telethon របស់ Python។ សូមចុះឈ្មោះគណនីក្នុងកម្មវិធីជាមុនសិន (មើលខាងក្រោម)។

# pabal_client.py — pip install telethon==1.42.0
# ដាក់ server-key.pem (សោសាធារណៈរបស់ម៉ាស៊ីនមេ ដែលបានទាញយកខាងលើ) ក្នុងថតដដែល
import asyncio

from telethon import TelegramClient, events
from telethon.crypto import rsa

rsa.add_key(open("server-key.pem").read(), old=False)          # សោសាធារណៈរបស់ម៉ាស៊ីនមេ Pabal

client = TelegramClient("pabal", api_id=1, api_hash="0" * 32)  # រក្សាទុកការចូលគណនីក្នុង pabal.session
client.session.set_dc(2, "122.34.175.215", 8443)


@client.on(events.NewMessage(incoming=True))
async def show(event):
    sender = await event.get_sender()
    print(f"{sender.first_name}: {event.raw_text}")


async def main():
    await client.start(phone=lambda: input("លេខទូរស័ព្ទ (+8210…): "))   # បញ្ចូលលេខកូដតែម្តងលើកដំបូង
    me = await client.get_me()
    print(f"បានចូលគណនី៖ {me.first_name} (id {me.id})")
    await client.send_message("BotFather", "/help")
    await client.run_until_disconnected()


asyncio.run(main())

សូមប្រើ Telethon 1.42។ វាជាកំណែដែលនិយាយ layer 216។ កំណែថ្មីជាងនេះ ព្យាយាមអានការឆ្លើយតបដោយ layer ខ្ពស់ជាង ហើយបរាជ័យដោយ TypeNotFoundError។
Telethon បានបិទការចុះឈ្មោះគណនីថ្មី (sign_up())។ សូមចុះឈ្មោះក្នុងកម្មវិធី ឬហៅ auth.signUp ដោយផ្ទាល់។
ការចូលគណនីត្រូវបានរក្សាទុកក្នុងឯកសារ pabal.session ដូច្នេះលើកក្រោយនឹងមិនសួរលេខកូដទៀតទេ។ ឯកសារនេះជាកូនសោនៃគណនី សូមការពារវា។

លំហូរការចូលគណនី

បង្កើត auth key ហើយចូលគណនីដោយលេខកូដ

ការពន្យល់ដ្យាក្រាម

ពីរដំណាក់កាល៖ ខាងលើជាដំណាក់កាលបង្កើត auth key សម្រាប់ការអ៊ិនគ្រីប (ពិធីការ) ហើយខាងក្រោមជាដំណាក់កាលចូលគណនី ដែលភ្ជាប់គណនីទៅនឹងសោនោះ (API)។ បណ្ណាល័យធ្វើដំណាក់កាលខាងលើឲ្យដោយស្វ័យប្រវត្តិ។
ការចូលគណនីភ្ជាប់ទៅនឹង auth key៖ ទោះបើកវគ្គ (session) ច្រើនដោយសោដែលបានចូលគណនីម្តងហើយ វគ្គទាំងអស់នៅតែស្ថិតក្នុងស្ថានភាពចូលគណនី។ បើបាត់សោ (លុបឯកសារ session) ត្រូវចូលគណនីម្តងទៀត។
ប្រតិបត្តិករម៉ាស៊ីនមេ ជាអ្នកកំណត់ផ្លូវដែលលេខកូដត្រូវទៅ៖ បើជា SMS ឬអ្នកគ្រប់គ្រងបញ្ជូន អ្នកនឹងទទួលបាន sentCodeTypeSms ហើយបើជាអ៊ីមែល អ្នកនឹងទទួលបាន sentCodeTypeSetUpEmailRequired រួចកម្មវិធីអតិថិជនសួរអាសយដ្ឋានអ៊ីមែល ហើយហៅ account.sendVerifyEmailCode (ជួរកណ្តាល)។
បន្ទាត់ដាច់ៗពណ៌ក្រហម ជាផ្លូវសម្រាប់លេខថ្មី៖ បើលេខកូដត្រឹមត្រូវ តែគ្មានគណនី អ្នកនឹងទទួលបាន authorizationSignUpRequired ហើយពេលហៅ auth.signUp ដោយដាក់ឈ្មោះ ការចុះឈ្មោះត្រូវបានបញ្ចប់។ ការចុះឈ្មោះអាចធ្វើបាន លុះត្រាតែបញ្ចូលលេខកូដត្រឹមត្រូវរួច។
បូតចូលគណនីដោយហៅ auth.importBotAuthorization (តូខឹនបូត) តែម្តង ជំនួសឲ្យដំណាក់កាលខាងក្រោម។

កំហុស	ពេលណា
`PHONE_NUMBER_INVALID`	លេខខុស ឬជាលេខថ្មី ខណៈម៉ាស៊ីនមេបិទការចុះឈ្មោះថ្មី
`PHONE_NUMBER_BANNED`	លេខដែលប្រតិបត្តិករបានហាមឃាត់
`FLOOD_WAIT_n` (420)	ស្នើលេខកូដញឹកញាប់ពេក។ ព្យាយាមម្តងទៀតក្រោយ `n` វិនាទី
`PHONE_CODE_INVALID`	លេខកូដខុស (បើលើសចំនួនដងដែលបានកំណត់ វានឹងត្រូវចាក់សោ)
`PHONE_CODE_EXPIRED`	លេខកូដផុតកំណត់ ឬត្រូវចាក់សោ ឬ `phone_code_hash` ដែលម៉ាស៊ីនមេមិនស្គាល់ — ចាប់ផ្តើមម្តងទៀតពី sendCode
`EMAIL_INVALID`, `EMAIL_NOT_ALLOWED`	អាសយដ្ឋានអ៊ីមែលខុស / ជាគណនីដែលមានស្រាប់ ប៉ុន្តែមិនមែនជាអ៊ីមែលចូលគណនីដែលបានចុះបញ្ជី
`AUTH_KEY_UNREGISTERED` (401)	ហៅ method ដែលតម្រូវឲ្យចូលគណនី ដោយប្រើសោដែលមិនទាន់ចូលគណនី

លេខសាកល្បង

នៅលើម៉ាស៊ីនមេដែលប្រតិបត្តិករបានបើកលេខសាកល្បង លេខក្នុងទម្រង់ +99966XYYYY អាចចូលគណនីដោយលេខកូដ XXXXX (X ប្រាំដង) ដោយមិនមានការបញ្ជូនលេខកូដពិតប្រាកដ។ វាជាមុខងារសម្រាប់តែម៉ាស៊ីនមេអភិវឌ្ឍ ហើយត្រូវបានបិទនៅលើម៉ាស៊ីនមេផលិតកម្ម។

ការទទួល update

ភ្លាមៗ៖ បើការតភ្ជាប់នៅបើក ម៉ាស៊ីនមេផ្ញើសារថ្មី ការកែ និងការលុប ភ្លាមៗជា updateShortMessage ឬ updates។ វគ្គដែលបានផ្ញើសំណើ ទទួលលទ្ធផលនោះជាការឆ្លើយតប RPC ដូច្នេះរឿងដដែលមិនមកម្តងទៀតជា push ទេ។
pts៖ ការផ្លាស់ប្តូរនីមួយៗរបស់អ្នកប្រើម្នាក់ៗ មានលេខរៀង (pts)។ បើ pts ដែលកម្មវិធីអតិថិជនទទួលបានមានចន្លោះខ្វះ មានន័យថាវាបានខកខានអ្វីមួយ។
ការតាមទាន់៖ ចងចាំ pts បច្ចុប្បន្នដោយ updates.getState ហើយពេលភ្ជាប់ម្តងទៀត ទទួលសារថ្មី ការលុប និងអ្នកប្រើ និងក្រុមដែលពាក់ព័ន្ធ ក្នុងចន្លោះពេលនោះ ដោយ updates.getDifference(pts, date, qts)។ បើ pts ដែលកម្មវិធីអតិថិជនមាន នាំមុខម៉ាស៊ីនមេ (ឧ. ពេលទិន្នន័យម៉ាស៊ីនមេត្រូវបានកំណត់ឡើងវិញ) អ្នកនឹងទទួលបាន differenceTooLong ដូច្នេះសូមផ្ទុកបញ្ជីការសន្ទនាឡើងវិញ។
បណ្ណាល័យដូចជា Telethon ធ្វើដំណើរការទាំងនេះដោយស្វ័យប្រវត្តិ។

ID និង peer

គោលដៅ	ID	កំណត់ចំណាំ
មនុស្ស	ចាប់ពី 100001	`peerUser`។ @BotFather គឺ 100000
បូត	ប្រព័ន្ធលេខដូចមនុស្ស	`user.bot = true`។ លេខនៅខាងមុខតូខឹន គឺជា ID បូត
ក្រុមមូលដ្ឋាន	ចាប់ពី 1000001	`peerChat`។ នៅក្នុង Bot API វាបង្ហាញជាលេខអវិជ្ជមាន (`-chat_id`)
សារ	ចាប់ពី 1 សម្រាប់ប្រអប់សារនីមួយៗ	ក្នុងការសន្ទនា 1:1 អ្នកចូលរួមម្នាក់ៗមានច្បាប់ចម្លង និងលេខរៀងផ្ទាល់ខ្លួន។ ទោះជាសារតែមួយ ក៏លេខអាចខុសគ្នាសម្រាប់មនុស្សពីរនាក់

សម្រាប់ access_hash សូមរក្សាទុកតម្លៃដែលម៉ាស៊ីនមេផ្តល់ឲ្យដូចដើម ហើយប្រើវា (វាមកជាមួយការស្វែងរកឈ្មោះអ្នកប្រើ បញ្ជីការសន្ទនា និង update)។

ឯកសារ

ការបង្ហោះ៖ បង្ហោះជាផ្នែកៗដោយ upload.saveFilePart ហើយយោងវាដោយ inputFileUploaded…។ upload.saveBigFilePart សម្រាប់ឯកសារធំ មិនទាន់មាននៅឡើយ ដូច្នេះតាមការពិត អាចបង្ហោះបានរហូតដល់ 10MB។
ការផ្ញើ៖ ប្រើ inputMediaUploadedPhoto (រូបថតថ្មី) ឬ inputMediaPhoto (រូបថតដែលមាននៅលើម៉ាស៊ីនមេ) ក្នុង messages.sendMedia។ មេឌៀផ្សេងទៀត MEDIA_INVALID។
ការទទួល៖ ប្រើ inputPhotoFileLocation (រូបថតក្នុងសារ) ឬ inputPeerPhotoFileLocation (រូបប្រវត្តិរូប) ក្នុង upload.getFile។ រហូតដល់ 1MB ក្នុងមួយដង។
រូបប្រវត្តិរូប៖ photos.uploadProfilePhoto, photos.updateProfilePhoto, photos.getUserPhotos, photos.deletePhotos។
រូបថតត្រូវបានរក្សាទុកតែក្នុងទំហំដើមមួយប៉ុណ្ណោះ (មិនបង្កើតរូបតូច thumbnail ដាច់ដោយឡែកទេ)។

វិសាលភាពដែលគាំទ្រ

ម៉ាស៊ីនមេមានកម្មវិធីដោះស្រាយ (handler) សម្រាប់ method ចំនួន 408 នៃ layer 216 ហើយទាំងអស់អាចអានសំណើបាន ប៉ុន្តែ method ដែលបានផ្ទៀងផ្ទាត់ពីដើមដល់ចប់ជាមួយកម្មវិធីអតិថិជនពិត មានតែ method ខាងក្រោមប៉ុណ្ណោះ។ method ផ្សេងទៀតឆ្លើយតាមទម្រង់ត្រឹមត្រូវ ប៉ុន្តែខ្លឹមសារអាចទទេ ឬមិនត្រូវបានកត់ទុក។

វិស័យ	method ដែលបានផ្ទៀងផ្ទាត់
ការតភ្ជាប់	`initConnection`, `invokeWithLayer`, `help.getConfig`, `auth.bindTempAuthKey` (សោបណ្តោះអាសន្ន PFS), `auth.exportAuthorization`/`importAuthorization`
ការចូលគណនី	`auth.sendCode`, `auth.signIn`, `auth.signUp`, `auth.logOut`, `auth.importBotAuthorization`, `account.sendVerifyEmailCode`
អ្នកប្រើ និងទំនាក់ទំនង	`users.getUsers`, `users.getFullUser`, `contacts.resolveUsername`, `contacts.importContacts`, `contacts.search`
សារ	`messages.sendMessage`, `messages.sendMedia` (រូបថត), `messages.getHistory`, `messages.getDialogs`, `messages.getMessages`, `messages.editMessage`, `messages.deleteMessages`
ក្រុម	`messages.createChat`, `messages.deleteChatUser`, `messages.editChatTitle` (`messages.addChatUser` បានផ្ទៀងផ្ទាត់តែជាមួយកម្មវិធីផ្លូវការប៉ុណ្ណោះ)
បូត	`messages.getBotCallbackAnswer`, `messages.setBotCallbackAnswer`, សារដែលមានប៊ូតុង (`reply_markup`)
Update	`updates.getState`, `updates.getDifference`, push ភ្លាមៗ
ឯកសារ និងរូបថត	`upload.saveFilePart`, `upload.getFile`, `photos.*` (ខាងលើ)

យើងក៏បានផ្ទៀងផ្ទាត់ថា Telegram Desktop 6.2.6 ផ្លូវការ ដំណើរការដោយមិនចាំបាច់កែប្រែ ចាប់ពីការចុះឈ្មោះ ការចូលគណនី ការសន្ទនា រូបថត ក្រុម រហូតដល់ការភ្ជាប់ឡើងវិញ។ method ប្រហែល 60 ដែលកម្មវិធីហៅពេលចាប់ផ្តើម ត្រូវបានពិនិត្យទម្រង់ការឆ្លើយតបដាច់ដោយឡែក។

កំហុស

កំហុសមកជា rpc_error ស្តង់ដារ (error_code + error_message)។ error_message ជានិច្ចជាអក្សរធំ លេខ និងសញ្ញាគូសក្រោម (PEER_ID_INVALID) ហើយពេលចាំបាច់ មាន : ការពន្យល់ ភ្ជាប់ពីក្រោយ។

លេខកូដ	អត្ថន័យ
`400`	សំណើខុស — `PEER_ID_INVALID`, `MESSAGE_ID_INVALID`, `MEDIA_INVALID`, `USERNAME_NOT_OCCUPIED` …
`401`	ត្រូវចូលគណនី — `AUTH_KEY_UNREGISTERED`
`403`	គ្មានសិទ្ធិ — ឧ. ក្រុមដែលអ្នកមិនមែនជាសមាជិក
`420`	`FLOOD_WAIT_n` — រង់ចាំ n វិនាទី
`500`	កំហុសខាងក្នុងម៉ាស៊ីនមេ
កំហុសការដឹកជញ្ជូន `-404`	ម៉ាស៊ីនមេមិនស្គាល់ auth key នេះ — បង្កើតសោថ្មី ហើយចូលគណនីម្តងទៀត (សោអចិន្ត្រៃយ៍) ឬភ្ជាប់ (bind) ម្តងទៀត (សោបណ្តោះអាសន្ន)

អ្វីដែលមិនទាន់មាន

ឆានែល និង supergroup (channels.* ឆ្លើយតប ប៉ុន្តែមិនបង្ហាញត្រឹមត្រូវក្នុងកម្មវិធី) ការសន្ទនាសម្ងាត់ ការហៅ
មេឌៀក្រៅពីរូបថត upload.saveBigFilePart រូបតូច (thumbnail)
ការផ្ទៀងផ្ទាត់ 2 ជំហាន (SRP) — មិនអាចកំណត់បាន ហើយសកម្មភាពដែលតម្រូវឲ្យមានការផ្ទៀងផ្ទាត់ 2 ជំហាន ត្រូវបានបដិសេធ
ការដឹកជញ្ជូនតាម HTTP និង WebSocket, MTProxy, ការផ្ញើ msgs_ack, ការប្តូរ bad_server_salt
ការបែងចែកទៅម៉ាស៊ីនមេច្រើន — ម៉ាស៊ីនមេមួយគ្រឿងទទួលបន្ទុក DC 1 ដល់ 5 ទាំងអស់

ដើម្បីភ្ជាប់កម្មវិធី Telegram ផ្លូវការទៅ Pabal

កម្មវិធី Telegram បង្កប់អាសយដ្ឋានម៉ាស៊ីនមេ និងសោសាធារណៈក្នុងខ្លួននៅពេល build។ ដូច្នេះ មិនមែនកែនៅអេក្រង់ការកំណត់ទេ គឺត្រូវកែកូដប្រភព ហើយ build ម្តងទៀត។ កម្មវិធី Pabal (Pabal.app) ត្រូវបានបង្កើតតាមរបៀបនោះ។ បើអ្នកជាប្រតិបត្តិករម៉ាស៊ីនមេ សូមមើល ការដំឡើងម៉ាស៊ីនមេ — ការភ្ជាប់កម្មវិធី។