ការផ្ទៀងផ្ទាត់ភាពត្រឹមត្រូវ

កំណែ API 2026-10-affable-towhee

ការហៅនីមួយៗទៅកាន់ Lingara API ភ្ជាប់មកជាមួយថូខឹនចូលប្រើ។ ម៉ាស៊ីនមេទទួលបានថូខឹនចូលប្រើ ដោយប្ដូរ ID និងសម្ងាត់របស់ក្លាយអិនត៍ OAuth នៅចំណុចបញ្ចប់ថូខឹន៖ នេះជាការផ្តល់សិទ្ធិដោយព័ត៌មានសម្គាល់ក្លាយអិនត៍ (client credentials grant) របស់ OAuth 2.0 សម្រាប់ម៉ាស៊ីនមេដែលធ្វើសកម្មភាពក្នុងនាមខ្លួនឯង។ បង្កើតក្លាយអិនត៍នៅលើទំព័រ ការតភ្ជាប់ នៃកម្មវិធីគេហទំព័រ Lingara តាម app.getlingara.com/admin។

សម័យប្រើប្រាស់ ឬក្លាយអិនត៍

កម្មវិធី Lingara ចូលគណនីឱ្យអ្នកដោយប្រើសម័យប្រើប្រាស់ ដែលមានវិសាលភាពទាំងអស់ ហើយប្រើកូតានៃគម្រោងរបស់អ្នក។ ក្លាយអិនត៍មានដែនកំណត់ចង្អៀតជាង៖ អ្នកជ្រើសរើសវិសាលភាពដែលវាត្រូវបានអនុញ្ញាតនៅពេលអ្នកបង្កើតវា ហើយថូខឹនចូលប្រើនីមួយៗដែលវាទទួលបាន មានតែវិសាលភាពដែលវាស្នើសុំប៉ុណ្ណោះ។

តម្លៃបី

ID ក្លាយអិនត៍ចាប់ផ្តើមដោយ lgr_cid_ ហើយសម្គាល់ក្លាយអិនត៍នៅចំណុចបញ្ចប់ថូខឹន។ វាមិនមែនជាសម្ងាត់ទេ។

សម្ងាត់ក្លាយអិនត៍ចាប់ផ្តើមដោយ lgr_cs_ ហើយត្រូវផ្ញើតែទៅចំណុចបញ្ចប់ថូខឹនប៉ុណ្ណោះ។ វាបង្ហាញតែម្តងគត់ នៅពេលអ្នកបង្កើតវា៖ សូមចម្លងវានៅពេលនោះ ព្រោះ Lingara រក្សាទុកតែ hash របស់វាប៉ុណ្ណោះ។

ថូខឹនចូលប្រើចាប់ផ្តើមដោយ lgr_at_ ហើយមានសុពលភាពមួយម៉ោង។ វាត្រូវដាក់ក្នុងក្បាល Authorization: Bearer នៃការហៅនៅក្រោម /v1/ ហើយមិនដាក់នៅកន្លែងផ្សេងឡើយ។ វាជាតម្លៃតែមួយគត់ដែលត្រូវនៅក្នុងក្បាលនោះ៖ សម្ងាត់ក្លាយអិនត៍ដែលផ្ញើទៅទីនោះ ត្រូវបានបដិសេធដោយ 401។

ទទួលបានថូខឹនចូលប្រើ

POST ទម្រង់មួយទៅចំណុចបញ្ចប់ថូខឹន ជាមួយ grant_type=client_credentials។ ផ្ញើ ID ក្លាយអិនត៍ និងសម្ងាត់ ដោយប្រើការផ្ទៀងផ្ទាត់ HTTP Basic ឬជាវាលទម្រង់ client_id និង client_secret ប៉ុន្តែមិនមែនទាំងពីរទេ។ scope គឺជាបញ្ជីវិសាលភាពដែលក្លាយអិនត៍ត្រូវបានអនុញ្ញាត បំបែកដោយដកឃ្លា។ បើលុបវាចោល អ្នកនឹងទទួលបានគ្រប់វិសាលភាពដែលក្លាយអិនត៍ត្រូវបានអនុញ្ញាត។ ពាក្យបញ្ជាខាងក្រោមស្នើសុំតែ usage:read ប៉ុណ្ណោះ ដែលជាវិសាលភាពដែលឧទាហរណ៍ GET /v1/usage ខាងក្រោមត្រូវការ។

curl -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=usage:read"

ការឆ្លើយតបមាន access_token, token_type (Bearer), expires_in (3600 គិតជាវិនាទី) និង scope ដែលជាវិសាលភាពដែលថូខឹនពិតជាមាន។ ការប្ដូរដែលបរាជ័យឆ្លើយតបក្នុងទម្រង់កំហុស OAuth {error, error_description} មិនមែនស្រោម {code, error} របស់ /v1/ ទេ។ សម្ងាត់ខុស ឬត្រូវបានដកហូត ឬក្លាយអិនត៍ដែលត្រូវបានលុប ត្រូវបានបដិសេធដោយ 401 និង invalid_client។ វិសាលភាពដែលក្លាយអិនត៍មិនអាចស្នើសុំបាន បដិសេធការប្ដូរទាំងមូលដោយ 400 និង invalid_scope៖ វាមិនដែលត្រូវបានបង្រួមដោយស្ងាត់ៗទេ។

ធ្វើសកម្មភាពជំនួសអ្នកប្រើ Lingara ផ្សេងទៀត

កម្មវិធីដែលធ្វើសកម្មភាពជំនួសអ្នកប្រើ Lingara ផ្សេងទៀត ប្រើការផ្តល់សិទ្ធិដោយកូដអនុញ្ញាត។ សូមបញ្ជូនកម្មវិធីរុករករបស់អ្នកប្រើទៅ URL អនុញ្ញាត ជាមួយ response_type=code, client_id, redirect_uri ដែលត្រូវគ្នាពិតប្រាកដនឹងមួយដែលអ្នកបានចុះឈ្មោះ, scope, state និង code_challenge ប្រភេទ S256។ អ្នកប្រើនឹងឃើញទំព័រយល់ព្រមរបស់ Lingara ហើយត្រឡប់មក redirect_uri របស់អ្នកវិញ ជាមួយ code, state និង iss។ សូមពិនិត្យថា state គឺជាតម្លៃដែលអ្នកបានផ្ញើ ហើយ iss គឺ https://api.getlingara.com មុនពេលអ្នកប្រើកូដនោះ។

តម្រូវឱ្យប្រើ PKCE

ក្លាយអិនត៍គ្រប់មួយប្រើ PKCE ដោយប្រើតែវិធីសាស្ត្រ S256 ប៉ុណ្ណោះ។ សូមបង្កើត code_verifier ចៃដន្យមួយ ផ្ញើតម្លៃហាស SHA-256 របស់វា ដែលបានអ៊ិនកូដជា base64url ជា code_challenge ជាមួយ code_challenge_method=S256 ហើយរក្សាទុក verifier សម្រាប់ការប្ដូរ។ សំណើដែលគ្មានវិធីសាស្ត្រ ឬប្រើ plain ត្រូវបានបដិសេធដោយ invalid_request។

ប្ដូរកូដ

ក្នុងរយៈពេល 60 វិនាទី សូម POST ទៅចំណុចបញ្ចប់ថូខឹន ជាមួយ grant_type=authorization_code, code, redirect_uri ដដែល និង code_verifier ដោយផ្ទៀងផ្ទាត់ជាក្លាយអិនត៍។ ក្លាយអិនត៍សាធារណៈផ្ញើតែ client_id ប៉ុណ្ណោះ។ ការឆ្លើយតបបន្ថែម refresh_token ដែលចាប់ផ្តើមដោយ lgr_rt_។ កូដចាប់ផ្តើមដោយ lgr_ac_ ហើយប្រើបានតែម្តង៖ ការប្រើលើកទីពីរត្រូវបានបដិសេធដោយ invalid_grant ហើយបញ្ចប់ថូខឹនដែលការប្ដូរលើកទីមួយបានចេញឱ្យ។

ធ្វើឱ្យស្រស់

នៅពេលថូខឹនចូលប្រើផុតកំណត់ សូម POST ទៅចំណុចបញ្ចប់ថូខឹន ជាមួយ grant_type=refresh_token និង refresh_token ដោយផ្ទៀងផ្ទាត់ជាក្លាយអិនត៍ម្តងទៀត។ ការធ្វើឱ្យស្រស់នីមួយៗផ្តល់ថូខឹនធ្វើឱ្យស្រស់ថ្មីមួយ៖ សូមរក្សាទុកតែថូខឹនថ្មីបំផុត។ សូមធ្វើឱ្យស្រស់ម្តងមួយៗតាមលំដាប់៖ ថូខឹនធ្វើឱ្យស្រស់ចាស់ដែលត្រូវបានប្រើលើសពី 60 វិនាទី បន្ទាប់ពីវាត្រូវបានជំនួស ត្រូវចាត់ទុកថាត្រូវបានលួច ហើយបញ្ចប់ថូខឹនរបស់ការដំឡើងនោះដោយ invalid_grant។ ថូខឹនធ្វើឱ្យស្រស់ដែលមិនបានប្រើរយៈពេល 30 ថ្ងៃនឹងផុតកំណត់។ ចំណុចបញ្ចប់ថូខឹនកំណត់ចំនួនសំណើក្នុងមួយអាសយដ្ឋាន ដូច្នេះសូមធ្វើឱ្យស្រស់តែនៅពេលថូខឹនអស់សុពលភាពប៉ុណ្ណោះ។

កម្មវិធីដើមគឺជាក្លាយអិនត៍សាធារណៈ

កម្មវិធីកុំព្យូទ័រ ទូរស័ព្ទ ឬបន្ទាត់ពាក្យបញ្ជា មិនអាចរក្សាសម្ងាត់បានទេ ដូច្នេះវាជាក្លាយអិនត៍សាធារណៈ៖ វាគ្មានសម្ងាត់ ផ្ញើតែ client_id ទៅចំណុចបញ្ចប់ថូខឹន ហើយចុះឈ្មោះការបញ្ជូនបន្ត loopback ដូចជា http://127.0.0.1/callback (ច្រកណាក៏បាន) ឬគ្រោងការណ៍ប្រើប្រាស់ឯកជនដូចជា com.example.app:/callback។ អ្នកប្រើឃើញទំព័រយល់ព្រមរាល់ពេល។ ទំព័រគេហទំព័រមិនអាចជាក្លាយអិនត៍បានទេ៖ ទាំងចំណុចបញ្ចប់ថូខឹន និង /v1/ មិនឆ្លើយតបនឹងសំណើ preflight ឆ្លងប្រភពទេ។

នៅពេលអ្នកប្រើដកកម្មវិធីរបស់អ្នកចេញ

អ្នកប្រើអាចដកកម្មវិធីរបស់អ្នកចេញនៅពេលណាក៏បាន ក្នុង កម្មវិធីដែលបានភ្ជាប់ ឬដោយលុបការដំឡើងវា ប្រសិនបើពួកគេបានដំឡើងវា ហើយការហៅបន្ទាប់របស់វាបរាជ័យដោយ 401។ នៅពេលអ្នកប្រើចាកចេញពីកម្មវិធីរបស់អ្នក សូមដកហូតថូខឹនធ្វើឱ្យស្រស់របស់វានៅចំណុចបញ្ចប់ដកហូត ដែលបញ្ចប់ថូខឹនរបស់ការដំឡើងនោះ។

នៅពេលថូខឹនផុតកំណត់

បន្ទាប់ពីមួយម៉ោង /v1/ ឆ្លើយតប 401 ជាមួយកូដ unauthorized និងកំហុសដែលចាប់ផ្តើមដោយ invalid_token។ សូមប្ដូរម្តងទៀតនៅពេលការហៅមួយទទួលបាន 401 ឬបន្តិចមុនពេល expires_in អស់ ហើយសាកល្បងការហៅម្តងទៀតមួយដង។ បើការប្ដូរខ្លួនឯងបរាជ័យដោយ invalid_client ឬ invalid_scope នោះក្លាយអិនត៍ ឬសម្ងាត់របស់វាត្រូវបានលុប ដកហូត ឬបង្រួម៖ សូមឈប់ ហើយកែវានៅលើទំព័រ ការតភ្ជាប់ ព្រោះការសាកល្បងម្តងទៀតមិនអាចជោគជ័យទេ។ សូមរក្សាថូខឹនទុករវាងការហៅ៖ ចំណុចបញ្ចប់ថូខឹនកំណត់ចំនួនការប្ដូរក្នុងមួយក្លាយអិនត៍ និងក្នុងមួយអាសយដ្ឋាន ហើយកម្មវិធីដែលប្ដូររាល់ការហៅ ត្រូវបានបដិសេធដោយ 429 និង rate_limited ក្នុងរយៈពេលមួយម៉ោង (សូមរង់ចាំតាម Retry-After)។ ការផ្តល់សិទ្ធិនេះគ្មានថូខឹនធ្វើឱ្យស្រស់ទេ៖ សម្ងាត់ត្រូវបានប្ដូរម្តងទៀត។

ថូខឹនចូលប្រើដំណើរការតែលើផ្លូវ API ប៉ុណ្ណោះ

ថូខឹនចូលប្រើដំណើរការតែលើផ្លូវនៅក្រោម /v1/ ប៉ុណ្ណោះ។ បើផ្ញើទៅផ្លូវ Lingara ផ្សេងទៀត វាត្រូវបានបដិសេធដោយ 401 ហើយខ្លឹមសារចាប់ផ្តើមដោយ api_token_not_accepted ជាអត្ថបទធម្មតា ឬនៅក្នុងវាល error មិនដែលនៅក្នុងស្រោម {code, error} ដែលផ្លូវ /v1/ ប្រើទេ។ សូមផ្ញើថូខឹនចូលប្រើនៅក្នុងក្បាល Authorization ដូចខាងក្រោម។

curl "https://api.getlingara.com/v1/usage" \
  -H "Authorization: Bearer $LINGARA_TOKEN"

វិសាលភាព

ប្រតិបត្តិការនីមួយៗត្រូវការវិសាលភាពមួយគត់ ដែលមានឈ្មោះនៅលើទំព័ររបស់វា។ ថូខឹនចូលប្រើដែលគ្មានវិសាលភាពនោះត្រូវបានបដិសេធដោយ 403 និងកូដ insufficient_scope។ ដើម្បីហៅប្រតិបត្តិការនោះ សូមស្នើសុំវិសាលភាពរបស់វានៅពេលប្ដូរ ប្រសិនបើក្លាយអិនត៍ត្រូវបានអនុញ្ញាត។ តារាងខាងក្រោមរាយវិសាលភាពនីមួយៗ និងប្រតិបត្តិការដែលវាអនុញ្ញាត។

អ្នកណាបង់ថ្លៃសម្រាប់ការហៅ

ក្លាយអិនត៍ត្រូវបានគិតថ្លៃតាមវិធីមួយក្នុងចំណោមវិធីពីរ ដែលត្រូវជ្រើសរើសនៅពេលបង្កើតវា។ ក្លាយអិនត៍ allowance ប្រើកូតារបស់ម្ចាស់វា ដែលជាកូតាដូចគ្នានឹងកម្មវិធីរបស់អ្នក ហើយថូខឹនចូលប្រើរបស់វាក៏ប្រើកូតានោះដែរ។ GET /v1/usage បង្ហាញចំនួនដែលនៅសល់។ ក្លាយអិនត៍ metered មិនប្រើកូតាទេ៖ វាត្រូវបានគិតថ្លៃតាមក្រេឌីត តាមរយៈការជាវការគិតថ្លៃតាមការប្រើប្រាស់ ដែលអ្នករៀបចំនៅលើទំព័រ ការតភ្ជាប់។ ការហៅរបស់វាត្រូវបានបដិសេធដោយ 402 និង spend_cap_reached នៅពេលក្លាយអិនត៍ ឬគណនីរបស់អ្នកដល់កម្រិតចំណាយប្រចាំខែ ហើយដោយ 402 និង metered_billing_inactive ដរាបណាការគិតថ្លៃតាមការប្រើប្រាស់មិនទាន់សកម្ម។ ផែនការមេរៀនមួយស្មើនឹង 10 ក្រេឌីត វេនសន្ទនាជាមួយគ្រូបង្រៀនមួយស្មើនឹង 1 ក្រេឌីត ហើយការបង្កើតវាក្យសព្ទមួយស្មើនឹង 3 ក្រេឌីត ដូច្នេះ units ដែល GET /v1/usage រាយការណ៍ អាចបម្លែងទៅជាក្រេឌីតតាមទម្ងន់ទាំងនេះ។ ការហៅដែលកម្មវិធីធ្វើជំនួសអ្នកប្រើផ្សេង ដោយប្រើថូខឹនពីកូដអនុញ្ញាត តែងតែប្រើកូតារបស់អ្នកប្រើនោះ មិនថារបៀបរបស់ក្លាយអិនត៍ជាអ្វីទេ។

រក្សាទុកសម្ងាត់ និងថូខឹននៅលើម៉ាស៊ីនមេ

សម្ងាត់ក្លាយអិនត៍ គួរតែនៅលើម៉ាស៊ីនមេដែលអ្នកគ្រប់គ្រង មិនដែលនៅក្នុងទំព័រគេហទំព័រ កម្មវិធីបន្ថែមរបស់កម្មវិធីរុករក ឬកញ្ចប់កម្មវិធី ដែលអ្នកណាក៏អាចអានវាបានឡើយ។ កម្មវិធីដើមគឺជាក្លាយអិនត៍សាធារណៈ ហើយមិនកាន់សម្ងាត់ទេ។ ទាំង /v1/ និងចំណុចបញ្ចប់ថូខឹន មិនឆ្លើយតបនឹងសំណើ preflight ឆ្លងប្រភពទេ ដូច្នេះកម្មវិធីរុករកនៅលើគេហទំព័រផ្សេងមិនអាចហៅវាបានទោះយ៉ាងណាក៏ដោយ។

គ្រប់គ្រងក្លាយអិនត៍

នៅលើទំព័រ ការតភ្ជាប់ តាម app.getlingara.com/admin អ្នកអាចបង្កើត ប្ដូរឈ្មោះ និងលុបក្លាយអិនត៍ ផ្លាស់ប្តូរអ្វីដែលក្លាយអិនត៍នីមួយៗអាចធ្វើបាន និងកំណែដែលវាត្រូវបានភ្ជាប់ ព្រមទាំងបង្កើត និងដកហូតសម្ងាត់របស់វា។ ការលុបក្លាយអិនត៍បញ្ឈប់ថូខឹនចូលប្រើទាំងអស់ដែលវាមានភ្លាមៗ ហើយបញ្ចប់សិទ្ធិដែលអ្នកប្រើគ្រប់រូបបានផ្តល់ឱ្យវា។ ការដកហូតសម្ងាត់បញ្ឈប់ភ្លាមៗនូវថូខឹនចូលប្រើទាំងអស់ដែលបានប្ដូរដោយសម្ងាត់នោះ។ ការបង្រួមវិសាលភាពរបស់ក្លាយអិនត៍ក៏មានប្រសិទ្ធភាពភ្លាមៗដែរ៖ ការពង្រីកវា ឬការផ្លាស់ប្តូរកំណែរបស់វា មានប្រសិទ្ធភាពចាប់ពីការប្ដូរបន្ទាប់។

ប្ដូរសម្ងាត់ថ្មី

ក្លាយអិនត៍មួយអាចមានសម្ងាត់ពីរក្នុងពេលតែមួយ។ ដើម្បីប្ដូរ សូមបង្កើតសម្ងាត់ថ្មី ដាក់ឱ្យប្រើ ហើយដកហូតសម្ងាត់ចាស់ នៅពេលកាលបរិច្ឆេទ ប្រើចុងក្រោយ របស់វានៅលើទំព័រ ការតភ្ជាប់ ឈប់ផ្លាស់ប្តូរ។ ដំណើរការដែលមានសម្ងាត់ថ្មីរួចហើយ ប៉ុន្តែនៅតែកាន់ថូខឹនពីសម្ងាត់ចាស់ នឹងទទួលបាន 401 មួយដង ហើយប្ដូរម្តងទៀត។ សម្ងាត់តែមួយគត់របស់ក្លាយអិនត៍មិនអាចដកហូតបានទេ៖ សូមបង្កើតសម្ងាត់ជំនួសជាមុន ឬលុបក្លាយអិនត៍។

ប្រសិនបើការបកប្រែ និងឯកសារយោងជាភាសាអង់គ្លេសខុសគ្នា ឯកសារយោងជាភាសាអង់គ្លេសគឺជាឯកសារដែលត្រឹមត្រូវ។