Ujasnite si úlohu a rozhodnutie
Táto príručka premení rýchly štart rozhrania API na prehľadný prevádzkový pracovný postup. Spája rozhodnutia o doméne, vlastníctvo, dôkazy a akceptovanie, takže výsledok naďalej funguje vo výrobe.
Pred pripojením CMS začnite s jednou overenou požiadavkou, overte platnosť zmluvy s odpoveďou a pridajte riešenie zlyhania.
Praktický postup
- 1
Typy zdrojov inventára, identifikátory, polia, miestne nastavenia, vlastníci a stavy publikácie.
- 2
Vyberte si vzor doručenia z objemu, latencie, redakčnej kontroly a tolerancie zlyhania.
- 3
Mapujte zdrojový záznam do samostatného záznamu jazykovej verzie s trvalým prepojením.
- 4
Pridajte autentifikáciu, idempotenciu, opakovanie, zrušenie platnosti vyrovnávacej pamäte, protokolovanie a riadenie prístupu.
- 5
Testovacia publikácia, zmeny zdroja, nedostupné výsledky, vrátenie späť, ovládanie klávesnice a monitorovanie pred vydaním.
Príklad alebo nástroj
Kompletný pár požiadaviek a odpovedí zahŕňa autentifikáciu, miestne nastavenie, režim, idempotenciu a spracovanie chýb. V nástroji tiež zaznamenajte základnú líniu, vlastníka, rozhodnutie, dôkazy, otvorený problém a dátum schválenia. Použite skutočnú stránku alebo transakciu, aby tím videl závislosti, výnimky a údržbu, ktorá nasleduje po vydaní.
| Rozhodovací bod | Záznam | Akceptačné kritérium |
|---|---|---|
| Základná línia | Pozorovaný aktuálny stav | Zdroj a dátum zaznamenania |
| rozhodnutie | Vybraná možnosť a zdôvodnenie | Zvážte riziko a publikum |
| Dôkazy | Testujte, dokumentujte alebo merajte | Kontrolovateľné a špecifické pre verziu |
| Schválenie | Meno, rola a dátum | Splnené všetky povinné kritériá |
Pošlite jednu požiadavku v tvare výroby
Vytvorte klienta integrácie na strane servera a uložte jeho poverenia v správcovi tajných informácií nasadenia. Odosielajte UTF-8 JSON cez HTTPS so stabilným identifikátorom zdroja, revíziou zdroja, požadovaným miestnym nastavením, jazykovým režimom a telom obsahu. Pridajte kľúč idempotencie, ktorý zostane rovnaký pri opakovanom pokuse o rovnakú úlohu. Nezverejňujte poverenia v kóde prehliadača, súboroch odkladacieho priestoru, poliach CMS, snímkach obrazovky alebo chybových odpovediach viditeľných pre klienta.
Začnite s reprezentatívnou, ale necitlivou stránkou služby. Zahrňte nadpisy, zoznamy, odkazy a právnu alebo prevádzkovú podmienku, aby odpoveď plnila skutočnú zmluvu o obsahu. Pred volaním API odmietnite prázdny identifikátor zdroja, nepodporované miestne nastavenie, neznámy režim, príliš veľké telo alebo zdeformovanú štruktúru. Nastavte explicitný časový limit pripojenia a odozvy a rozšírte identifikátor korelácie do denníkov vašej aplikácie.
| Pole žiadosti | Účel | Validácia |
|---|---|---|
| sourceId | Odolné prepojenie so záznamom CMS | Požadované, stabilné, neosobné |
| zdrojRevízia | Detekuje zastarané výsledky | Povinné a nemenné pre požiadavku |
| miestne nastavenie a režim | Vyberá jazykové pravidlá | Musí to byť povolená kombinácia |
| idempotencyKey | Zabezpečuje opakované pokusy | Rovnaká operácia používa rovnaký kľúč |
Overte úplnú zmluvu o odpovedi
Úspešný stav HTTP považujte len za prvú kontrolu. Overte schému odpovede, identifikátor výsledku, identifikátor a revíziu zdroja, miestne nastavenie, jazykový režim, stav spracovania, bloky obsahu, upozornenia a verziu modelu alebo sady pravidiel, ak sú dodané. Neznáme hodnoty výčtu a chýbajúce povinné polia by sa mali nepodariť uzavrieť do kontrolovateľnej chyby integrácie. Uchovajte upozornenia vedľa konceptu, pretože môžu identifikovať terminológiu, kvalitu zdroja alebo požiadavky na manuálnu kontrolu.
Uložte vygenerovaný výstup ako samostatný koncept revízie, a nie prepisovanie schváleného zdroja. Zaznamenajte identifikátory požiadavky a výsledkov, nastavenia transformácie, časové pečiatky a integritu hash zdrojovej revízie. Vykreslite rozdiel pre recenzentov a uniknúť celému výstupu podľa jeho cieľa. Vygenerované označenie je nedôveryhodným vstupom, kým sa nedokončí overenie schémy, dezinfekcia, kontroly dostupnosti a schválenie človekom.
- 1
Overte odchádzajúce užitočné zaťaženie podľa lokálnej schémy.
- 2
Odošlite požiadavku s overením, časovým limitom, idempotenciou a korelačnými hlavičkami.
- 3
Overte stav, hlavičky a telo odpovede oproti pripnutej zmluve.
- 4
Vytvorte samostatný koncept CMS spojený s presnou zdrojovou revíziou.
- 5
Nasmerujte upozornenia a rozdiely do správneho frontu redakčnej kontroly.
Riešte chyby bez duplikovania alebo straty práce
Časové limity opakovania, zlyhania pripojenia a limity rýchlosti iba vtedy, keď je operácia idempotentná. Použite obmedzené exponenciálne stiahnutie s jitterom a rešpektujte oneskorenie opakovania poskytnuté serverom. Nepokúšajte sa znova o zlyhania overenia, zlyhania overenia alebo nepodporované možnosti, kým sa nezmení konfigurácia. Umiestnite vyčerpané operácie do frontu nedoručených správ s odkazom na zdroj, kategóriou bezpečnej chyby, počtom pokusov a ďalším zodpovedným tímom.
Oddeľte stav pre používateľa od podrobností diagnostiky. Editori potrebujú jasné stavy, ako sú zaradené do frontu, spracovanie, pripravený koncept, požadovaná akcia a zlyhali s bezpečným ďalším krokom. Operácie potrebujú identifikátory požiadaviek, trvanie, kategóriu stavu a históriu opakovania, ale nie úplný zdrojový text v bežných protokoloch. Upozornenie na trvalú chybovosť, rastúci vek frontu, zlyhania autentifikácie, nezhody schém a koncepty, ktorých revízia zdroja sa zmenila počas spracovania.
Každá opakovaná operácia má stabilný kľúč idempotencie.
Backoff je obmedzený a rešpektuje inštrukcie limitu rýchlosti.
Protokoly nezahŕňajú poverenia a nepotrebné telá obsahu.
Položky s nedoručenou správou majú vlastníka a postup opakovania.
Zastaraný výsledok nemôže ticho nahradiť novšiu zdrojovú revíziu.
Pred vydaním overte integráciu
Otestujte platné požiadavky, každú zdokumentovanú chybu overenia, vypršané a odvolané poverenia, časové limity, limity sadzieb, duplicitné odoslanie, dokončenie mimo objednávky, vývoj schémy, sanitáciu a zmeny zdroja počas spracovania. Potvrďte, že monitorovanie identifikuje každé zlyhanie a že vyškolený operátor môže položku prehrať alebo zatvoriť bez úpravy databázy. Spustite prístupnosť a redakčnú kontrolu na vykreslenom koncepte, a nie iba na surovej odpovedi.
Vydanie s obmedzenými povereniami, definovanými limitmi sadzieb a výdavkov, informačnými panelmi, vlastníctvom upozornení a prepínačom vrátenia, ktorý zastaví novú generáciu bez ovplyvnenia publikovaného obsahu. Pripnite podporovanú verziu zmluvy a naplánujte kontrolu aktualizácie. Záznam o akceptácii výroby by mal obsahovať dôkaz o skúške, bezpečnostné schválenie, dokumentáciu toku údajov, odhlásenie kontrolórom, prevádzkové pokyny a úspešné obnovenie jednej zámerne neúspešnej úlohy.
Úlohy, dôkazy a schválenie
Generovanie uchovávajte oddelene od publikácie. Úspešná odpoveď je návrh, nie schválenie. Uložte identifikátor a verziu zdroja, nastavenia transformácie, identifikátor výsledku, stav recenzie, schvaľovateľa a čas zverejnenia. Keď sa zdroj zmení, namiesto tichého nahradenia schváleného obsahu označte jazykovú verziu na kontrolu. To umožňuje rollback a audit naprieč platformami.
Prevádzka a údržba
Publikovaním práca nekončí. Prepojte jazykovú verziu alebo konfiguráciu s jej zdrojom, monitorujte opatrenia na kvalitu a služby a definujte konkrétne spúšťače kontroly. Spúšťače zahŕňajú zmeny zdroja, právne zmeny, nové potreby publika, opakujúce sa otázky podpory, technické zmeny a incidenty. Pomenovaný vlastník vyhodnotí spúšťač, v prípade potreby otvorí novú revíziu a zaznamená obnovené schválenie.
Kontrolný zoznam na zverejnenie
Integrácia využíva trvalé identifikátory zdroja.
Poverenia sú uložené na strane servera a rotujú sa.
Časový limit, opakovanie a správanie pri obmedzení rýchlosti sú definované.
Opakované žiadosti sú idempotentné.
Vygenerovaný obsah prejde do stavu kontroly.
Zmeny zdroja znehodnotia alebo znova otvoria verziu.
Jazyková navigácia funguje pomocou klávesnice a asistenčnej technológie.
Monitorovanie pokrýva zlyhania, fronty, latenciu a zastaraný obsah.