Ponovni poskus agenta lahko podvoji dejanje: zaščitite stranske učinke

Podvojena dejanja agenta preprečite tako, da vsakemu koraku, ki spremeni zunanji sistem, dodelite stabilen ključ idempotentnosti, pred klicem shranite njegovo namero in pred ponovitvijo preverite dejanski učinek. Dokumentacija Apache Airflow opozarja, da se lahko orodje po napaki izvede znova, če je stranski učinek že nastal, rezultat orodja pa še ni bil shranjen.

Časovna prekoračitev pomeni, da izvajalec ni pravočasno prejel odgovora. Sama po sebi ne pove, ali je cilj zahtevo prejel, sporočilo poslal ali zapis ustvaril. Zato manjkajočega odgovora ne obravnavajte kot dovoljenja za nov klic: stanje namere, opaženi rezultat klica in stanje pri cilju so trije različni podatki.

Zakaj običajen ponovni poskus ni varen

Agent lahko med enim zagonom pokliče več orodij. Če najprej ustvari zapis, nato pošlje obvestilo in pri pošiljanju izgubi povezavo, ponovitev celotnega načrta lahko znova ustvari tudi zapis. Izvajalec mora obnoviti posamezni korak iz njegovega shranjenega stanja, namesto da agentu prepusti novo načrtovanje že začetih sprememb.

Predpomnjenje rezultatov pomaga le pri korakih, katerih rezultat je bil uspešno zapisan. Med učinkom v zunanjem sistemu in shranitvijo odgovora ostane časovno okno, v katerem lahko izvajalec odpove. Prav za ta primer potrebujete zaščito pri samem dejanju in možnost poznejšega preverjanja cilja.

Ključ sestavite iz izvornega dogodka in posameznega dejanja

Vsak vhodni dogodek naj ima trajen identifikator, na primer ID zahtevka ali sporočila v vrsti. Za vsako spremembo določite ločen ključ iz identifikatorja dogodka, vrste dejanja, cilja in po potrebi različice nameravane operacije. Ustvarjanje zapisa in pošiljanje obvestila zato dobita različna ključa, ponovitev istega pošiljanja pa ohrani prvotnega.

Ključ določite v aplikacijski kodi pred klicem orodja. Ne ustvarjajte ga na novo ob vsakem poskusu in njegove izbire ne prepustite modelu, saj lahko ta po ponovnem zagonu oblikuje drugačne argumente. Skupaj s ključem shranite tudi nespremenljivo različico vhodnih podatkov; če agent predlaga drugačno vsebino, jo obravnavajte kot spremembo namere, ki zahteva ločeno odločitev.

Navodila za Workspace Agents API določajo, da ponovitev istega sprožilnega dogodka z istim Idempotency-Key vrne prvotni sprejeti izid, namesto da bi dodala nov dogodek v vrsto. To velja za sprožitev agenta. Če ta pozneje piše v drugo storitev, potrebuje tudi tisti klic svoj ključ ali drugo zaščito pred podvajanjem.

Namera naj bo trajna, izvajanje pa usklajeno

Pred zunanjim klicem v bazo zapišite izvorni dogodek, ključ dejanja, cilj, vrsto operacije in različico vhodnih podatkov. Za ključ uvedite omejitev enoličnosti. Tako dva izvajalca ne moreta ustvariti dveh ločenih lokalnih namer za isto dejanje, obstoječi zapis pa omogoča obnovitev po prekinitvi.

Enoličnost zapisa še ne prepreči, da bi dva izvajalca hkrati poslala zahtevo. Prevzem dejanja zato uredite z atomskim prehodom stanja ali časovno omejeno dodelitvijo izvajalcu. Če dodelitev poteče med zunanjim klicem, novega izvajalca usmerite v preverjanje izida; sam potek časa ni dokaz, da je prvi klic prenehal delovati.

Koristna stanja so »pripravljeno«, »v teku«, »potrjeno« in »nejasen izid«. V »potrjeno« preidite šele ob preverljivem odgovoru ali podatku iz ciljnega sistema, na primer ID-ju ustvarjenega objekta. Lokalna omejitev baze varuje lokalni zapis; podvajanje v zunanji storitvi prepreči njen mehanizem idempotentnosti ali preverjanje že izvedene operacije.

Rezultat klica beležite ločeno od dejanskega učinka

Za vsak poskus hranite uporabljeno orodje, čas začetka, ključ, različico poslanih podatkov ter prejeti odgovor ali napako. Če cilj vrne ID objekta, ga povežite z zapisom namere. Dnevnik poskusov pove, kaj je izvajalec opazil; zapis namere pove, kaj je želel opraviti; poizvedba pri cilju pa lahko pokaže, kaj se je dejansko zgodilo.

Napaka orodja lahko nastane po delno opravljenem delu. Prav tako uspešen odgovor API-ja lahko pomeni le sprejem zahteve, če se končni učinek izvede pozneje. Zabeležite natančen pomen odgovora, ki ga vrača posamezno orodje, in ne enačite samodejno sprejema, zaključka ter dostave.

Pravila ponavljanja so odvisna tudi od ponudnika. Stripejeva pravila idempotentnosti določajo, da ponovitev z istim ključem vrne shranjeni odgovor prve zahteve, tudi če je bil to odgovor z napako 500; po odstranitvi ključa iz sistema pa lahko ponovna uporaba sproži novo zahtevo. Zato ob napaki preverite stanje operacije in pravila hrambe ključa, preden sklepate, kaj bo naredil naslednji poskus.

Po časovni prekoračitvi odločite glede na stanje pri cilju

Ob nejasnem odgovoru naj izvajalec najprej prebere zapis namere in dnevnik poskusov. Nato naj pri ciljni storitvi poišče operacijo po ključu idempotentnosti, izvornem ID-ju ali poslovnem identifikatorju ustvarjenega objekta, če storitev takšno iskanje omogoča. Pri sporočilih razlikujte med podatkom, da je storitev zahtevo sprejela, in podatkom, da je sporočilo dostavila.

1. Če cilj potrdi učinek, shranite njegov zunanji ID, označite dejanje kot potrjeno in nadaljujte z naslednjim korakom.
2. Če je zanesljivo ugotovljeno, da učinka ni bilo, ponovite isto dejanje z istim ključem in istimi vhodnimi podatki.
3. Če cilja ni mogoče preveriti ali odgovor dopušča oba izida, označite dejanje kot nejasno in ustavite samodejno ponavljanje tega koraka.

Pri zadnji možnosti mora biti za ročno obravnavo na voljo dovolj podatkov za odločitev: izvorni dogodek, ključ, cilj, poslani podatki, časi poskusov, odgovori in morebitni zunanji ID-ji. Skrbnik lahko nato potrdi že opravljeno dejanje, dovoli ponovitev pod prvotnim ključem ali odobri novo, jasno ločeno operacijo. Če cilj ne omogoča iskanja in ne sprejema stabilnega ključa, avtomatizacija po nejasnem izidu ne more zanesljivo vedeti, ali bi ponovitev povzročila podvojitev.