6 kontrolle për të verifikuar ngjarjet më të fundit të gjurmimit të transportuesit të sinkronizuara përmes API-së suaj
Për të verifikuar që API-ja juaj ka sinkronizuar ngjarjet më të fundit të gjurmimit nga transportuesi, kontrolloni identitetin e dërgesës, vulat kohore të ngjarjeve, detajet e ngjarjeve, rrugën e dorëzimit, renditjen e ngjarjeve dhe freskinë, duke i krahasuar me një pamje të pavarur të gjurmimit. Një përgjigje e suksesshme e API-së ose një konfirmim i webhook-ut konfirmon vetëm një pjesë të këtij zinxhiri; vetëm kjo nuk provon se aplikacioni juaj ka marrë ngjarjen më të re të transportuesit.

Ky udhëzues është për zhvilluesit dhe ekipet e operacioneve përgjegjëse për dërgimin e të dhënave të gjurmimit në një sistem menaxhimi porosish, faqe të orientuar nga klientët, mjet mbështetjeje ose rrjedhë pune për njoftime. Qëllimi është të gjendet se ku një ngjarje mungoi ose ndryshoi, dhe më pas të vendoset nëse duhet të provohet përsëri përpunimi, të korrigjohet një hartëzim ose të pritet për informacion të ri nga transportuesi.
Përpara se të filloni: përcaktoni çfarë do të thotë “më i fundit”
Mbani të ndara tri kohë: kur transportuesi thotë se ndodhi një ngjarje, kur ofruesi juaj i gjurmimit e mori ose e ekspozoi atë dhe kur aplikacioni juaj e ruajti. Këto kohë mund të ndryshojnë. Një transportues mund të publikojë një skanim pas ngjarjes fizike, ndërsa integrimi juaj mund ta përpunojë edhe më vonë. Prandaj, ngjarja më e re sipas kohës së ndodhjes nuk është domosdoshmërisht regjistrimi i marrë më së fundmi.
Zgjidhni një pikë krahasimi përpara se të filloni hetimin. Në mënyrë ideale, përdorni faqen e gjurmimit të transportuesit ose një regjistrim tjetër të autorizuar të ofruar nga transportuesi për të njëjtën dërgesë. Nëse kjo nuk është e disponueshme, krahasoni aplikacionin tuaj me përgjigjen aktuale të API-së së ofruesit të gjurmimit. Ky krahasim më i ngushtë mund të përcaktojë nëse aplikacioni juaj përputhet me ofruesin; nuk mund të përcaktojë nëse ofruesi i ka tashmë të gjitha skanimet e transportuesit. Regjistroni kur e bëtë krahasimin, në mënyrë që një përditësim i mëvonshëm të mos e bëjë një rezultat të mëparshëm të duket jokonsistent.
1. Konfirmoni që të dyja sistemet i referohen së njëjtës dërgesë
Filloni me numrin e gjurmimit, transportuesin dhe çdo identifikues llogarie ose dërgese të përdorur nga integrimi juaj. Numrat e gjurmimit mund të mos jenë të mjaftueshëm për zgjidhjen e problemeve: një numër mund të jetë futur me gabim shtypi, të jetë lidhur me transportuesin e gabuar ose të jetë ripërdorur në një regjistrim të brendshëm pasi një porosi është redaktuar. Një numër porosie dhe një numër gjurmimi shërbejnë gjithashtu për qëllime të ndryshme. Një porosi mund të ketë disa pako, prandaj kontrollimi i statusit më të fundit të porosisë mund të fshehë një pako të vjetëruar.
- Gjeni numrin e saktë të gjurmimit dhe transportuesin e dërguar në API-në e gjurmimit.
- Konfirmoni se cili regjistrim i brendshëm i dërgesës ose pakos mori përgjigjen.
- Kontrolloni nëse dërgesa u zëvendësua, u nda, u anulua ose u rilidh pas regjistrimit.
- Krahasoni transportuesin dhe numrin e shfaqur në regjistrimin burimor me ato që shfaqen në aplikacionin tuaj.
Nëse identifikuesit nuk përputhen, mos e trajtoni më ndryshimin si vonesë sinkronizimi. Korrigjoni fillimisht lidhjen dhe më pas përsëritni krahasimin e ngjarjeve. Ruani mjaftueshëm identifikues në regjistrat diagnostikues për të gjurmuar një dërgesë, pa vendosur kredenciale të ndjeshme të llogarisë në këto regjistra.
2. Krahasoni kohët e ngjarjeve pa humbur kuptimin e tyre
Për çdo ngjarje kandidate më të fundit, regjistroni kohën e ndodhjes të raportuar nga transportuesi, zonën kohore ose zhvendosjen e deklaruar nëse ofrohet, si dhe kohët e marrjes dhe ruajtjes nga aplikacioni juaj. Shndërroni vulat kohore në një bazë të përbashkët kohore për krahasim, por ruani vlerën origjinale. RFC 3339 përcakton një format vule kohore në internet me informacion të qartë për zhvendosjen; është një referencë e dobishme kur hartoni fushat tuaja të vulave kohore. Megjithatë, nuk garanton që transportuesi ose ofruesi do të japë një zonë kohore për çdo ngjarje.
Një shfaqje vetëm e orës, një zonë lokale e supozuar ose një analizues që heq në heshtje zhvendosjen mund ta kalojë një ngjarje në një ditë tjetër kalendarike ose ta vendosë në rendin e gabuar. Kur burimi jep një orë lokale të paqartë, shënojeni krahasimin si të pasigurt në vend që të shpikni një çast të saktë UTC. Dalloni gjithashtu kohën e ndodhjes së ngjarjes nga koha e përgjigjes së API-së: një përgjigje e marrë tani mund të përmbajë në mënyrë të ligjshme një ngjarje që ka ndodhur më herët.
Shënoni kohën kur kontrolluat pamjen e transportuesit ose të ofruesit. Nëse burimi publikoi një skanim të ri pas kërkesës suaj API, ndryshimi midis dy pamjeve nuk dëshmon se kërkesa e mëparshme dështoi.
3. Kontrolloni ngarkesën e ngjarjes, jo vetëm statusin kryesor
Krahasoni përshkrimin, vendndodhjen, statusin ose kodin e transportuesit dhe çdo fushë përkatëse të dorëzimit të ngjarjes më të fundit me regjistrimin burimor. Një status i normalizuar si “në transit” mund të përmbledhë disa skanime të dallueshme. Nëse aplikacioni juaj ruan vetëm përmbledhjen, mund të duket i pandryshuar edhe pse ka mbërritur një ngjarje e re.
Inspektoni përgjigjen e papërpunuar të API-së ose trupin e ruajtur të webhook-ut aty ku e lejojnë rregullat tuaja të trajtimit të të dhënave. Më pas ndiqeni ngjarjen përmes analizimit, hartëzimit të fushave, ruajtjes dhe paraqitjes. Kërkoni fusha null që mbishkruhen nga vlera të parazgjedhura, kode statusi të papritura që bien në një kategori të përgjithshme, tekst të shkurtuar ose një ndërfaqe përdoruesi që shfaq vetëm lloje të zgjedhura ngjarjesh. Një mospërputhje e etiketës së statusit ndryshon nga një ngjarje që mungon: ajo tregon drejt logjikës së transformimit ose shfaqjes, jo drejt dorëzimit.
Mos nxirrni përfundimin e dorëzimit vetëm sepse një vendndodhje ose status tingëllon përfundimtar. Konfirmoni ngjarjen dhe fushat specifike mbi të cilat mbështetet rrjedha juaj e punës. Në të kundërt, një status i pandryshuar në nivel të lartë nuk provon se sinkronizimi është ndalur; një skanim i marrë rishtazi mund të hartohet në të njëjtën kategori. Regjistrimi juaj diagnostikues duhet të ruajë si ngjarjen burimore, ashtu edhe vlerën e shfaqur për përdoruesit.
4. Ndiqni mënyrën se si ngjarja arriti në aplikacionin tuaj
Nëse përdorni webhook-e, kontrolloni regjistrin e marrjes për dërgesën dhe ngjarjen përkatëse. Verifikoni që endpoint-i juaj e pranoi kërkesën, që mesazhi kaloi validimin dhe që përpunimi pasues përfundoi. Një përgjigje suksesi HTTP nga endpoint-i juaj nuk provon se një punonjës i mëvonshëm i radhës e ruajti ngjarjen. Nëse përpunimi është asinkron, shqyrtoni si kërkesën hyrëse, ashtu edhe rezultatin e punës.
Nëse kërkoni një API me polling, kontrolloni kërkesën e fundit të përfunduar, identifikuesin e dërgesës në atë kërkesë, përgjigjen e saj dhe çdo logjikë faqosjeje ose marrjeje që përdor integrimi juaj. Një kërkesë e suksesshme mund të pasohet ende nga një shkrim i dështuar në bazën e të dhënave ose nga leximi i një cache-i të vjetëruar. Përdorni dokumentacionin përkatës të ofruesit për të verifikuar fushat aktuale të përgjigjes, kërkesat e autentikimit dhe sjelljen e dorëzimit për integrimin tuaj, në vend që të supozoni se çdo API gjurmimi ndjek të njëjtën kontratë. Për një integrim me 17TRACK, pikat përkatëse të nisjes janë faqja Tracking API dhe dokumentacioni i API-së; konfirmoni sjelljen e dokumentuar për endpoint-in dhe metodën që përdorni.
Bëjeni përpunimin e ngjarjeve të sigurt për përsëritje. Një riprovim nuk duhet të krijojë skanime të dyfishta, të dërgojë në mënyrë të përsëritur të njëjtin njoftim klienti ose të zëvendësojë një gjendje të re të ruajtur me një ngarkesë më të vjetër. Çelësi i duplikimit varet nga fushat që ofruesi juaj jep realisht. Testoni çelësin e zgjedhur kundrejt ngjarjeve të dallueshme që rastësisht ndajnë një status ose vulë kohore; këto ngjarje nuk duhet të bashkohen vetëm sepse duken të ngjashme.
5. Verifikoni rregullat e renditjes dhe kalimit të gjendjes
Renditni ngjarjet e regjistruara sipas një rregulli të përcaktuar qartë dhe më pas inspektoni rezultatin. Shumë aplikacione duhet të dallojnë “ngjarjen më të fundit që ndodhi” nga “ngjarja më e fundit që morëm”. Një skanim i mëparshëm i vonuar mund të mbërrijë pas një skanimi më të ri. Nëse baza juaj e të dhënave thjesht e bën mesazhin e përpunuar së fundmi gjendjen aktuale të dërgesës, ai skanim i vonuar mund ta kthejë statusin e shfaqur prapa.
Krahasoni historikun e ruajtur me historikun burimor, jo vetëm fushën e vetme të statusit. Pyetni nëse një regjistrim i marrë rishtazi u shtua, u hodh poshtë si duplikat ose u lejua të përditësonte gjendjen aktuale. Kontrolloni çdo rregull që u jep përparësi ngjarjeve të caktuara ndaj të tjerave. Një rregull i tillë mund të jetë i qëllimshëm, por nuk duhet të fshehë ngjarjen bazë ose të nënkuptojë se transportuesi e anuloi një moment të rëndësishëm kur aplikacioni thjesht mori me vonesë një skanim më të vjetër.
Për një test praktik, merrni një dërgesë me më shumë se një ngjarje dhe riluajini mesazhet e saj në një rend tjetër mbërritjeje në një mjedis jo-produktiv. Konfirmoni që historiku i ngjarjeve mbetet i plotë dhe që statusi i shfaqur për klientin ndjek rregullin tuaj të dokumentuar. Kjo zbulon defekte renditjeje që një test normal, në rend, nuk mund t'i zbulojë.
6. Matni freskinë dhe harmonizoni përjashtimet
Në fund, krahasoni atë që dinte secila shtresë në të njëjtën pikë vëzhgimi: pamja e transportuesit, përgjigjja e ofruesit të gjurmimit, rezultati i webhook-ut hyrës ose i polling-ut, regjistrimi në bazën e të dhënave dhe rezultati i orientuar nga klienti. Shënoni shtresën e parë ku ngjarja e pritur zhduket. Ky kufi është më i dobishëm se një raport i përgjithshëm se “gjurmimi është i vonuar”.
Matni si moshën e ngjarjes më të fundit të raportuar nga transportuesi, ashtu edhe kohën që nga kontrolli ose marrja e fundit e suksesshme e të dhënave nga integrimi juaj. Ato u përgjigjen pyetjeve të ndryshme. Një pako mund të mos ketë skanim të ri nga transportuesi edhe pse integrimi juaj është në gjendje të mirë; ose transportuesi mund të shfaqë një skanim të ri ndërsa kërkesa juaj e fundit e suksesshme është e vjetër. Përdorni pragje alarmi që pasqyrojnë kërkesat tuaja operative dhe sjelljen që keni vërejtur. Mos u premtoni klientëve një interval fiks përditësimi nëse marrëveshjet tuaja me transportuesin dhe ofruesin nuk e mbështesin atë.
Krijoni një radhë të vogël harmonizimi për dërgesat, regjistrimet e të cilave ndryshojnë nga burimi i zgjedhur i krahasimit. Përfshini identifikuesit, ngjarjen që mungon ose nuk përputhet, vulat kohore përkatëse, shtresën e parë që dështoi dhe veprimin pasues. Për shembull, një ngjarje e pranishme në përgjigjen e ofruesit, por që mungon në bazën tuaj të të dhënave, kërkon hetim të integrimit. Një ngjarje e pranishme në bazën tuaj të të dhënave, por që mungon në faqen e gjurmimit, kërkon kontroll të shfaqjes ose cache-it. Nëse vetë transportuesi nuk shfaq skanim të ri, një kërkesë tjetër API nuk mund ta krijojë atë.
Testi operacional është i drejtpërdrejtë: a mund të identifikoni të njëjtën dërgesë, të gjeni ngjarjen më të fundit të njohur në burim dhe ta ndiqni atë ngjarje deri në pamjen e orientuar nga përdoruesi pa i ndryshuar kuptimin? Nëse jo, gjashtë kontrollet e ngushtojnë problemin në një kufi specifik dhe i japin ekipit tuaj një hap pasues të mbështetshëm.
FAQ
A do të thotë një përgjigje e suksesshme e webhook-ut se ngjarja më e fundit është sinkronizuar?
Jo. Ajo tregon se endpoint-i juaj ktheu një përgjigje të suksesshme ndaj një kërkese. Konfirmoni që validimi, përpunimi në radhë, ruajtja në bazën e të dhënave dhe shfaqja gjithashtu përfunduan me sukses. Kontrolloni ngarkesën për të përcaktuar se cilën ngjarje përmbante kërkesa.
Pse faqja e transportuesit shfaq një skanim më të ri se përgjigjja ime API?
Së pari konfirmoni që po shikoni të njëjtën pako dhe që të dyja vëzhgimet u bënë në kohë të krahasueshme. Publikimi nga transportuesi dhe marrja ose ekspozimi i një ngjarjeje nga ofruesi i gjurmimit mund të ndodhin në kohë të ndryshme. Nëse ndryshimi vazhdon, përdorni dokumentacionin dhe procesin e mbështetjes së ofruesit për të hetuar dërgesën specifike, në vend që të supozoni një garanci përditësimi.
A duhet të përdor vulën kohore të ngjarjes apo kohën kur sistemi im e mori atë për të zgjedhur statusin më të fundit?
Përdorni një rregull të dokumentuar të përshtatshëm për rrjedhën tuaj të punës dhe ruani të dyja vlerat. Vula kohore e ngjarjes përshkruan kur ndodhi aktiviteti i raportuar; koha e marrjes përshkruan kur sistemi juaj mësoi për të. Asnjëra fushë e vetme nuk zgjidh çdo rast, veçanërisht kur kohët burimore janë të paqarta ose skanimet e mëparshme mbërrijnë me vonesë.
Çfarë ndodh nëse statusi i API-së është i pandryshuar, por lista e ngjarjeve ka një hyrje të re?
Kjo mund të jetë e pritshme nëse disa ngjarje të transportuesit hartohen në një status të vetëm të normalizuar. Krahasoni detajet e ngjarjes dhe verifikoni që aplikacioni juaj e ruajti dhe e shfaq hyrjen e re aty ku duhet. Trajtojeni një ngjarje që mungon dhe një etiketë përmbledhëse të pandryshuar si çështje të ndryshme.
Burimet
- 17TRACK Tracking API — referencë produkti për integrimet e API-së së gjurmimit.
- 17TRACK API documentation — pikë reference për kontrollimin e kontratës së zbatueshme të integrimit.
- RFC 3339: Date and Time on the Internet: Timestamps — referencë për formatin e vulave kohore dhe zhvendosjes UTC.


