Idempotentse partneri API automatiseerimine: tehisintellekti klientide, võtmete ja krediitide pakkumine ilma dubleerivate kõrvalmõjudeta

Registreeruv töötaja loob kliendirühma, HTTP-päring aegub ja tööülesanne proovib uue päringuga uuesti. Nüüd võib samal kliendil olla kaks rühma, kaks API-võtit või kohalik andmebaasikirje, mis osutab valele ülesvooluobjektile. Makse veebihaagi saabub minut hiljem, see toimetatakse kohale kaks korda ja krediteerib klienti kaks korda, kuna veebihaagi töötleja käsitleb iga tarnet uue ärisündmusena.

See on Partner API automatiseerimise tõeline rikkerežiim. Esimene edukas kõne on harva raske osa. Raske osa on äriliste kavatsuste säilitamine, kui võrgud ebaõnnestuvad, töötajad jooksevad kokku, kasutajad topeltklõpsavad, makseteenuse pakkujad proovivad uuesti veebihaake ja finantsandmeid tuleb hiljem siiski kooskõlastada.

Praktiline muster on lihtne: käsitlege iga muutuvat Partner API toimingut kui püsivat äritoimingut, mitte kui tulekahju ja unusta HTTP-päringut. See tähendab kohalike toimingute kirjete salvestamist, idempotentsusvõtmete tahtlikku kasutamist, raha täpset sõelumist, veebihaagide asünkroonset töötlemist ja tundmatute tulemuste kooskõlastamist enne kompenseerivate muudatuste tegemist.

Eri faktid, soovitused ja ennustused

Faktid

Model Gate'i Partner API dokumentatsioonis öeldakse, et POST, PATCH ja DELETE päringud nõuavad Idempotency-Key, mis pärast ajalõppude uuesti proovimist peaks kasutama sama võtit ja idempotentsuse kirjeid säilitatakse 7 päeva.

Sama dokumentatsiooni kohaselt on rahalised väärtused ja piirangud JSON-i kümnendstringid. Neid tuleks käsitleda täpsete kümnendväärtuste või stringidena, mitte teisendada binaarsete ujukomatüüpidega.

Partner API avab haldus- ja aruandluspinnad saldo, auditisündmuste, rühmade, võtmete, päringute ja tehingute jaoks. Auditisündmused registreerivad edukad haldusmutatsioonid selliste väljadega nagu päringu ID, toiming, sihtmärk, allika IP, olek, turvalised metaandmed ja UTC ajatempel.

Triipdokumentide idempotentsusvõtmed on viis, kuidas toiminguid ohutult uuesti proovida. Selle veebihaagi juhised hoiatavad ka, et lõpp-punktid võivad sama sündmuse vastu võtta mitu korda, ning soovitab töödeldud sündmuste ID-d logida ja asünkroonselt töödelda.

AWS ja Azure'i juhised tugevdavad sama hajutatud süsteemide reeglit: korduskatsed on kasulikud, kuid mutatsioonitoimingud vajavad helistaja esitatud päringu identifikaatorit või samaväärset korratavuse lepingut, et server saaks helistaja kavatsusi säilitada.

Soovitused

Kasutage ettevõtmiseks, võtmete loomiseks, kululimiidi muutmiseks, krediidi täiendamiseks, rahakoti kontrollimiseks ja veebihaagipõhiseks täitmiseks ühte kohalikku toimingute pearaamatut. Muutke pearaamat integratsiooni püsivaks tõeallikaks kavatsuste, katsete, ülesvoolu päringu ID-de, saadud sihtmärgi ID-de ja kooskõlastusoleku kohta.

Looge idempotentsusvõtmed stabiilsest äriplaanist, kui kavatsus on stabiilne. Kasutage sama võtit uuesti pärast ajalõpu või teadmata serveri tulemust. Looge uus võti ainult siis, kui äritegevus on tahtlikult uus.

Töötlege veebihaake kahes etapis: kinnitage ja säilitage kiiresti sündmuse identiteet, seejärel viige äritegevus asünkroonselt läbi idempotentse töötaja.

Ennustused

Kuna üha enam agentuure ja SaaS-i platvorme müüb AI-juurdepääsu edasi, liiguvad tugiprobleemid API-liidese põhiühenduvuse asemel vastavusse: klientide dubleerimine, vaidlustatud krediidid, rahakoti saldod ja ebaselged kontrolljäljed. Integratsioone, mis hoiavad püsivaid kohalikke toimingute kirjeid, on lihtsam toetada kui integratsioone, mis tuginevad ainult HTTP vastustele ja logidele.

Koostage kohaliku partneri tegevusreskontra

Toimingu pearaamat salvestab äritoimingu enne esimese Partner API päringu saatmist. See peaks olema lisamissõbralik, kliendi poolt päringuid võimaldav ja piisavalt range, et kaks töötajat ei saaks samaaegselt teha sama toimingut.

Kasulik skeem näeb välja selline:

partner_operatsioonid
- operatsiooni_id // sisemine UUID
- external_customer_id // teie kliendi, rentniku või konto ID
- toiming // loo_rühm, loo_võti, määra_limiit, krediidi_üleminek
- idempotency_key // saadeti partneri API-le mutatsioonitaotluste jaoks
- request_fingerprint // meetodi, tee ja tähendusliku keha kanooniline räsi
- model_gate_request_id // X-Request-ID või samaväärne vastuse identifikaator, kui see on saadaval
- sihtmärk_avalik_id // rühma ID, võtme ID, tehingu ID või muu tulemuseks olev objekt
- olek // ootel, õnnestunud, ebaõnnestunud_retryable, ebaõnnestunud_lõplik, kooskõlastamine
- katsete_arv
- viimane_vea_kood
- viimane_veateade
- loodud_at
- uuendatud_at
- lukustatud_kuni

Oluliseks piiranguks on ainulaadsus ärilistel eesmärkidel. Näiteks external_customer_id + action + signup_version võib esmase ettevalmistamise jaoks olla kordumatu. Teine tahtlik lisamine ei tohiks esimesega kokku puutuda; sellel peaks olema erinev operatsiooni identiteet ja idempotentsuse võti.

Registreerumisvoo jaoks looge üks ülemtoiming, näiteks provision_customer, seejärel jälgige alamtoiminguid jaoks create_group, create_key ja set_initial_limit. See võimaldab kasutajaliidesel näidata ühte kliendile suunatud olekut, samas kui taustaprogramm jääb täpselt kindlaks, milline väline mutatsioon on kinni jäänud.

Idempotentsusvõtmete loomine ärikavatsusest

Idempotentsuse võtmed peaksid olema piisavalt stabiilsed, et vastu pidada korduskatsetele, ja piisavalt spetsiifilised, et vältida kahe erineva toimingu kokkuvarisemist. Deterministlik vorming aitab tugi- ja lepitusmeeskondadel süsteemi üle arutleda.

create-group-for-customer:{customer_id}:{signup_version}
create-key-for-customer:{customer_id}:{group_id}:{key_purpose}:{version}
set-spend-limit:{customer_id}:{group_id}:{limit_policy_version}
täiendamine:{kliendi_id}:{makse_sündmuse_id}:{pearaamatu_kande_id}

Kasutage sama idempotentsusklahvi, kui toiming on sama ja eelmine tulemus on teadmata. Näited hõlmavad kliendi ajalõppu, ühenduse lähtestamist pärast päringu keha saatmist, töötaja kokkujooksmist enne vastuse salvestamist või 5xx-i, kus server võib mutatsiooni juba lõpule viia.

Kasutage uut idempotentsusvõtit, kui ärieesmärk muutub. Klient, kes ostab teise krediidipaketi, on uus lisamakse. Administraator, kes tõstab kululimiiti 100,00-lt 250,00-le pärast eraldi heakskiitu, on uus toiming. Parandatud registreerumismall võib vajada ka võtmes uut versiooni, kui päringu sisu muutub oluliselt.

Salvestage päringu sõrmejälg võtme kõrvale. Kui teie kood üritab sama idempotentsusvõtit teistsuguse kasuliku koormusega uuesti kasutada, ebaõnnestub see enne Partner API kutsumist kohapeal. See kontroll tuvastab peened vead mallide migreerimise ja osaliste korduskatsete ajal.

Klientide pakkumine olekumasinana

Ettevõtte töötaja peaks liikuma selgesõnalistes olekutes edasi, selle asemel, et eeldada, et üks tehing võib hõlmata teie andmebaasi, Partner API-t ja järgnevaid arveldussüsteeme.

peotel_loomise_grupp
  - luua kohaliku operatsiooni kirje
  - saatke grupi loomise taotlus Idempotency-Key abil
  - poe päringu ID ja grupi avalik ID

group_created_key_pending
  - luua võtmetoimingute kirje
  - saatke võtme loomise taotlus Idempotency-Key abil
  - salvestage võtme metaandmed ja saladus vastavalt oma turvapoliitikale

key_created_limit_pending
  - luua kululimiidi operatsiooni kirje
  - saatke limiidi värskendus Idempotency-Key abil
  - salvestage saadud poliitika versioon või siht-ID

ette nähtud
  - märkige klient valmis
  - väljastada siseauditi sündmus
  - teavitama tootesüsteeme

See olekumasin muudab õnnetused üleelatavaks. Kui töötaja sureb pärast grupi loomist, kuid enne võtme salvestamist, saab asendustöötaja toimingu pearaamatut kontrollida, sama idempotentsusvõtit uuesti kasutada ja jätkata. Kui rühm on olemas ülesvoolu, kuid kohalik salvestamine ebaõnnestus, saab vastavusse viimine leida sihtmärgi rühma, võtme, tehingu ja auditi pindade kaudu, selle asemel et luua pimesi uut objekti.

Raha käsitlemine kümnendandmetena

Krediidid, rahakoti saldod, kululimiidid, kasutuskogused ja tehingusummad ei tohiks läbida binaarseid ujukomatüüpe. Väärtus, näiteks 0,10, on finantsväärtus, mitte mõõtmine. Salvestage algne JSON-i kümnendstring sisestuspiirile ja teisendage aritmeetika jaoks ainult täpseks kümnendkohatüübiks.

Ärge kirjutage JavaScriptis arveldusloogikat numbri ümber. Kasutage kümnendteeki või hoidke väärtusi stringidena, kuni need jõuavad spetsiaalsesse rahamoodulisse. Pythonis kasutage stringide, mitte ujukite Decimal-i. Kasutage andmebaasides fikseeritud skaala arvulisi veerge, kus on nõutav aritmeetika, ja tekstiveerge, kus täpse ülesvoolu esituse säilitamine on auditi jaoks kasulik.

// Halb: binaarne ujukomakonversioon
const limiit = Number(apiResponse.spend_limit);

// Parem: täpne kümnendkoha piir
const limit = new Decimal(apiResponse.spend_limit);

Rakendage võrdlustele sama reeglit. Kululimiidi kontroll, mis ümardab ühe poole sentideni ja teise poole pakkuja täpsuse järgi, võib päringuid valesti blokeerida või lubada. Määrake üks sisemine täpsuspoliitika, dokumenteerige see ja testige nulli ümber olevaid piirväärtusi, minimaalseid lisasummasid ja üleminekuid.

Muutke veebihaagi sisestamine igavaks

Veebihaagi töötlejad ei tohiks teostada keerulist sisseehitamist. Käsitleja ülesanne on sündmus autentida, säilitada selle identiteet ja kiiresti tagasi pöörduda. Täitmine kuulub töötajale, kes saab turvaliselt uuesti proovida.

payment_webhook_events
- pakkuja
- sündmuse_id
- sündmuse_tüüp
- saadud_kell
- kasulik koormus_räsi
- töötlemise_olek
- seotud_kliendi_id
- seotud_toimingu_id
- viimane_viga

Määrake pakkuja + sündmuse_id kordumatu piirang. Kui sama sündmus saabub kaks korda, tagastage edu pärast seda, kui olete kinnitanud, et see on juba salvestatud või töödeldud. Ärge krediteerige rahakotti kaks korda, sest kohaletoimetamine toimus kaks korda.

Täitmise töötaja peaks looma või leidma vastava toimingu top_up_credit. Selle idempotentsusvõti võib sisaldada maksesündmuse ID-d ja teie sisemise pearaamatu kirje ID-d. Kui töötaja jookseb kokku pärast Partner API täiendamise õnnestumist, kuid enne kohaliku oleku värskendamist, kasutab järgmine katse sama võtit uuesti ja seejärel kooskõlastab saadud tehingu.

Proovige uuesti partneri API-kutsete muteerumise reeglid

Korduskatsed vajavad reegleid. Ilma nendeta muutub uuesti proovimise kood duplikaadi kõrvalmõjude generaatoriks.

Võrgu ajalõppude, ühenduse lähtestamise ja tundmatute 5xx tulemuste korral proovige dokumenteeritud säilitusaknas sama taotlust uuesti sama Idempotency-Key abil. Registreerige iga katse toimingu pearaamatusse.

429 vastuse puhul järgige Retry-After, kui see on antud, ja säilitage sama toimingu jaoks sama idempotentsusvõti. Hindade piiramine ei muuda ärilist eesmärki.

Valideerimisvigade korral ärge proovige automaatselt uuesti. Märkige toiming nurjunuks, selgitage välja konkreetne viga ja nõudke parandatud toiming uue päringu sõrmejäljega, kui kavandatud kasulik koormus muutub.

Muutunud kasuliku koormuse põhjustatud idempotentsusvõtme konflikti korral peatuge. See on kohalik viga või ebaturvaline korduskatse. Ärge looge uut võtit automaatselt, välja arvatud juhul, kui äritegevus on selgesõnaliselt uus ja töövooga heaks kiidetud.

Leppige tundmatud tulemused enne hüvitamist

Pärast teadmata tulemust ei ole kõige ohutum järgmine samm tavaliselt kompenseeriv mutatsioon. Kõigepealt küsige, mis juhtus.

Kasutage toimingute pearaamatut idempotentsuse võtme, sõrmejälje ja viimase teadaoleva päringu ID leidmiseks. Seejärel kontrollige asjakohaseid Partner API pindu: gruppide ja võtmete loendid ettevalmistamiseks, tehingud krediidi täiendamiseks, saldo rahakoti oleku jaoks, kasutustaotluste kirjed ja haldusmutatsioonide auditisündmused.

Praktiline vastavusseviimise jada on järgmine:

1. Laadige kohaliku toimingu kirje uuesti lukuga.
2. Proovige algset mutatsiooni uuesti sama idempotentsusvõtmega, kui see on endiselt säilitusaknas ja päringu sõrmejälg ühtib.
3. Kui uuesti proovimine olekut ei lahenda, esitage päring asjakohasest loendist või hankige lõpp-punktid, kasutades kliendi metaandmeid, rühma ID-sid, võtme ID-sid, tehingu ID-sid või ajatempleid.
4. Vaadake üle auditisündmused, et leida edukaid haldusmutatsioone, mis on seotud päringu ID, toimingu, sihtmärgi ja UTC ajatempliga.
5. Värskendage tõenditega kohalikku toimingut õnnestus, failed_final või reconciliation_needed.
6. Väljasta kompenseeriv mutatsioon alles pärast ülesvoolu oleku kinnitamist ja uue kompensatsioonitoimingu salvestamist.

7-päevane idempotentsuse säilitamise aken on kasulik tavaliste korduskatsetuste jaoks, kuid see ei ole raamatupidamisarhiiv. Hoidke püsivaid kohalikke dokumente toetuse, rahanduse ja hilinenud vaidluste kohta.

Runbook for Stuck States

ootel_rühma loomine

Kontrollige, kas operatsioonikirje on olemas ja kas idempotentsuse võti saadeti. Kui päring võis jõuda Partner API-sse, proovige uuesti sama võtmega. Kui puuduvad tõendid päringu saatmise kohta, saatke algne päring ja salvestage päringu ID.

group_created_key_pending

Kinnitage rühma sihtmärgi ID kohapeal ja ülesvoolu. Ärge looge teist rühma. Looge või proovige uuesti klahvitoimingut oma idempotentsusvõtmega.

key_created_local_save_failed

See on turvalisuse seisukohast tundlik, kuna API võtme saladusi kuvatakse sageli ainult üks kord. Kui saladust ei salvestatud vastavalt eeskirjadele, märkige võti kohapeal kasutuskõlbmatuks, tühistage või pöörake seda selgesõnalise toiminguga ja looge uue ärilise eesmärgiga asendusvõti.

topup_requested_unknown

Võimalusel proovige sama idempotentsusklahviga uuesti täiendada. Seejärel ühildage tehingud ja rahakoti saldo. Ärge tehke teist laadimist lihtsalt sellepärast, et esimene vastus läks kaduma.

webhook_received_processing_failed

Hoidke veebihaagi sündmus märgituna vastuvõetuks ja täitmata. Pärast põhjuse kõrvaldamist esitage see uuesti töötaja kaudu. Ainulaadne sündmusekirje hoiab ära topelttäitmise.

leppimine_vajalik

Määrake toiming päringu ID, idempotentsuse võtme, kliendi ID, sihtmärgi ID-de, ajatemplite ja viimaste vigadega sisemisse tugijärjekorda. Käsitsi ülevaatus peaks värskendama sama toimingukirjet, mitte looma eraldi privaatset rada.

Testi kontroll-loend

• Sama kliendi registreerimisnupul tehtud topeltklõpsud loovad ühe rühma ja ühe ettenähtud võtme.
• Töötaja krahh pärast ülesvoolu õnnestumist, kuid enne kohaliku salvestamise jätkumist ilma dubleerivate kõrvalmõjudeta.
• HTTP ajalõpp enne vastuse sisu käsitlemist sama idempotentsusvõtme uuesti proovimisega.
• Duplikaatmakse veebihaak ei loo topeltkrediidi lisamist.
• Järjest väljas maksete veebihaak ja varustamistöö koonduvad õigesse kliendi olekusse.
• 429-vastus koos käsuga Retry-After lükkab uuesti katse edasi ilma toimingu identiteeti muutmata.
• Idempotentsuse võtme taaskasutamine muudetud kasuliku koormusega nurjub kohapeal.
• Kummaväärtused umbes 0,01, 0,10, 100,00 ja kululimiidi piirid ei ümardu ootamatult.
• Auditi-sündmuse vastavusseviimine võib selgitada, kes ja millal gruppi, võtit või piirangut muutis.
• Idempotentsuse säilitamise aknast vanemad toimingud on kooskõlastatud kohalike kirjete ja Partner API aruandluspindade kaudu, mitte pimeda taasesituse kaudu.

Kauplemised

Deterministlikud idempotentsusvõtmed muudavad korduskatsed ja uurimise lihtsamaks, kuid need peavad sisaldama piisavalt ärikonteksti, et vältida võtme taaskasutamist tõeliselt uue eesmärgi jaoks.

Kohalik toimingute pearaamat muudab skeemi ja töövoo keerukamaks, kuid annab integratsioonile püsiva tõeallika, kui võrgukõned, veebihaagid ja andmebaasi kirjutamine eri aegadel ebaõnnestuvad.

Kiire veebihaagi allaneelamisest naasmine vähendab teenusepakkuja korduskatseid, kuid see nõuab usaldusväärset järjekorda, taasesituse tööriistu ja jälgimist, et töötlemise tõrked oleksid nähtavad.

Sõrmejälgede range päringu kontrollimine hoiab ära võtme juhusliku taaskasutamise erinevate kasulike koormustega, kuid sunnib selgesõnalist versioonimist, kui registreerumise vaikeväärtused või piirangumallid muutuvad.

Saldo, tehingu, rühma, võtme ja auditi lõpp-punktide kaudu vastavusse viimine on aeglasem kui algse vastuse usaldamine. See on ka turvalisem tee pärast teadmata tulemusi.

Tehtitav järeldus

Usaldusväärne partneri API automatiseerimine on nii raamatupidamise ja toimingute kui ka HTTP-integratsiooni probleem. Alustage püsivate äritoimingute määratlemisest: looge kliendigrupp, looge võti, muutke limiiti, lisage krediiti, ühildage rahakott ja töödelge veebihaagi. Andke igale toimingule stabiilne idempotentsuse võti, päringu sõrmejälg, olekumasin ja püsiv kohalik kirje.

Seejärel muutke iga töötaja igavaks: hankige operatsioon, saatke täpselt kavandatud päring, kasutage sama idempotentsusvõtit pärast tundmatuid tulemusi, sõeluge täpselt kümnendstringe ja enne kompenseerimist ühildage. See disain ei kõrvalda igat tõrget, kuid muudab tõrked seletatavaks, uuesti proovitavaks ja auditeeritavaks, ilma et kliendile tekiks dubleerivaid kõrvalmõjusid.

Seotud lugemine

• apitele-tenant-opgramse-limits provisjoni arhitektuur
• AI API arveldusraamatu vastavusseviimine
• API võtmehalduse juhtelemendid meeskondadele