Odoo JSON-2 API: kalit, soʻrov, javob va tranzaksiya qoidasi

Internet-doʻkon buyurtmani Odoo ga yozishi kerak, hisobot dasturi esa har kecha hisob-fakturalarni oʻqib olishi kerak. Ikkalasi ham Odoo ning oynasidan emas, tashqaridan, dastur orqali kiradi, shuning uchun ularga odam uchun moʻljallangan ekran emas, mashina tushunadigan kirish yoʻli kerak. Odoo 19.0 dan beri buning rasmiy yoʻli bor: JSON-2 API. Hujjat gʻoyani shunday ochadi: Odoo odatda ichkaridan, modullar bilan kengaytiriladi, ammo uning maʼlumotlari va koʻpgina imkoniyatlari tashqi dasturlar uchun ham ochiq.

Bitta soʻrov, bitta metod

Gʻoya oddiy. Dastur bitta manzilga POST soʻrovi yuboradi, manzilning oʻzi esa ikki qismdan iborat: model va metod. Model — Odoo dagi jadvalning texnik nomi, masalan kontaktlar yoki sotuv buyurtmalari, metod esa shu jadval ustida bajariladigan amal: qidirish, oʻqish, yaratish, yozish yoki buyurtmani tasdiqlash kabi tayyor biznes amali. Soʻrovning tanasida esa amal parametrlari JSON obyekti koʻrinishida joʻnatiladi, javob ham xuddi shu formatda qaytadi.

Bitta qoida koʻpincha eʼtibordan chetda qoladi: parametrlar faqat nomi bilan beriladi, eski usullardagi kabi oʻrniga qarab, yaʼni nomsiz yuboriladigan parametr JSON-2 da umuman yoʻq. Mavjud modellar, maydonlar va metodlar har bir bazada boshqacha boʻlishi mumkin, chunki bazaga oʻrnatilgan ilovalar har xil. Ularning toʻliq roʻyxatini bazaning oʻzidagi /doc sahifasidan koʻrish mumkin.

Misol uchun, dastur nomida «deco» soʻzi bor kompaniyalarni qidirmoqchi boʻlsa, u qidirish va oʻqishni birlashtirgan metodni chaqiradi, tanaga filtrni hamda kerakli maydon nomini yozadi, kontekstda esa tilni koʻrsatadi. Javobda mos yozuvlar roʻyxati keladi. Hujjatdagi namunada bunday soʻrovga bitta yozuv qaytadi: Deco Addict nomli kompaniya.

Authorization sarlavhasi OAuth 2.0 ning umumiy qoidasiga tayanadi: «Bearer» soʻzi, boʻshliq, soʻng token. Bu qoida 2012-yil oktabrda RFC 6750 sifatida eʼlon qilingan. Odoo ning oʻz kodi bu soʻzni katta yoki kichik harfda yozilganidan qatʼi nazar qabul qiladi.

API kalit: parol oʻrniga uzun maxfiy qator

Kalit foydalanuvchi nomidan ishlaydi. Uni foydalanuvchi oʻz sozlamalaridagi xavfsizlik boʻlimida, yangi kalit tugmasi bilan yaratadi. Odoo ikki narsani soʻraydi: tavsif va amal qilish muddati. Tavsif keyinroq kalit hali ishlatilayotganini yoki uni xavfsiz oʻchirib yuborsa boʻlishini aniqlashga yordam beradi, shuning uchun unga integratsiya nomini yozgan maʼqul. Muddat tugagach kalit oʻzi yaroqsiz boʻladi.

• Kalit 160 bitli tasodifiy qiymat; ekranda faqat bir marta koʻrinadi, keyin uni qayta olib boʻlmaydi.
• Muddat uch oydan oshmaydi; uzoq ishlaydigan kalit kamida har uch oyda almashtiriladi.
• Qoʻlda, tajriba uchun ishlatiladigan kalitga odatda bir kun yetarli deyiladi.
• Yoʻqolgan yoki sizib chiqqan kalit darhol oʻchiriladi, oʻrniga yangisi yaratiladi.

Kalitni tugma bilan qoʻlda yaratish yagona yoʻl emas: dastur ham kalit yarata va bekor qila oladi, bu uzoq muddatli ulanishlarni almashtirib turishda qulay. Sukut boʻyicha bu huquq faqat sozlamalar maʼmuriga beriladi, boshqa foydalanuvchilar uchun esa maxsus tizim parametrini yoqish kerak. Bir foydalanuvchi dastur orqali koʻpi bilan 10 ta kalit yaratadi, limitdan oshsa server 422 holatini qaytaradi. Bekor qilishda kalit haqiqiy boʻlsa, u shu zahoti ishlamay qoladi. Aks holda server 403 holatini beradi.

Bir tafsilot almashtirishni osonlashtiradi: bekor qilinayotgan kalit bilan sarlavhadagi kalit bir xil boʻlishi shart emas, shuning uchun eskisini yangisi bilan bekor qilish mumkin. Hujjat tartibni shunday beradi:

1. Yangi kalitni eskisini bekor qilishdan oldin yarating.
2. Yangisini xavfsiz joyda saqlang va ishga tushirishdan oldin tekshiring.
3. Hamma xizmat yangi kalitga oʻtganini aniqlang.
4. Faqat shundan keyin eskisini bekor qiling.

Maxfiy qiymatlarni muntazam almashtirish va faqat eng zarur huquqni berish — keng tarqalgan xavfsizlik qoidasi. Odoo hujjati bu borada OWASP ning maxfiy qiymatlar qoʻllanmasiga havola qiladi, u ham aynan shu ikki tamoyilni tavsiya etadi. Demak, kalitga paroldek munosabatda boʻlish kerak: uni dastur kodiga yozib qoʻymang, elektron xatda yubormang va umumiy jamoa chatida ulashmang, chunki kalit kimning qoʻliga tushsa, oʻsha odam foydalanuvchi nomidan ishlay oladi.

Kalit foydalanuvchidan ortiq narsa qila olmaydi

JSON-2 Odoo ning oddiy xavfsizlik qoidalaridan chetga chiqmaydi. Har amal foydalanuvchining kirish huquqlariga, yozuv qoidalariga va maydon ruxsatlariga qarshi tekshiriladi. Bir martalik skript yoki tajriba uchun oʻz hisobingiz yetadi, doimiy ulanish uchun esa alohida bot foydalanuvchi ochish tavsiya etiladi. Hujjat buning uchta sababini keltiradi:

• Botga faqat eng zarur huquq beriladi, kalit sizib chiqsa zarar kichik boʻladi.
• Botning parolini boʻsh qoldirish mumkin, shunda login va parol bilan kirib boʻlmaydi.
• Oʻzgarish tarixida muallif sifatida bot koʻrinadi, biror xodim emas.

Odoo ning foydalanuvchi huquqlari hujjati ham shu yoʻnalishda: ruxsat faqat kerak boʻlgan odamga beriladi, aks holda ortiqcha odam yozuvni oʻzgartirib yoki oʻchirib qoʻyishi mumkin. Bot uchun ham shu mantiq amal qiladi, faqat uning ortida odam oʻrniga dastur turadi.

Qaysi bazaga: Host va X-Odoo-Database

Bir server bir nechta bazani saqlashi mumkin. Shunda dastur qaysi bazani nazarda tutayotganini aytishi kerak. Buning uchun X-Odoo-Database sarlavhasi bor. Hujjatga koʻra, u server bir nechta bazani saqlasa va baza nomi domen nomidan aniqlanmasa majburiy boʻladi. Host sarlavhasi esa bir serverda boshqa veb-ilovalar ham ishlasa, soʻrovni toʻgʻri joyga, yaʼni Odoo ga yoʻnaltirish uchun kerak. Koʻpchilik kutubxona uni manzildan oʻzi qoʻyadi, shuning uchun dasturchining oʻzi qoʻshishi kerak boʻladigan sarlavha koʻpincha faqat baza sarlavhasi, u ham server bir nechta bazani saqlagandagina.

Javob va xato obyekti

Muvaffaqiyatli soʻrovga server 200 holatini va metod qaytargan qiymatni JSON koʻrinishida beradi. Xato boʻlsa, 4xx yoki 5xx holati bilan birga xato obyekti keladi. Unda beshta maydon bor.

Holat raqami xatoning turini darrov koʻrsatadi. Hujjatdan va Odoo kodidan olingan holatlar quyidagi jadvalda.

Hujjatdagi namuna notoʻgʻri kalit haqida: server 401 holati va «Invalid apikey» xabarini qaytaradi. Odoo kodida ham shunday: kalit tekshiruvdan oʻtmasa, 401 koʻtariladi, kutilmagan istisnoda esa 500 beriladi. Debug maydonida server ichidagi fayl yoʻllari ham koʻrinadi. Shu sababli xato obyektini butunligicha tashqi foydalanuvchiga oʻtkazmaslik maʼqul, ichki jurnalga esa toʻliq yozib qoʻyish foydali. Bu tahririyat fikri, hujjatda bunday koʻrsatma yoʻq.

Har chaqiriq alohida tranzaksiya

Eng koʻp xato shu yerda qilinadi. Tranzaksiya — bazada «yo hammasi, yo hech narsa» qoidasi bilan bajariladigan ish birligi. JSON-2 da har chaqiriq oʻz tranzaksiyasida ishlaydi: muvaffaqiyatli tugasa natija saqlanadi, xato chiqsa hammasi bekor qilinadi. Bir nechta chaqiriqni bitta tranzaksiyaga ulab boʻlmaydi, demak, ikki chaqiriq orasida bazani boshqa jarayon oʻzgartirib ulgurishi mumkin. Bunday xatoni topish qiyin: har bir soʻrov alohida qaralganda toʻgʻri ishlaydi, nosozlik esa faqat ikki soʻrov orasidagi boʻshliqda, boshqa jarayon aralashganda paydo boʻladi.

Gipotetik misol. Integratsiya avval ombordagi qoldiqni oʻqiydi va 5 dona borligini koʻradi, keyin 4 donani band qilish uchun ikkinchi chaqiriq yuboradi. Oraliqda esa boshqa operator 3 donani joʻnatib yuborgan boʻlsin. Ikkinchi chaqiriq eskirgan raqamga tayanib ishlaydi, natijada band qilingan miqdor omborda aslida yoʻq. Hujjat aynan shunday xavfni rezervatsiya va toʻlov amallarida alohida taʼkidlaydi.

Yechim aniq: bogʻliq amallarni bitta metod ichida bajarish kerak, shunda yo hammasi bajariladi, yo hech biri va oraliq holat qolmaydi. Biznes modellarida bunday metodlar koʻpincha tayyor turadi. Masalan, sotuv buyurtmasini tasdiqlash metodi avval buyurtmaning yaroqliligini tekshiradi, soʻng uni tasdiqlaydi. Mos metod yoʻq boʻlsa, uni alohida modulda yozish mumkin. Bu yoʻl dasturchi talab qiladi, lekin bogʻliq amallar uchun hujjat boshqa yechim bermaydi.

Qidirish va oʻqishni birlashtirgan metod bu qoidaning kichik namunasi. Ikkala amal bir tranzaksiyada bajarilgani uchun, qidirish bilan oʻqish orasida boshqa jarayon yozuvni oʻchirib yuborsa ham, xato chiqmaydi. Ikki alohida chaqiriqda esa oʻqish «yozuv topilmadi» xatosi bilan tugashi mumkin. Hujjatning oʻz kod namunasi ikki chaqiriqdan iborat va uni ikkita alohida tranzaksiya deb izohlaydi.

Pastki qatlamda nima boʻladi? Odoo serveri bazaga «Repeatable Read» deb ataladigan izolyatsiya darajasida ulanadi, yaʼni bir vaqtda ishlayotgan tranzaksiyalar bir-birini qanchalik koʻrishini aniqlovchi qoida bilan. Bu darajada tranzaksiya oʻz boshlanishidagi holat suratini koʻradi va boshqalarning keyin saqlagan oʻzgarishlarini koʻrmaydi. Ikki tranzaksiya bir yozuvni oʻzgartirmoqchi boʻlsa, ikkinchisi «could not serialize access» xatosi bilan toʻxtaydi va butun tranzaksiyani qaytadan boshlash kerak boʻladi. Bunday xatoda Odoo serveri amalni oʻzi, koʻpi bilan besh urinishgacha takrorlaydi. Tashqi dastur ham shunday xatoga tayyor turishi kerak.

Chegara: API hamma obuna rejasida ochiq emas

Sahifaning boshida ogohlantirish turadi: tashqi API ga kirish faqat «Custom» deb ataladigan obuna rejasida mavjud, «One App Free» va «Standard» rejalarida esa yoʻq. Xuddi shu ogohlantirish 19.0 hujjatida ham bor. Demak, texnik jihatdan hammasi tayyor boʻlsa ham, integratsiya loyihasi obuna shartiga urilib toʻxtashi mumkin. Boshlashdan oldin shartni hujjat bilan, keyin oʻz shartnomangiz bilan solishtiring. Reja shartlari oʻzgarib turadi, shuning uchun yakuniy javob Odoo ning hozirgi sahifasida va shartnomada turadi.

Amalda nima qilish mumkin

Hujjatdan chiqarilgan amaliy qadamlar, tahririyat fikri sifatida:

• Har ulanish uchun alohida bot foydalanuvchi va alohida kalit oching, kalit tavsifiga integratsiya nomini yozing.
• Kalitga yetarli boʻlgan eng qisqa muddat bering va almashtirish sanasini jamoa taqvimiga oldindan yozib qoʻying, chunki muddati oʻtgan kalit integratsiyani kutilmaganda toʻxtatadi.
• Bogʻliq amallarni bitta metodga yigʻing va ikki chaqiriq orasida baza holati oʻzgarib ketishi mumkinligini hamisha hisobga oling.
• Xato obyektining name va message maydonini jurnalga yozing, debug maydonini esa tashqariga bermang.
• Loyihaga kirishishdan oldin obuna rejasida API borligini tekshiring, soʻng bazaning /doc sahifasida kerakli model hamda metodlarni koʻrib chiqing.