Mis on identsuspäring (idempotency)? Mikski raamatupidamis- ja makseliidesed seda vajavad

Tegevus on idempotentne ehk iseseisev (idempotent), kui selle kahekordsel tegemisel on sama mõju mis ühekordsel. Kirje lugemine on olemuselt idempotentne. Arve koostamine ei ole seda – kutsuge seda kaks päringut ja teil on kaks arvet, kaks nõuet ning klient, kes küsib, miks talle esitati topeltarve.

See lünk on oluline, sest võrgud tõrguvad kindlal ja ebameeldival viisil: päring õnnestub ja vastus läheb kaduma. Klient näeb ajapiiri ületust (timeout) ega suuda eristada, kas päring ei jõudnudki pärale või jõudis, töötles, kuid vastus kadus teel. Tema ainus turvalise näivusega valik on seda korrata ja just kordus on see, mis tekitab duplikaadi.

Miks raamatupidamine asja hullemaks teeb

Enamikus süsteemides on duplikaat tüütu pisiasi. Pearaamatus on see süvenev probleem:

• Topeltarve kulutab numbri lünkadeta jadast (gapless sequence), nii et selle kustutamine ei tule kõne alla – muutumatus tähendab, et parandamiseks on vaja kreeditarvet, mida teie klient näeb.
• Duplikaat kirjendab kandeid, nii et tulu, käibemaks ja nõuded on üle arvestatud, kuni keegi seda märkab.
• See jõuab käibemaksudeklaratsiooni ja Leedus i.SAF-i registritesse.
• Kui see vallandas makse, liikus raha tegelikult ära.

Ei toimi ka lihtsalt "kontrolli duplikaate", sest kaks täiesti eraldiseisvat arvet samale kliendile samale summale samal päeval on täiesti tavapärased. Süsteem ei saa sisu põhjal tahet tuletada – klient peab selle ise esitama.

Kuidas identsuspäringu võtmed töötavad

Klient genereerib iga loogilise tegevuse kohta unikaalse võtme ja saadab selle koos päringuga:

POST /v1/sales/invoices/create
Idempotency-Key: 8f14e45f-ea1b-4c2b-9f3a-2d7c1e0b5a91

Seejärel tagab server järgmise:

1. Esimene selle võtmega päring – töötleb tavapäraselt, salvestab tulemuse võtme juurde.
2. Kordus sama võtme ja sama sisuga (payload) – ei käivita uuesti, vaid tagastab salvestatud vastuse.
3. Sama võti, teistsugune sisu – lükkab tagasi. Võti on väide, et tegemist on sama tegevusega; teistsugune keha tähendab, et see ei ole nii, ja vana tulemuse vaikne tagastamine oleks halvem kui veateade.
4. Kordus ajal, mil algne päring alles töötab – lükkab tagasi korduva veaga, selle asemel et käivitada samaaegselt.

Neljas punkt on see, mida naiivsed rakendused kipuvad kahe silma vahele jätma. Klient, kelle päring aegub 5 sekundi möödudes ja kes teeb korduse 6. sekundil, satub kokkupõrkesse omaenda parajasti töös oleva päringuga; ilma samaaegsuse kaitseta lähevad mõlemad läbi ja saateki duplikaadi, mille vältimiseks see mehhanism loodigi.

Võtmete õige genereerimine

Võti peab tuvastama tegevuse, mitte katse:

• Õige: UUID, mis genereeritakse üks kord, kui kasutaja klõpsab nuppu "koosta arve", ja mida taaskasutatakse selle klõpsu igal katsel.
• Õige: teie enda domeenist tuletatud deterministlik võti – order-1041-invoice.
• Vale: uus UUID iga HTTP katse kohta. Iga kordus saab uue võtme, nii et iga kordus on uus tegevus ja te ei ole midagi rakendanud.
• Vale: sisu räsi (hash). Kaksi õiguspäraselt identset toimingut satuvad siis konflikti ja teine neelatakse vaikides alla.

Võtmed vajavad säilitusperioodi – piisavalt pikka, et katta realistlikud kordusvahemikud ja kliendi katkestused, kuid mitte igavesti.

Mida see ei lahenda

Identsuspäring kaitseb sama päringu topeltkäivitamise eest. See ei kaitse järgmise eest:

• Kaks erinevat kasutajat loovad erinevatest sessioonidest sama arve – see on ärireegli probleem, mis lahendatakse unikaalsuse piirangutega, näiteks üks arve tellimuse kohta.
• Loogilised duplikaadid erinevate võtmetega.
• Determinismi puudumine tegevuse sees – kui töötleja genereerib ajatempli või numbri, salvestab salvestatud vastus esimese, mis on soovitud käitumine, kuid mida tasub mõista.

See täiendab andmebaasi piiranguid, mitte ei asenda neid. Nordleti pearaamat kasutab mõlemat: identsuspäringu võtmed peatavad korduvad päringud, samas kui unikaalsed indeksid peatavad topeltarveldamise partiid väljamakse ID kohta, topeltostuarved tarnija ja dokumendi numbri järgi ning topeltamortisatsiooni jooksud vara ja perioodi kaupa.

Kuidas Nordlet seda rakendab

Saatke päis Idempotency-Key mis tahes olekut muutuva päringu korral – see peab olema mittetühi string, mille pikkus on maksimaalselt 255 tähemärki.

Esimene antud võtmega päring käivitatakse ja selle tulemus salvestatakse. Kordus sama võtme ja sama sisuga tagastab salvestatud vastuse uuesti käivitamata, nii et arve luuakse täpselt üks kord, olenemata sellest, mitu korrad päringut korratakse.

Kaks tõrkeolekut on vaikimise asemel selgesõnalised:

• Sama võti, teistsugune sisu → lükatakse tagasi: "Idempotency-Key was already used with a different request payload." See püüab kinni ohtliku olukorra, kus klient taaskasutab võtit ja muudab samal ajal summat.
• Sama võti, algne päring alles töötab → lükatakse tagasi korduva veana: "A request with this Idempotency-Key is still being processed, retry shortly." Topeltkäivitamist samaaegselt ei toimu.

Võtmed on ettevõttepõhised, nii et kaks rentnikku, kes genereerivad sama UUID, ei satu kunagi konflikti.

Täiendav tagatis toimib teises suunas. Veebikonksude (webhook) edastamine toimib põhimõttel vähemalt kord (at-least-once), mis tähendab, et teie liides saab aeg-ajalt sama sündmuse kaks korda – pärast ajalimiidi ületust, mil edastus tegelikult õnnestus, või uuesti edastamisel. Iga sündmus sisaldab ID-d ja teie töötleja peaks salvestama töödeldud ID-d ja eirama kordusi. Identsuspäring on omadus, mida integratsiooni mõlemad pooled vajavad; API tavade juhend käsitleb päringupoolt üksikasjalikult.

FAQ

Mis on identsuspäringu võti (idempotency key)?

Kliendi genereeritud tunnustega päring, mis saadetakse koos päringuga ja mis võimaldab serveril ära tunda sama loogilise toimingu kordust. Esimene päring käivitatakse; sama võtmega kordused tagastavad salvestatud tulemuse uuesti käivitamise asemel.

Miks vajavad raamatupidamisliidesed identsuspäringuid?

Kuna dubleeritud kirje loob reaalse dokumendi reaalsete tagajärgedega – teine arve kulutab järjestikuse numbri, postitab pearaamatusse ja jõuab käibemaksudeklaratsiooni. Erinevalt dubleeritud lugemisest ei saa seda lihtsalt kustutada; seda tuleb parandada kreeditarvega.

Kas ma peaks igale kordusele looma uue võtme?

Ei – see nullib mehhanismi täielikult. Genereerige üks võti loogilise toimingu kohta ja taaskasutage seda selle toimingu igal katsel. Uus võti iga katse kohta tähendab, et igat katset käsitletakse uue toiminguna.

Mis juhtub, kui ma kasutan võtit uuesti teise sisuga?

Päring lükatakse tagasi. Võti kinnitab, et tegemist on sama toiminguga, seega tähendab muudetud keha, et midagi on valesti – tõenäoliselt on tegemist võtme taaskasutamise veaga kliendi poolel. Varasema tulemuse vaikne tagastamine oleks halvem.

Kas identsuspäring hoiab ära kõik duplikaadid?

Ei. See hoiab ära sama päringu topeltkäivitamise. Kaks erinevat kasutajat, kes loovad iseseisvalt sama arve, on teinud kaks erinevat päringut, mis on unikaalsuse piirangute ärireegli probleem, mitte midagi sellist, mida identsuspäringu võti näeks.