Selvitä tehtävä ja päätös
Tämä opas muuttaa api-pikakäynnistyksen tarkastettavaksi työnkuluksi. Se yhdistää verkkotunnuksen päätökset, omistajuuden, todisteet ja hyväksynnän, jotta tulos toimii edelleen tuotannossa.
Aloita yhdestä todistetusta pyynnöstä, vahvista vastaussopimus ja lisää virheiden käsittely ennen CMS:n yhdistämistä.
Käytännön työnkulku
- 1
Varaston lähdetyypit, tunnisteet, kentät, alueet, omistajat ja julkaisutilat.
- 2
Valitse toimitusmalli äänenvoimakkuuden, latenssin, toimituksellisen ohjauksen ja virhetoleranssin joukosta.
- 3
Yhdistä lähdetietue erilliseksi kieliversiotietueeksi kestävällä linkityksellä.
- 4
Lisää todennus, idempotenssi, uudelleenyritys, välimuistin mitätöinti, lokikirjaus ja pääsynhallinta.
- 5
Testijulkaisu, lähdemuutokset, tulokset, joita ei ole saatavilla, palautus, näppäimistön käyttö ja valvonta ennen julkaisua.
Esimerkki tai työkalu
Täydellinen pyyntö- ja vastauspari sisältää todennuksen, kielen, tilan, idempotenssin ja virheiden käsittelyn. Tallenna työkaluun myös lähtökohta, omistaja, päätös, todisteet, avoin kysymys ja hyväksymispäivä. Käytä oikeaa sivua tai tapahtumaa, jotta tiimi näkee riippuvuudet, poikkeukset ja julkaisua seuraavat ylläpitotyöt.
| Päätöskohta | Tallentaa | Hyväksymiskriteeri |
|---|---|---|
| Perustaso | Havaittu nykytila | Lähde ja tallennuspäivämäärä |
| Päätös | Valittu vaihtoehto ja perustelut | Riski ja yleisö huomioitu |
| Todisteet | Testaa, dokumentoi tai mittaa | Tarkastettava ja versiokohtainen |
| Hyväksyminen | Nimi, rooli ja päivämäärä | Kaikki pakolliset kriteerit täyttyivät |
Lähetä yksi tuotantomuotoinen pyyntö
Luo palvelinpuolen integrointiasiakas ja tallenna sen tunnistetiedot käyttöönoton salaisuuden hallintaan. Lähetä UTF-8 JSON HTTPS:n kautta vakaan lähdetunnisteen, lähdeversion, pyydetyn kielialueen, kielitilan ja sisällön rungon kanssa. Lisää idempotenssiavain, joka pysyy samana, kun identtistä työtä yritetään uudelleen. Älä paljasta valtuustietoja selainkoodissa, arkistotiedostoissa, CMS-kentissä, kuvakaappauksissa tai asiakkaan näkyvissä virhevastauksissa.
Aloita edustavalta, mutta ei-arkaluonteiselta palvelusivulta. Sisällytä otsikot, luettelot, linkit ja oikeudellinen tai toiminnallinen ehto, jotta vastaus noudattaa todellista sisältösopimusta. Hylkää tyhjä lähdetunniste, ei-tuettu kielialue, tuntematon tila, ylisuuri runko tai virheellinen rakenne ennen API:n kutsumista. Aseta eksplisiittinen yhteyden ja vastauksen aikakatkaisu ja levitä korrelaatiotunniste sovelluslokeihisi.
| Pyyntökenttä | Tarkoitus | Validointi |
|---|---|---|
| lähdetunnus | Kestävä linkki CMS-levyyn | Pakollinen, vakaa, ei-henkilökohtainen |
| lähdeVersio | Tunnistaa vanhentuneet tulokset | Pakollinen ja muuttumaton pyynnöstä |
| alue ja tila | Valitsee kielisäännöt | On oltava käytössä oleva yhdistelmä |
| idempotencyKey | Tekee uudelleenyrityksistä turvallisia | Sama toiminto käyttää samaa avainta |
Vahvista täydellinen vastaussopimus
Käsittele onnistunutta HTTP-tilaa vain ensimmäisenä tarkistuksena. Vahvista vastausskeema, tuloksen tunniste, lähteen tunniste ja versio, alue, kielitila, käsittelyn tila, sisältölohkot, varoitukset ja malli- tai sääntöversio, jos ne toimitetaan. Tuntemattomien enum-arvojen ja puuttuvien pakollisten kenttien pitäisi epäonnistua sulkeutuessaan tarkistettavaksi integrointivirheeksi. Säilytä varoitukset luonnoksen viereen, koska ne voivat tunnistaa terminologian, lähteen laadun tai manuaalisen tarkistuksen vaatimukset.
Tallenna luotu tulos erillisenä luonnoksena hyväksytyn lähteen korvaamisen sijaan. Tallenna pyyntö- ja tulostunnisteet, muunnosasetukset, aikaleimat ja lähdeversion eheyshajautus. Luo erotus arvioijille ja pakota kaikki tulosteet määränpään mukaan. Luotu merkintä on epäluotettava syöttö, kunnes skeeman validointi, puhdistus, käytettävyystarkistukset ja ihmisen hyväksyntä on suoritettu.
- 1
Vahvista lähtevä hyötykuorma paikallista mallia vastaan.
- 2
Lähetä pyyntö todennus-, aikakatkaisu-, idempotenssi- ja korrelaatiootsikoilla.
- 3
Vahvista tila, otsikot ja vastauksen runko kiinnitettyä sopimusta vastaan.
- 4
Luo erillinen CMS-luonnos, joka on linkitetty tarkkaan lähdeversioon.
- 5
Ohjaa varoitukset ja erot oikeaan toimitukselliseen arvostelujonoon.
Käsittele virheitä kopioimatta tai menettämättä työtä
Yritä uudelleen aikakatkaisuja, yhteyshäiriöitä ja nopeusrajoituksia vain, kun toiminto on idempotentti. Käytä rajoitettua eksponentiaalista perääntymistä värinän kanssa ja kunnioita palvelimen tarjoamaa uudelleenyritysviivettä. Älä yritä uudelleen vahvistusvirheitä, todennusvirheitä tai ei-tuettuja vaihtoehtoja, ennen kuin kokoonpanoa muutetaan. Aseta loppuun käytetyt toiminnot kuolleiden kirjainten jonoon lähdeviittauksen, turvallisen virheluokan, yritysmäärän ja seuraavan vastuullisen tiimin kanssa.
Erota käyttäjälle suunnattu tila diagnostisista tiedoista. Toimittajat tarvitsevat selkeitä tiloja, kuten jonossa, käsittelyssä, luonnos valmis, toimenpiteitä vaaditaan ja epäonnistui turvallisen seuraavan vaiheen avulla. Toiminnot tarvitsevat pyyntötunnisteet, keston, tilaluokan ja uudelleenyrityshistorian, mutta eivät tavallisten lokien koko lähdetekstiä. Varoitus jatkuvasta virheprosentista, kasvavasta jonon iästä, todennusvirheistä, skeeman yhteensopimattomuudesta ja luonnoksista, joiden lähdeversio muuttui käsittelyn aikana.
Jokaisella uudelleen yritettävällä toiminnolla on vakaa idempotenssiavain.
Backoff on rajoitettu ja noudattaa nopeusrajoitusohjeita.
Lokit eivät sisällä kirjautumistietoja ja tarpeettomia sisältörunkoja.
Kuolleiden kirjeiden lähetyksillä on omistaja ja uusintamenettely.
Vanhentunut tulos ei voi hiljaa korvata uudempaa lähdeversiota.
Todista integrointi ennen julkaisua
Testaa kelvollisia pyyntöjä, jokaista dokumentoitua vahvistusvirhettä, vanhentuneita ja peruutettuja valtuustietoja, aikakatkaisuja, nopeusrajoituksia, lähetyksen kaksoiskappaleita, virheellistä valmistumista, skeeman kehitystä, desinfiointia ja lähteen muutoksia käsittelyn aikana. Varmista, että valvonta tunnistaa jokaisen vian ja että koulutettu käyttäjä voi toistaa tai sulkea kohteen ilman tietokannan muokkausta. Suorita esteettömyys ja toimituksellinen tarkistus renderoidulle luonnokselle pelkän raaka vastauksen sijaan.
Julkaise rajoitetuilla tunnistetiedoilla, määritellyillä korko- ja kulutusrajoilla, kojelaudoilla, varoitusomistuksella ja palautuskytkimellä, joka pysäyttää uuden sukupolven vaikuttamatta julkaistuun sisältöön. Kiinnitä tuettu sopimusversio ja ajoita päivityksen tarkistus. Tuotannon hyväksymistietueen tulee sisältää testitodisteet, turvallisuushyväksyntä, tietovirran dokumentaatio, tarkastajan allekirjoitus, käyttöohjeet ja yhden tahallisesti epäonnistuneen työn onnistunut palauttaminen.
Roolit, todisteet ja hyväksyntä
Pidä sukupolvi erillään julkaisusta. Onnistunut vastaus on luonnos, ei hyväksyntä. Tallenna lähteen tunniste ja versio, muunnosasetukset, tuloksen tunniste, tarkistuksen tila, hyväksyjä ja julkaisuaika. Kun lähde muuttuu, merkitse kieliversio tarkistettavaksi sen sijaan, että korvaisit hyväksytyn sisällön hiljaa. Tämä mahdollistaa palautuksen ja tarkastuksen eri alustoilla.
Käyttö ja huolto
Työ ei lopu julkaisuun. Linkitä kieliversio tai kokoonpano sen lähteeseen, seuraa laatu- ja palvelutoimenpiteitä ja määritä konkreettisia tarkistuskäynnistimiä. Triggereitä ovat lähteen muutokset, lakimuutokset, uudet yleisötarpeet, toistuvat tukikysymykset, tekniset muutokset ja tapaukset. Nimetty omistaja arvioi triggerin, avaa tarvittaessa uuden version ja kirjaa uusitun hyväksynnän.
Julkaisun tarkistuslista
Integraatiossa käytetään kestäviä lähdetunnisteita.
Tunnistetiedot tallennetaan palvelinpuolelle ja niitä kierretään.
Aikakatkaisu, uudelleenyritys ja nopeusrajoitus on määritelty.
Toistuvat pyynnöt ovat idempotentteja.
Luotu sisältö siirtyy tarkistustilaan.
Lähteen muutokset mitätöivät version tai avaavat sen uudelleen.
Kielinavigointi toimii näppäimistön ja aputekniikan avulla.
Valvonta kattaa viat, jonot, latenssin ja vanhentuneen sisällön.