Jūsų pirmoji „Tracking API“ užklausa: REST kliento naudojimo su Postman ir Curl vadovas
Norėdami pateikti pirmąją sekimo API užklausą, REST kliente sukonfigūruokite galinį tašką, autentifikavimo antraštę ir JSON turinį, išsiųskite užklausą ir patikrinkite HTTP būseną bei atsakymo turinį. Šiame vadove naudojama 17TRACK Tracking API, kad būtų parodyta ta pati darbo eiga naudojant Postman ir curl: užregistruoti siuntą, paprašyti jos sekimo informacijos ir patikrinti, ar rezultatas paruoštas naudoti jūsų programoje.
Tikslas – nedidelis, atkuriamas integracijos testas, o ne paruošimas naudoti gamybinėje aplinkoje. Jums reikės API kredencialo ir sekimo numerio, kurį turite teisę apdoroti. Toliau pateiktose komandose naudojamas v2.2 galinio taško šablonas; prieš vykdydami jas patvirtinkite galinio taško versiją ir konkrečiai paskyrai taikomus reikalavimus 17TRACK API dokumentacijoje.
Supraskite, ką turi atlikti jūsų pirmoji užklausa
Siuntos sekimo integracija apima du atskirus aspektus: nurodyti paslaugai, kurią siuntą sekti, ir gauti su ta siunta susijusią sekimo informaciją. Šiame pavyzdyje tai yra atskiros užklausos. Registracija nereiškia, kad siunta jau pajudėjo, o sėkminga registracija negarantuoja, kad vežėjo įvykiai bus prieinami iš karto.
Pirmajam testui naudokite vieną siuntą, o ne paketą siuntų. Taip lengviau atskirti autentifikavimo klaidas, neteisingus sekimo numerius ir atsakymo interpretavimą. Pirmasis naudingas etapas nėra vien „gavau HTTP 200“. Tai yra „API priėmė numatytą operaciją ir galiu paaiškinti siuntos lygio rezultatą“.
Postman suteikia vaizdinę sąsają užklausoms redaguoti ir atsakymams tikrinti. curl leidžia tą patį HTTP apsikeitimą atkuriamai vykdyti terminale. Nė vienas iš jų nekeičia API autentifikavimo taisyklių, siuntos duomenų ar apdorojimo elgsenos. Naudokite tą įrankį, kuris padeda aiškiau ištirti užklausą, o tada veikiančią konfigūraciją atkurkite kitame įrankyje.
Paruoškite kredencialą, siuntą ir užklausos informaciją
Prieš atidarydami bet kurį klientą, surinkite toliau nurodytą informaciją:
- Įgaliotas API kredencialas: gaukite jį atlikdami 17TRACK API paskyros sąranką. Vartotojo sekimo sesija nepakeičia API kredencialo.
- Realus sekimo numeris: naudokite jums priklausančią arba prieigai leidžiamą siuntą. Neseniai aktyvi siunta paprastai yra naudingesnė nei išgalvotas numeris testuojant tikrus sekimo duomenis.
- Vežėjas, jei žinomas: turėkite vežėjo pavadinimą diagnostikai. Jei jūsų atveju reikalingas vežėjo identifikatorius, naudokite API dokumentacijoje nurodytą reikšmę ir lauką, o ne spėliokite.
- Dabartinė užklausos sutartis: patvirtinkite API versiją, autentifikavimo antraštę, užklausos schemą ir visus paskyros apribojimus.
- Saugi darbo vieta: nedėkite kredencialų, klientų duomenų ar visų sekimo atsakymų į viešas saugyklas, ekrano kopijas ar bendrinamus pagalbos pranešimus.
Minimalūs užklausų pavyzdžiai naudoja šiuos nustatymus:
| Nustatymas | Pavyzdinė konfigūracija |
|---|---|
| Base URL | https://api.17track.net/track/v2.2 |
| Registracijos operacija | POST /register |
| Sekimo informacijos operacija | POST /gettrackinfo |
| Autentifikavimo antraštė | 17token: YOUR_API_TOKEN |
| Turinio formatas | Content-Type: application/json, su JSON masyvu, kuriame yra siuntų objektai |
Sekimo numerius laikykite eilutėmis. Pakeitus vieną į skaitinį tipą gali būti pašalinti priekiniai nuliai arba kitaip pakeista jo reikšmė. Toliau esantį vietos rezervavimo ženklą YOUR_TRACKING_NUMBER reikia pakeisti tikros bandomosios siuntos numeriu; tai nėra veikiantis pavyzdinis numeris.
Pateikite registracijos užklausą naudodami Postman
1. Sukurkite nedidelę testavimo aplinką
Postman sukurkite aplinką su trimis kintamaisiais: base_url, tracking_token ir tracking_number. Nustatykite base_url į pirmiau nurodytą pagrindinį URL, o kituose kintamuosiuose įrašykite kredencialą ir siuntos numerį. Prieš siųsdami užklausą pasirinkite šią aplinką.
Naudokite Postman prieinamus slaptų duomenų tvarkymo valdiklius ir patikrinkite, ką jūsų darbo sritis bendrina arba sinchronizuoja. Vertės paslėpimas sąsajoje nepakeičia prieigos kontrolės. Neeksportuokite užpildytų kredencialų kartu su kolekcija, skirta kolegoms ar viešai dokumentacijai.
2. Sukonfigūruokite metodą, URL ir antraštes
Sukurkite HTTP užklausą, pasirinkite POST ir kaip URL įveskite {{base_url}}/register. Skirtuke „Headers“ pridėkite:
17token: {{tracking_token}}
Content-Type: application/json
Šiame pavyzdyje kredencialas turi būti pasirinktinėje 17token antraštėje. Nepakeiskite jos „Bearer“ žetono konfigūracija vien todėl, kad kitame API naudojamas toks šablonas. Taip pat patikrinkite, ar paveldėti kolekcijos nustatymai neprideda nenumatytos „Authorization“ antraštės.
3. Pridėkite JSON turinį
Atidarykite „Body“, pasirinkite „raw“, tada pasirinkite JSON. Įveskite:
[
{
"number": "{{tracking_number}}"
}
]
Išoriniai laužtiniai skliaustai yra svarbūs: šioje užklausoje naudojamas masyvas, nors jame yra tik viena siunta. Naudokite dvigubas kabutes, pašalinkite kablelius gale ir JSON kode nenaudokite komentarų. Jei dokumentacijoje jūsų vežėjui ar siuntai reikalinga papildoma informacija, prieš siųsdami pridėkite dokumentacijoje nurodytus laukus.
4. Išsiųskite užklausą ir patikrinkite rezultatą
Spustelėkite „Send“. Pirmiausia patikrinkite, ar apskritai gavote HTTP atsakymą. DNS klaida, TLS klaida, tarpinio serverio problema ar skirtasis laikas skiriasi nuo atsakymo, kuriame nurodoma, kad užklausa neteisinga. Tada patikrinkite atsakymo turinį, ar jame yra operacijos rezultatas ir siuntos lygio priėmimo arba atmetimo informacija.
Išsaugokite užklausą pavadinimu „Register test shipment“. Užrašykite HTTP būseną, API rezultatą ir klaidos pranešimą, tačiau nekopijuokite žetono. Jei registracija nepavyksta, išspręskite šią problemą prieš tęsdami. Pakartotinis nepakitusios užklausos siuntimas apsunkina diagnostiką ir gali naudoti paskyros išteklius.
Atkurkite užklausą naudodami curl
Toliau pateiktose komandose naudojamas POSIX tipo apvalkalas, pavyzdžiui, Bash arba Zsh. PowerShell ir Windows Command Prompt taiko kitokias kabučių bei kintamųjų taisykles. PowerShell aplinkoje, jei reikia, naudokite curl.exe, kad iškviestumėte curl vykdomąjį failą, o ne konkrečiam apvalkalui skirtą komandos pseudonimą.
Nustatykite pagrindinį URL ir įkelkite kredencialą į aplinkos kintamąjį naudodami įprastą slaptų duomenų tvarkymo procesą:
export TRACKING_BASE_URL='https://api.17track.net/track/v2.2'
# Set TRACKING_API_TOKEN securely before continuing.
Aplinkos kintamasis neleidžia kredencialui patekti į pakartotinai naudojamą pavyzdį, tačiau tai nėra visa slaptų duomenų valdymo sistema. Vietiniam testavimui venkite įvesti tikrą žetoną į komandą, kurią išsaugos apvalkalo istorija. Automatizavimui naudokite platformos slaptų duomenų saugyklą ir apribokite žurnalų išvestį.
Sukurkite failą pavadinimu shipment.json ir pakeiskite vietos rezervavimo ženklą bandomosios siuntos sekimo numeriu:
[
{
"number": "YOUR_TRACKING_NUMBER"
}
]
Išsiųskite registracijos užklausą:
curl --request POST \
--url "$TRACKING_BASE_URL/register" \
--header "17token: $TRACKING_API_TOKEN" \
--header 'Content-Type: application/json' \
--data-binary @shipment.json \
--connect-timeout 10 \
--max-time 30 \
--silent --show-error \
--output register-response.json \
--write-out 'HTTP status: %{http_code}\n'
Tai išsaugo atsakymo turinį faile register-response.json ir atskirai išveda HTTP būseną. Prisijungimo ir bendrojo laiko apribojimai yra vietinio testavimo pasirinkimai, o ne 17TRACK paslaugos garantijos. Atidarykite išsaugotą failą ir patikrinkite API rezultatą; vien būsenos eilutės nepakanka.
curl gali sėkmingai užbaigti perdavimą net tada, kai serveris grąžina HTTP klaidos atsakymą. Ir atvirkščiai, dėl perdavimo klaidos gali nepavykti gauti tinkamo API atsakymo. Kurdami scenarijus, atskirai tvarkykite curl išėjimo būseną, HTTP būseną ir programos lygio rezultatą.
Paprašykite siuntos sekimo informacijos
Patvirtinę registraciją, nukopijuokite Postman užklausą ir pakeiskite URL į {{base_url}}/gettrackinfo. Palikite POST metodą, autentifikavimo antraštę, turinio tipą ir siuntos turinį. Išsaugokite ją atskirai, kad netyčia iš naujo neužregistruotumėte siuntos, kai norite gauti duomenis.
Lygiavertė curl užklausa:
curl --request POST \
--url "$TRACKING_BASE_URL/gettrackinfo" \
--header "17token: $TRACKING_API_TOKEN" \
--header 'Content-Type: application/json' \
--data-binary @shipment.json \
--connect-timeout 10 \
--max-time 30 \
--silent --show-error \
--output tracking-response.json \
--write-out 'HTTP status: %{http_code}\n'
Nemanykite, kad naujai užregistruota siunta iš karto grąžins visą įvykių istoriją. Duomenų prieinamumas priklauso nuo siuntos ir paslaugos apdorojimo. Jei informacija dar neprieinama, vadovaukitės dokumentuota gavimo ir atnaujinimo tvarka, o ne nuolat registruokite tą patį numerį arba vykdykite dažną apklausos ciklą.
Skaitykite atsakymą trimis lygiais
- Perdavimas: ar klientas prisijungė ir gavo HTTP atsakymą?
- Operacija: ar API priėmė užklausą ir ar atskira siunta buvo apdorota sėkmingai?
- Siuntos informacija: ar grąžinti duomenys identifikuoja numatytą siuntą ir ką iš tikrųjų patvirtina jos būsena arba įvykių istorija?
Naudodami oficialią atsakymo schemą raskite būsenos, vežėjo ir įvykių laukus. Išlaikykite skirtumą tarp normalizuotos siuntos būsenos ir originalaus vežėjo įvykio aprašymo. Sėkminga paieška neįrodo, kad siunta pristatyta, o trūkstami įvykiai neįrodo, kad siunta prarasta.
Saugodami laiko žymas išsaugokite pateiktą laiko juostą arba poslinkio informaciją. Nerūšiuokite neapdorotų datos eilučių iš skirtingų formatų manydami, kad jos sudaro teisingą chronologinę seką. Taip pat atskirkite laiką, kai jūsų programa gavo įrašą, nuo laiko, kai įvyko siuntos įvykis.
Šalinkite problemas nekeisdami visko iš karto
- Nėra atsakymo: patikrinkite pagrindinio kompiuterio pavadinimą, tinklo prieigą, tarpinio serverio nustatymus, TLS konfigūraciją ir vietinį skirtąjį laiką. Įprastai neišjunkite sertifikatų tikrinimo.
- Autentifikavimo klaida: patvirtinkite, kad žetonas aktyvus, yra
17tokenantraštė ir pasirinkta Postman aplinka teisingai išsprendžia kintamąjį. Patikrinkite, ar nėra atsitiktinių tarpų. - Neteisinga užklausa: pagal dokumentaciją patikrinkite API versiją, operacijos kelią, POST metodą, turinio tipą ir JSON masyvo struktūrą.
- Siunta atmesta: perskaitykite konkrečios siuntos klaidą. Patikrinkite numerį ir būtiną vežėjo informaciją, o ne laikykite kiekvieną atmetimą autentifikavimo problema.
- Nėra sekimo įvykių: patvirtinkite registraciją ir numatytą siuntos tapatybę. Patikrinkite, ar reikia vežėjo informacijos ir ar atnaujinimai prieinami prieš bandydami dar kartą.
- Postman veikia, bet curl neveikia: palyginkite išspręstą URL, tikrąsias antraštes ir turinio baitus. Apvalkalo kabutės ir nenustatyti aplinkos kintamieji dažnai lemia užklausų skirtumus.
Vienam testui keiskite vieną kintamąjį ir trumpai užrašykite rezultatą. Jei tikrinate Postman konsolę arba naudojate išsamią curl išvestį, laikykite ją jautria informacija: užklausos antraštės gali atskleisti kredencialus. Prieš dalindamiesi diagnostika pašalinkite slaptus duomenis ir klientų informaciją.
Žinokite, kada vadovas baigtas
Reikšmingą pirmąjį integracijos testą atlikote tada, kai abu klientai siunčia numatytą užklausą, registracija yra suprasta, gavimas grąžina interpretuojamą rezultatą ir galite atskirti API klaidą nuo siuntos, apie kurią nėra naujos informacijos. Vienodi HTTP būsenos kodai neįrodo, kad abu klientai veikė identiškai.
Prieš perkeldami darbo eigą į programą, laikykite kredencialus serveryje, tikrinkite įvestis ir naudokite struktūrizuotą klaidų tvarkymą. Peržiūrėkite savo paskyrai taikomus dokumentuotus spartos, paketų, pakartotinių bandymų ir atnaujinimų teikimo apribojimus. Nemanykite, kad po skirtojo laiko registraciją saugu aklai kartoti: serveris galėjo apdoroti užklausą, nors klientas negavo atsakymo.
Pridėkite testus neteisingam kredencialui, netinkamam JSON, neteisingam siuntos numeriui, jau užregistruotai siuntai, nepasiekiamiems sekimo duomenims ir tinklo skirtajam laikui. Kiekvienas atvejis turi lemti sąmoningai pasirinktą programos rezultatą, o ne neapdorotą išimtį ar klaidinantį klientui rodomą statusą.
DUK
Ar galiu testuoti neturėdamas tikro sekimo numerio?
Naudodami neteisingą reikšmę galite patikrinti tam tikrą užklausos validavimo elgseną, tačiau tai nepatvirtina siuntos sekimo. Norėdami testuoti tikrus įvykius, naudokite įgaliotą siuntą arba dokumentuotą testinį objektą, jei paslauga tokį teikia. Nemanykite, kad atsitiktiniai pavyzdiniai numeriai priklauso smėliadėžei.
Kodėl HTTP 200 atsakyme vis tiek yra klaida?
HTTP būsena ir programos rezultatai aprašo skirtingus lygius. Serveris gali sėkmingai gauti ir apdoroti užklausą, kartu nurodydamas, kad atskira siunta buvo atmesta. Skaitykite atsakymo turinį ir dokumentuotą siuntos lygio rezultatą, o ne tik HTTP būseną.
Kodėl sekimo informacijai gauti naudojamas POST?
Naudokite galinio taško sutartyje nurodytą metodą. Šis gavimo pavyzdys priima siuntų identifikatorius JSON užklausos turinyje per POST. Pakeitus jį į GET vien todėl, kad operacija nuskaito duomenis, dokumentuota užklausa nebebus išlaikyta.
Ar turėčiau API žetoną įdėti į naršyklės JavaScript?
Neįterpkite privataus API kredencialo į viešai pateikiamą frontend kodą. Nukreipkite užklausas per įgaliotą backend, kuris apsaugo kredencialą, tikrina įvestis ir kontroliuoja, kurią siuntos informaciją gali pasiekti kiekvienas naudotojas.
Ar gamybai reikia ir Postman, ir curl?
Ne. Tai naudingi testavimo ir diagnostikos įrankiai. Gamybinė programa gali naudoti tinkamą HTTP klientą. Išsaugokite nuasmenintą Postman užklausą arba curl komandą kaip atkuriamą nuorodą be galiojančio žetono ir nereikalingų klientų duomenų.
Šaltiniai
- 17TRACK API documentation — autentifikavimo, galinių taškų sutarčių, užklausos laukų, atsakymo interpretavimo ir integracijos reikalavimų nuoroda.
- Postman documentation: Send API requests — užklausų konfigūravimas ir atsakymų tikrinimas.
- Postman documentation: Variables — kintamaisiais pagrįsta užklausų konfigūracija.
- curl manual — antraščių, užklausos turinio, skirtųjų laikų, išsaugotų atsakymų ir HTTP būsenos išvesties komandų parinktys.


