Keresés és weboldal
API: integrációs megállapodás, válasz és ismétlés
Milyen műveletet kérünk, mit jelent a válasz, és mi történik bizonytalan kimenetnél? Kitöltött szerződés, ismétlési modell és eseményhalmaz.
Szoftveres kapcsolat, pontos állapotok
Egyszer?
Újra elküldte. Újra teljesült?
RövidenAz API, vagyis alkalmazásprogramozási felület olyan meghatározott műveletek és szabályok együttese, amelyen keresztül egy szoftver más szoftverrel vagy rendszerösszetevővel kapcsolatba léphet. Az integrációhoz a kérés, válasz, jogosultság, hiba, ismétlés és változás feltételeit is ismerni kell; az API nem kizárólag webes REST-kapcsolat.
Más elnevezések: alkalmazásprogramozási felület, application programming interface.
Az API azt határozza meg, milyen módon vehet igénybe egy szoftver egy másik szoftver által kínált működést. A kapcsolat lehet helyi vagy hálózati, és nem minden API egy webcímen elérhető REST-szolgáltatás. Üzleti integrációnál a „van hozzá API” még kevés: tudni kell, mely műveletet fogadja, mit jelent a válasz, és mi történik hiba vagy ismétlés esetén. A következő saját kávékóstolós példa ezekből készít kitöltött, ellenőrizhető munkalapot.
A HTML a kiadott dokumentum szerkezetét írja le; egy API más rendszerek közötti műveleti szerződést is adhat. Az e-kereskedelem rendelési láncában a visszaigazolt technikai kérés és a ténylegesen teljesített üzleti feladat külön állapot.
Programok közötti felület, megnevezett szabályokkal
Az MDN meghatározása az API-t szoftveres képességek és szabályok összességeként írja le. Ide tartozhat böngészőben elérhető funkció, operációs rendszerhez adott felület vagy távoli szolgáltatás kapcsolata. A nyilvános webes API csak egy megvalósítási kör. A marketinges számára az a hasznos kérdés, hogy az adott felület melyik konkrét üzleti feladatot teszi lehetővé, milyen feltételekkel és milyen ellenőrizhető eredménnyel.
A kitalált kávéműhely weben fogad érdeklődést kóstolóira. A belső kapacitáskezelő külön rendszerben tartja a helyeket. A példabeli API-kapcsolat helyfoglalási műveletet kér, majd azonosítható állapotot ad vissza. Nincs valódi külső fiók vagy most végzett API-hívás. A kapcsolat nem lesz megfelelő attól, hogy a fejlesztő egy adatot egyszer sikeresen lekért. A létrehozás, az állapotellenőrzés és a hibák kezelése is része a vállalt működésnek.
A dokumentált lehetőség nem azonos a kész integrációval
Egy dokumentáció felsorolhat műveleteket, de a két rendszer közötti adatkapcsolatot ettől még meg kell tervezni. A mezők jelentése, a hozzáférés, a hibák és a változások saját feladatot adnak. Egy általános összekötő eszköz csökkentheti a fejlesztést, de nem találhatja ki helyettünk, melyik ügyfélállapotot szabad továbbítani. A marketingautomatizálás a működési szabályok tágabb rendszerét tárgyalja; itt a szoftveres határ pontos szerződése a kérdés.
A műhely érdeklődői adata és a ténylegesen elkülönített férőhely külön állapot. Ha az integráció csak kapcsolatot hoz létre a CRM-ben, abból nem következik, hogy a kapacitásrendszer helyet is tart fenn. Az üzleti lap mindkét eredményt megnevezi. A fejlesztő így nem egy homályos „szinkronizálást” kap, hanem a kívánt műveletet és a hozzá szükséges bizonyítékot. A rendszernevek összekötése önmagában nem elfogadási feltétel.
Kitöltött megállapodás egy helyfoglalási műveletre
A saját integrációs lap első sora a célt írja le: a kijelölt kóstolóhoz meghatározott számú hely elkülönítése, azonosítható kérés alapján. A kérés nem indulhat újra új ügyként ugyanazon kattintás vagy hálózati ismétlés miatt. A fogadó rendszer ellenőrzi a jogosultságot és az aktuális kapacitást. A küldőnek megfelelő választ kell adnia arra is, ha a hely már nem érhető el. A példa saját működési szerződés, nem minden szolgáltató előírása.
| Megállapodási mező | Kitöltött oktatási érték |
|---|---|
| Üzleti művelet | Két hely elkülönítése a KOST-17 alkalomra |
| Küldő műveletazonosító | H-508, ugyanazon logikai kérésnél megőrizve |
| Érvényes bemenet | Létező alkalom, pozitív egész létszám, szükséges jogosultság |
| Siker bizonyítéka | Foglalási azonosító és elkülönített állapot |
| Elutasítás | Érvénytelen adat vagy nincs megfelelő kapacitás |
| Bizonytalan kimenet | A válasz nem érkezett meg; előbb állapotegyeztetés szükséges |
A műveletazonosító és az ügyfélazonosító külön adat. Ugyanaz az ügyfél másik alkalomra új kérést indíthat, ezért nem elegendő minden ismétlést a nevéből felismerni. A titkos hozzáférési adat nem kerül az üzleti munkalapra. A dokumentum a szükséges jogot nevezi meg, a tényleges titkot megfelelően kezelt rendszer őrzi.
Két hely elkülönítése azonosítható műveletként
Üzleti célA kapcsolati sor létrejötte önmagában nem férőhely-elkülönítés.Két hely a KOST-17 alkalomraMűveletazonosítóUgyanazon logikai kérés ismétlésénél a szerződés szerint megőrzendő.H-508Végleges sikerA köztes technikai átvétel ettől külön eredmény.Azonosító és elkülönített állapotBizonytalan kimenetA hiányzó válaszból nem következik, hogy a művelet nem teljesült.Állapotegyeztetés

A mezőnév mögött tartalmi jelentés van
A létszám lehet fő, a készlet lehet darab, az időpont lehet helyi idő vagy egy pontosan meghatározott időalap szerinti érték. Azonos nevű mezők nem feltétlenül azonos jelentésűek. A fejlesztőnek és a folyamatfelelősnek együtt kell tisztáznia az egységet, a megengedett értéket és a hiány jelentését. Az üres adat nem mindig nulla. A „nincs megadva” és a „nem szükséges” szintén eltérő állapot lehet.
A kitöltött mezőtérkép a KOST-17 alkalomhoz két főt kapcsol, nem két jegycsomagot. A megjegyzés hiánya nem jelenti, hogy az ügyfél minden lehetséges feltételt elfogadott. A kedvezménymező üressége nem alakítható automatikusan százszázalékos kedvezménnyé vagy különleges jogosultsággá. A fogadó rendszer a megállapodás szerinti validálást végzi. A tesztkészletben külön szerepel hiányzó alkalom, nulla létszám és nem ismert azonosító, saját elvárt hibával.
Válasz érkezett, de melyik feladat készült el?
Webes HTTP-kapcsolatnál a válaszkód a protokoll meghatározott jelentését hordozza. Az RFC 9110 szerint a 202-es válasz feldolgozásra elfogadott, még nem befejezett kérést jelez. Nem bizonyítja a kért üzleti eredmény létrejöttét. A szolgáltatásnak külön meg kell mondania, hogyan ismerhető meg a végső állapot. Egy köztes technikai siker nem nevezhető automatikusan kész rendelésnek vagy elkülönített férőhelynek.
A saját példában a kérés sorba kerülhet, és egy feldolgozási azonosítót kap. A vásárlói szöveg ekkor a fogadásról tájékoztat, nem állít végleges helyet. A következő állapot ellenőrzött lekérdezésből vagy megfelelő eseményből származhat. Másik megvalósítás azonnal végleges állapotot adhat; ezt is a konkrét szerződés határozza meg. A munkalap a technikai választ és a bizonyított üzleti állapotot külön oszlopban őrzi, hogy a két fogalom ne mosódjon össze.
Száz művelet és százhat hálózati próbálkozás
A saját külön számpélda száz külön logikai helyfoglalási műveletet indít. Kilencven kérésre azonnal megfelelő végleges válasz érkezik. Négy érvénytelen bemenetet visszautasítanak. Hatnál időtúllépés miatt a küldő nem ismeri a kimenetet. A hatból négyet a fogadó már végrehajtott, kettőt még nem. Ezt az oktatási modellben tudjuk; egy valódi időtúllépésből önmagában nem lehetne ugyanígy kitalálni.
Az ismétlés a megállapodás szerinti azonosítóval és védelemmel történik. A négy már végrehajtott kérés ugyanahhoz a meglévő eredményhez jut, a másik kettő egyszer létrejön. A végső készlet kilencvenhat létrehozott helyfoglalás, négy elutasítás. A hálózati próbálkozások száma 100 + 6 = 106, az üzleti műveleteké száz. A hat újabb kérés ezért nem hat új vásárló vagy hat külön helyfoglalás.
Hat ismétlés nem hat új helyfoglalás
Első próbálkozások90 azonnali siker, 4 bemeneti elutasítás, 6 bizonytalan válasz.100A hat bizonytalan esetAz oktatási modellben ismert háttérállapot; valós hibából nem találgatjuk.4 már létrejött, 2 még nemIsmétlések után90 + 4 meglévő + 2 új; nincs második teljesítés ugyanarra a műveletre.96 végleges eredményÖsszes hálózati próbaTovábbra is 100 üzleti művelet, végül 96 eredmény és 4 elutasítás.100 + 6 = 106

Idempotencia: ugyanazon kérés ne teljesüljön kétszer
Az idempotens HTTP-műveletnél több azonos kérés szándékolt szerveroldali hatása megegyezik egyetlen kérés hatásával. Ez nem jelenti, hogy minden válasz vagy naplósor betűre azonos lesz. Egy adott létrehozó API külön ismétlésvédelmet adhat. A saját integráció nem feltételezheti ezt pusztán a webes kapcsolat tényéből. A fejlesztő a dokumentált szerveroldali viselkedést és annak határát ellenőrzi, az üzleti művelethez igazítva.
A Stripe idempotenciadokumentációja konkrét szolgáltatói példa az ismétléshez adott kulcs használatára. A részletszabály szolgáltatásonként, sőt ugyanazon szolgáltató felületváltozatai között is eltérhet. A műhely ezért nem másolja át univerzális szabályként a kulcs megőrzési idejét vagy egy hibás válasz újbóli kezelését. A saját megállapodás kimondja, mely művelethez mely kulcs tartozik, meddig ismerik fel, és mi történik, ha ugyanazzal az azonosítóval más létszámot kérnek.
Az időtúllépés nem egyenlő sikertelen teljesítéssel
Az időtúllépés a küldő oldalán bizonytalan kimenetet jelenthet. A szolgáltatás dolgozhatott a kérésen, miközben a válasz útközben elveszett vagy későn érkezett. A vakon új azonosítóval küldött művelet ezért dupla teljesítést okozhat. A helyes folytatás az adott API dokumentált egyeztetési vagy ismétlési rendje. A cikk nem javasol minden kapcsolatnál automatikus újrapróbálást ugyanannyi alkalommal.
A H-508 tesztügyben a küldő előbb a korábbi művelet állapotát keresi. Ha az adott rendszer ezt nem tudja biztonságosan megállapítani, a napló bizonytalan ügyként felelőshöz irányítja. A vásárlót nem kell újabb valódi helyfoglalásra ösztönözni csak azért, mert a hálózati válasz hiányzott. A helyreállítás a már létező ügyet rendezi. A teszt két változatot használ: végrehajtott, de válasz nélküli kérést és ténylegesen végre nem hajtott kérést, eltérő elvárt bizonyítékkal.
Hibafajtához illeszkedő folytatás kell
Az érvénytelen mező, a hiányzó jogosultság, a túl sűrű kérés és az átmeneti szolgáltatási hiba nem ugyanazt a teendőt kívánja. A felhasználónak érthető visszajelzés kell, az üzemeltetőnek pedig megfelelő technikai azonosító. A titkos kulcs vagy teljes személyes adattartalom nem kerülhet a nyilvános hibaüzenetbe. A szerződés a javítható adatot, az ismétlés feltételét és a kézi beavatkozást külön nevezi meg.
A saját hibamunkalap három kitöltött sort tartalmaz: nulla létszámnál bemeneti javítás; érvénytelen hozzáférésnél jogosult technikai ellenőrzés; bizonytalan időtúllépésnél állapotegyeztetés. Egyiknél sem megfelelő ugyanaz a korlátlan újraküldő automatizmus. A szükséges várakozást és korlátot az adott szolgáltatás dokumentációja adja. Ha a rendszer külön jelzi az újrapróbálás feltételét, azt a megvalósító figyelembe veszi. A próba a hibás út következményét is igazolja, nem csak a szokásos sikeres kérést.
A kérési korlátot a teljes folyamattal számold
A külön, feltételezett adatfrissítési modell hatszáz sort kezel, kérésenként százat. Ez legalább hat adatoldalt jelent, ha valóban mindegyik teljes és a szolgáltatás így lapoz. Két ismételt kérés esetén nyolc hálózati próbálkozás történik. Kétperces időablakban ez átlagosan négy kérés percenként. A hatszáz sor és a nyolc kérés külön egység. A tényleges korlátot a szolgáltató saját szabályából kell megismerni.
A példában feltételezett tíz kérés percenként nem valós termékcsomag vagy ajánlott küszöb. Az átlag ráadásul nem mutatja meg a pillanatnyi sűrűséget. Nyolc egyszerre küldött kérés más terhelési helyzet, mint egyenletesen elosztva. A lap megőrzi az időzítést és a párhuzamos műveleteket is. A kapacitáskezelő és az olvasó lekérdezés korlátja eltérhet, ezért nem másoljuk át ugyanazt a számítást minden műveletre. A döntés a dokumentált feltételhez kötött végrehajtási terv.
Lapozáskor a sorösszeg nem mindig egyedi rekord
Az adatok frissülhetnek, miközben a küldő több részletben olvas. A lapozás módja és az adatváltozás szabálya befolyásolhatja, hogy ugyanaz a rekord ismét megjelenik-e vagy kimarad-e. A hatszáz soros külön mintában tizenöt sor korábban már látott rekord ismételt előfordulása. Így 585 külön azonosító szerepel, ha más ismétlés vagy hiány nincs. Ebből még nem következik, hogy az összes valós rekordot sikerült áthozni.
A saját egyeztetési lap az olvasási határt, a lapozási jelölőt és a rekord azonosítóját őrzi. A „legutóbb módosult” idő értelmezését is tisztázza: ugyanazon időponthoz több rekord tartozhat. A megvalósító a dokumentált folytatási szabályt használja, nem kitalált sorrend alapján lép tovább. Az elfogadási próba változó adatot is tartalmaz. A végső bizonyíték a kijelölt készlet megfelelő lefedése és a helyes állapot, nem a kérések puszta darabszáma.
Eseményküldés: értesítés és feldolgozás külön állapot
Egy szolgáltatás eseményről értesítheti a fogadót, gyakran webhooknak nevezett kapcsolaton. Az értesítés átvétele és a teljes üzleti munka befejezése nem feltétlenül egyszerre történik. A fogadó megállapodás szerint ellenőrzi az eredetet, megőrzi a szükséges kapcsolatot és végrehajtja a kijelölt feladatot. A beérkezett üzenet nem automatikusan feldolgozott helyfoglalás. A megvalósításnak a megszakítás és az újraindulás állapotát is kezelnie kell.
A Stripe eseménykezelési útmutatója konkrétan tárgyalja az ismételt eseményt és a nem garantált kézbesítési sorrendet. Ez a szolgáltató saját feltétele, nem minden API-ra előírt tulajdonság. A műhely saját kapcsolatánál ugyanezeket a kérdéseket külön tisztázza. A későn érkező értesítés nem írhatja vissza ellenőrizetlenül a már újabb állapotú ügyet. A fogadó megfelelő azonosító és dokumentált állapotszabály szerint dönt, szükség esetén az aktuális forrásállapotot egyeztetve.
Negyven eseménykézbesítés kitöltött halmaza
A külön oktatási eseménynapló negyven kézbesítést tartalmaz. Harminckét külön eseményazonosító szerepel benne, nyolc sor ismételt kézbesítés. A harminckét eseményből harmincat feldolgoztak, kettő vizsgálatra vár. A 30/32 = 93,75% az egyedi eseménykészlet feldolgozottsága. A 30/40 = 75% más nevező, amely itt nem ugyanazt a kérdést írná le. Egyiket sem tekintjük általános szolgáltatói megbízhatósági értéknek.
A két nyitott esemény nem számítható megfelelőnek pusztán az átvételi visszajelzés miatt. A nyolc ismétlés pedig nem hozhat létre nyolc új ügyet. A napló az eseményazonosítót és az üzleti objektum kapcsolatát is kezeli a saját szabály szerint. Ha a szolgáltató külön eseményobjektumokat használ ugyanazon üzleti változáshoz, az egyszerű technikai azonosító mellett további ellenőrzés kellhet. A cikk saját készlete a kézbesítési ismétlés egyszerű esetét mutatja, nem minden szolgáltató teljes eseménymodelljét.
Negyven kézbesítés harminckét külön eseményhez
Kézbesítési sorEbből nyolc már látott esemény ismételt kézbesítése.40Külön eseményA szerkesztett készlet ismétlés nélküli eseményazonosítói.32Feldolgozott30 / 32 = 93,75% az egyedi eseménykészletben.30Vizsgálatra várNem kész a puszta átvételtől; 30 / 40 = 75% más nevező lenne.2

Öt válaszidő nem írja le az összes próbálkozást
A saját külön teljesítménylap öt sikeres válaszidőt tartalmaz: 120, 180, 200, 240 és 1260 ezredmásodpercet. Összegük kétezer, átlaguk négyszáz, mediánjuk kétszáz ezredmásodperc. A nagyobb utolsó érték az átlagot jelentősen befolyásolja. A készlet nem tartalmazza a sikertelen vagy időtúllépő kérések időtartamát. A mutató neve ezért öt sikeres válasz ideje, nem minden ügy teljes feldolgozási sebessége.
Az üzleti feladat teljes ideje az ismétlést, a várakozást és az esetleges későbbi feldolgozást is tartalmazhatja. A felhasználói eredményhez ezt kell vizsgálni. A technikai válaszidő fontos részlet, de egy gyors „elfogadva” válasz mögött még lehet hosszú sor. A saját jelentés külön tárolja az átvétel és a végleges állapot időpontját. A csapat nem cseréli fel a kettőt, amikor az ügyfélnek azt magyarázza, mikor kap biztos visszaigazolást a helyéről.
A hozzáférési kulcs nem adatkezelési engedély
Egy működő technikai hitelesítő adat azt mutathatja, hogy a rendszer a megfelelő hozzáférési joggal hívható. Nem ad automatikus felhatalmazást minden elérhető adat bármilyen üzleti használatára. A folyamatfelelős meghatározza a célt, a szükséges adatot és a megfelelő hozzáférést. A megvalósító ehhez igazítja a kérést és a tárolást. A titkos kulcs megjelenítése nem lehet része nyilvános oktatási példának vagy képernyőképnek.
A műhely kapcsolatának a kijelölt alkalom és a szükséges létszám elegendő lehet a kapacitásellenőrzéshez. A teljes ügyféladatbázis átmásolása más feladat és más következmény. A tesztkörnyezet saját, elkülönített adatot használ. A hibajegy technikai kapcsolati azonosítót őriz, nem feleslegesen a teljes üzenettartalmat. Ha további adat szükséges, azt a megnevezett célhoz kell indokolni. A „hozzáférünk” és a „szükségünk van rá” két külön döntési kérdés marad.
Változatkezelés és elavuló mezők
A szolgáltatás változhat: új kötelező mező, módosult értékkészlet vagy kivezetett művelet jelenhet meg. Az integráció tulajdonosa ezért nemcsak az első fejlesztésért felelős. Követnie kell a dokumentált változást és az érintett működést. A konkrét verziójelölés szolgáltatásonként eltérhet. A cikk nem állítja, hogy minden API útvonalában szám szerepel, vagy minden frissítés visszafelé változatlanul használható.
A saját változási lap az alkalomazonosító mezőjének új ellenőrzését példázza. A régi, szabad szöveges megnevezés helyett a fogadó ismert azonosítót vár. A fejlesztő megkeresi az adat forrását és elkülönített próbán ellenőrzi az új kérést. A hiányzó megfeleltetést nem helyettesíti találomra az első elérhető időponttal. A kiadási bizonyíték a helyes alkalomhoz kötött művelet. Az átadás megnevezi az érintett verziót és a még át nem állított kapcsolati helyeket is.
Tizenöt elfogadási eset a normál úton túl
A saját tesztlap tizenöt előre megnevezett esetet tartalmaz. Öt megfelelő bemenetet, négy hibás kérést (adat- vagy jogosultsági eltérést), három ismétlési helyzetet és három megszakítási vagy állapotegyeztetési esetet vizsgál. A csoportok a lapban külön sorokat jelentenek. Tizenegy megfelelő, három hibás, egy még nem végrehajtott. A 11/15 kerekítve 73,33%, kizárólag ennek a kijelölt ellenőrzési körnek az eredménye. Nem API-minősítés vagy éles rendelkezésreállási arány.
A három hibás eset az eltérő létszámmal ismételt kulcs, a válasz nélküli, már végrehajtott kérés és a későn érkező esemény hibás kezelése. Ezekből konkrét feladat készül. Az ismeretlen eset nyitott marad, nem kerül a sikerek közé. A próba nem valós ügyfél számára foglal helyet. Az elfogadási bizonyíték az előfeltétel, a bemenet, a megfigyelt válasz, az üzleti állapot és az ismétlés utáni eredmény együttese.
Az alábbi teljes esetkészlet a kitalált integráció saját szerződését vizsgálja. A jó hibakezelés is „megfelelő” eredmény: ilyenkor az elvárt elutasítás vagy bizonytalan állapot marad meg, jogosulatlan foglalás nélkül. A leírt kimenetek oktatási adatok.
| ID | Csoport és bemenet | Elvárt üzleti eredmény | Saját mintaeredmény | Állapot |
|---|---|---|---|---|
| A01 | Megfelelő: két hely, elérhető alkalom | Két hely és foglalási azonosító | Két hely elkülönítve | Megfelelő |
| A02 | Megfelelő: egy hely, elérhető alkalom | Egy hely és saját műveletazonosító | Egy hely elkülönítve | Megfelelő |
| A03 | Megfelelő: utolsó két szabad hely | Pontosan két hely, maradék nulla | A kapacitás helyesen elfogy | Megfelelő |
| A04 | Megfelelő: ugyanaz az ügyfél másik alkalomra | Új művelet a másik alkalomhoz | Külön, helyes foglalás jön létre | Megfelelő |
| A05 | Megfelelő: nem kötelező megjegyzés nélkül | A szükséges adatokkal teljesül | A kérés teljesül, nincs kitalált megjegyzés | Megfelelő |
| A06 | Hibás kérés: nem létező alkalom | Elutasítás, helyfoglalás nélkül | Elutasítás és érthető hibakód | Megfelelő |
| A07 | Hibás kérés: nulla létszám | Elutasítás, kapacitásváltozás nélkül | A nulla értéket elutasítja | Megfelelő |
| A08 | Hibás kérés: negatív létszám | Elutasítás, kapacitásváltozás nélkül | A negatív értéket elutasítja | Megfelelő |
| A09 | Hibás kérés: szükséges jogosultság hiányzik | Nincs üzleti művelet | A hozzáférést megtagadja | Megfelelő |
| A10 | Ismétlés: azonos kulcs és azonos két hely | Az eredeti eredmény, új elkülönítés nélkül | Egyetlen foglalás marad | Megfelelő |
| A11 | Ismétlés: párhuzamosan érkező azonos művelet | A dokumentált védelem mellett egy teljesítés | Egy teljesítés igazolható | Megfelelő |
| A12 | Ismétlés: azonos kulcs, két hely helyett három | Ütközés felismerése, nincs csendes átírás | A rendszer elfogadja az eltérő létszámot | Hibás |
| A13 | Megszakítás: teljesítés után elvesző válasz | Állapotegyeztetés, nincs új teljesítés | Új kérés újabb helyet különít el | Hibás |
| A14 | Állapot: későn érkező régi esemény | Az újabb igazolt állapot megmarad | A régi esemény visszaírja | Hibás |
| A15 | Megszakítás: egyeztetési forrás sem elérhető | Bizonytalan állapot és kijelölt következő próba | Még nem hajtották végre | Nem vizsgált |
Ki veszi észre a kapcsolat megszakadását?
A felületi hibaüzenet nem minden esetben elég. Az integráció háttérben is dolgozhat, miközben a felhasználó már nincs jelen. A működési lap ezért megnevezi a nyitott ügyek és hibák ellenőrzését. A jelzés a szükséges felelőshöz jusson, megfelelő részletességgel. Az összes nyers kérés korlátlan továbbítása nem hasznos hibanapló. Az ismételt technikai jelzést és az egyedi üzleti ügyet külön kell számolni.
A műhely saját napi egyeztetése az ismeretlen kimenetű helyfoglalásokat keresi. A felelős az eredeti műveletazonosító alapján állapítja meg, van-e végleges eredmény. A hibajegy lezárása nem pusztán az automatizmus újraindítása. A már függő ügyeket is a megfelelő állapothoz kell juttatni, dupla teljesítés nélkül. Az új működés ellenőrzése és a történeti elmaradás rendezése két összetartozó, de külön elfogadási pont. A jelentés mindkettőt megőrzi.
A kézi javítás is ugyanazt az üzleti szabályt kövesse
Egy üzemeltető megoldhatja a nyitott ügyet kézi egyeztetéssel, de a műveletet utána az automatikus folyamatnak is fel kell ismernie. Máskülönben egy későbbi ismétlés újra elvégezheti ugyanazt. A kézi javítás nem indokolja a kapcsolati azonosító elhagyását. A napló rögzíti, ki mit állapított meg és melyik meglévő ügyet rendezte. A szükséges jogosultság és jóváhagyás a saját működési rend része.
A H-508 ügyben az ellenőrző megtalálja a már létrejött férőhely-elkülönítést. Nem hoz létre újat a név alapján, hanem az eredeti művelethez kapcsolja a bizonyítékot. A következő automatikus egyeztetés már ezt a rendezett állapotot látja. A helyreállítási próba szándékosan újra kézbesíti a tesztjelzést, és ellenőrzi, hogy nincs második teljesítés. Ebből használható elfogadási feladat lesz, amely a valós üzleti kockázatra válaszol, nem csak egy program technikai futását igazolja.
Két rendszer részben is elkészülhet ugyanazzal az üggyel
A műhely külön próbája húsz kérést küld át a kapcsolatkezelő és a kapacitásrendszer közé. Tizenöt esetben mindkét kijelölt feladat megfelelően befejeződik. Háromnál létrejön a kapcsolatkezelői sor, de a helyelkülönítés nem teljesül. Kettőnél egyik eredmény sem jön létre. A készletben így tizennyolc kapcsolatkezelői sor és tizenöt teljes, kétoldali eredmény van. A 18/20 = 90% és a 15/20 = 75% eltérő feladatot mér. Egyik részrendszer sikere nem bizonyítja a másikét.
A részben elkészült három ügynek előre megnevezett folytatás kell. A csapat dönthet állapotegyeztetésről, kézi rendezésről vagy megfelelően tervezett visszavonó műveletről, a konkrét rendszer képessége szerint. Nem feltételezi, hogy két külön szolgáltatás automatikusan közös, mindent vagy semmit végrehajtást ad. A kapcsolatkezelői sor törlése sem szükségszerűen megfelelő üzleti rendezés. A napló megőrzi a két részfeladat állapotát és a döntés okát. A későbbi újrapróba csak a hiányzó részt végezheti el a saját megállapodás szerint, a már megfelelő eredmény megkettőzése nélkül.
Ugyanaz az azonosító más adattal nem egyszerű ismétlés
A H-508 eredeti kérés két helyet kívánt. Ha ugyanazzal a műveletazonosítóval később három helyet kérnek, a fogadónak fel kell ismernie a különbséget a saját szerződés szerint. Ez nem az eredeti hálózati kérés változatlan ismétlése. A megvalósítás elutasíthatja az ütközést vagy más dokumentált eljárást kérhet. Az üzleti változtatásnak saját azonosítható művelete és előfeltétele lehet. Az idempotenciakulcs nem általános engedély korlátlan utólagos átírásra.
A kitöltött teszt két egymást követő próbát őriz. Az első változatlan kétfős ismétlés, amelynek az eredeti ügyhöz kell jutnia. A második háromfős adatváltoztatás, amelynél a megállapodásban előírt ütközési eredményt várják. A fejlesztő a két kérést és a végleges helyszámot együtt vizsgálja. Ha a rendszer csendben elfogadja az új adatot, de a régi eredményt adja vissza érthető jelzés nélkül, az üzleti felület könnyen félretájékoztat. A próba ezért nem csak azt ellenőrzi, hogy nem lett második azonosító, hanem hogy a válasz jelentése is megfelel a tényleges állapotnak.
A régi ismétlésvédelmi adatnak lehet határa
A szerver nem feltétlenül őrzi örökké a korábban látott műveletazonosítót. A saját megállapodásnak ezért a felismerés időtartamát és a régi ügy rendezését is tisztáznia kell. A műhely példájában egy több napja bizonytalan kérést nem küldenek el új műveletként csak azért, mert a feldolgozó újraindult. Előbb megkeresik a történeti eredményt az üzleti nyilvántartásban. A szolgáltató tényleges megőrzési feltételét a megvalósító az aktuális dokumentációból ellenőrzi, nem másik API számát veszi át.
A kitöltött rendezési sor egy régi műveletet és annak meglévő helyfoglalási azonosítóját köti össze. Az integráció helyi ismétlési naplója időközben kiürült, a létrejött üzleti eredmény azonban megmaradt. A megfelelő egyeztetés visszaállítja a kapcsolatot, majd a következő feldolgozási próba már lezártnak ismeri fel az ügyet. Ez eltér attól az esettől, amikor az eredmény valóban nem létezett. A cikk nem javasol korlátlan titok- vagy személyesadat-megőrzést: a szükséges kapcsolati bizonyíték célját, tartalmát és hozzáférését a saját működési rend szerint kell meghatározni.
A lekérdezés és a módosítás eltérő elfogadási eset
A rendelkezésre álló helyek lekérdezése pillanatnyi adatot adhat, nem feltétlenül jelent foglalást. A látogató döntése és a tényleges elkülönítés között másik ügy is felhasználhatja a kapacitást. A műhely ezért nem a korábban látott szabad helyből vezeti le a végleges sikert. A módosító műveletnek az aktuális feltételt kell ellenőriznie. A felhasználói szöveg világosan különválasztja a megtekintett lehetőséget és a már igazolt eredményt.
A külön tesztben három szabad helyet lát két párhuzamos kérés, mindkettő két főt kíván. Ha a rendszer csak a korábbi lekérdezésre hagyatkozna, négy helyet ígérne a háromra. A megfelelő végrehajtás a saját szabály szerint megakadályozza a túlfoglalást, és a második ügynek érthető eredményt ad. A konkrét technikai megoldás a kapacitáskezelő feladata. Az elfogadási lap viszont közérthetően leírja a bizonyítandó feltételt: a végleges elkülönített helyek száma ne haladja meg a valóban elérhető készletet, és az elutasított kérés ne jelenjen meg kész foglalásként.
Másolható integrációs munkalap és lezárás
Az API-kapcsolat nem önálló bevételi vagy hatékonysági garancia. A használható integráció a megnevezett feladatot végzi el, és a hibát is követhető állapotba hozza. Egy weboldal technikai URL-próbája nem igazolja a háttérben működő API teljes szerződését, jogosultságát vagy ismétlésvédelmét. A saját munkalap azt segít átadni, amit valóban ellenőrizni kell: milyen kérésre mi történik, miből tudjuk ezt, és hogyan folytatjuk, ha a válasz bizonytalan.
Források és szerkesztési megjegyzés
- MDN: API és szoftveres kapcsolat
- RFC 9110: HTTP-műveletek és válaszok
- Stripe: idempotens kérések konkrét szolgáltatói példája
- Stripe: ismételt és eltérő sorrendű eseménykézbesítés
A forrásokat a feltüntetett frissítéskor ellenőriztük. A számpéldák oktatási minták, a javasolt ellenőrzőlisták szerkesztői útmutatók. A platformok működése és elnevezése változhat.
Vissza az összes fogalomhoz · Szerkesztési elvek · Javítást javaslok ehhez a szócikkhez
