Haku
gridsz
GRIDSZ
Ota yhteyttä
Pyydä esittely
GRIDSZ

Equitri-protokolla

Equitri on protokolla, jota GRIDSZ -kehys käyttää varmistaakseen, että samaa tehtävää työstävät osapuolet pysyvät synkronoituna. Se toimii Fulfillment (TASK)- ja Assurance (SERVICE)-sovellusliittymien taustalla, ja sen suunnittelussa on oletettu, että pitkäkestoisissa tehtävissä (jotka kestävät tyypillisesti yli päivän) päivitysten määrä on suhteellisen vähäinen. Tarkoituksellisesti yksinkertaisen sovellusrajapinnan takana Equitri piilottaa taustalla olevien järjestelmien, väliohjelmistojen, yön yli tapahtuvan eräkäsittelyn ja reaaliaikaisten järjestelmien monimutkaisuuden.

Jokaisen verkkoon liitetyn osapuolen on toteutettava sekä asiakasohjelma että palvelin: asiakasohjelma käynnistää päivitykset ja hakee tehtävätiedot toisen osapuolen palvelimelta, kun taas palvelin toimittaa tehtävätiedot toisen osapuolen asiakasohjelmalle (yleensä Gridsz). Luoja (InTask) ja vastaanottaja (OutTask) käyttävät eri sovellusrajapintoja (API), mutta niiden taustalla oleva protokolla on sama.

Kun tällä sivulla on ensin selostettu joitakin termejä ja itse protokollaa, esitellään seuraavaksi vaiheet molempiin suuntiin:

  • Gridsz uuden tehtävän tai päivittää olemassa olevan tehtävän
  • Integroitu järjestelmä, joka luo uuden tehtävän tai päivittää olemassa olevan tehtävän

Termit ”integroitu järjestelmä” ja ”sinä” viittaavat Equitrin käyttöönottavaan osapuoleen.

Tällä sivulla ei käsitellä http(s)-tason taustalla olevia yhteyksiä, VPN-verkkoja, välityspalvelimia jne., eikä siinä käsitellä tarkemmin sitä, miten osapuolen tulisi toimia vastaanotettujen tehtävätietojen suhteen. Vähimmäisvaatimuksena on, että integroitu järjestelmä pystyy käsittelemään Equitri-sovellusliittymän (INDICATION / FETCH / SYNC) molempiin suuntiin kelvollisella JSON-muodolla ja valtuutuksella, ottaen huomioon sekä normaali- että poikkeustilanteet.

Huomautus: FETCH-prosessia on mahdollista käsitellä erillään INDICATION- ja SYNC-prosesseista – eli kerätä tietoja päivittämättä tehtävää.

Sanasto

Lyhyt kuvaus käytetyistä termeistä.

Equitri

Nimi, joka on annettu GRIDSZ sovellusliittymissä käytetylle API-mekanismille. Tämä mekanismi koskee sekä täytäntöönpano- että varmistusvirtoja sekä luojan (InTask) että vastaanottajan (OutTask) sovellusliittymiä.

KÄYTTÖAIHE

INDICATION on Equitri-protokollan ensimmäinen viesti. Se on ”fire-and-forget”-tyyppinen POST-viesti, jossa ilmoitetaan yksinkertaisesti, että lähettäjän päätepisteestä on haettava tehtävä. Viestin rungon sisältö määrittää, mikä tehtävä on haettava ja mistä päätepisteestä. Kyseessä voi olla joko täysin uusi tehtävä tai olemassa olevan tehtävän päivitys.

FETCH

FETCH on Equitrin toinen viesti ja varsinainen ”voimaliike”. Yksinkertaisella HTTP GET -pyynnöllä oikeaan URL-osoitteeseen palautetaan koko tehtävän sisältö. FETCH-pyyntö voidaan suorittaa myös erillisenä kutsuna ilman edeltävää INDICATION-pyyntöä, jolloin se ei myöskään vaadi SYNC-pyyntöä.

SYNC

SYNC-viesti on Equitri-protokollan kolmas ja viimeinen viesti. Se on PUT-viesti, joka ilmoittaa, että tehtävä on käsitelty, eikä kyseisestä päivityksestä (versiosta) tule enää lähettää INDICATION-viestejä. SYNC-viesti sisältää myös selvennys- ja perustelukentän, joka täytetään, jos päivitys ei läpäise tietojen kelpoisuustarkistuksia.

Päivitysten lukumäärä

Tunnetaan myös nimellä ”versio”. Se määrittää, missä versiossa tietty tehtävä on tällä hetkellä. GRIDSZ versio on pääversio, ja se voi vain kasvaa tai pysyä samana (jos päivitys epäonnistuu).

Equitri-protokollan säännöt

Seuraavat yleiset säännöt ovat voimassa:

  1. Tässä asiakirjassa esiintyviä avainsanoja ”MUST”, ”MUST NOT”, ”REQUIRED”, ”SHALL”, ”SHALL NOT”, ”SHOULD”, ”SHOULD NOT”, ”RECOMMENDED”, ”MAY” ja ”OPTIONAL” on tulkittava RFC 2119 -standardissa kuvatulla tavalla.
  2. Tunnistamattomat HTTP-otsikot ohitetaan ilman erillistä ilmoitusta
  3. Kun osapuoli lähettää tehtävän toiselle osapuolelle ja heti sen jälkeen hakee kyseisen tehtävän samalta osapuolelta, vastaanotettu tehtävä sisältää täsmälleen samat tiedot kuin alkuperäinen.
  4. Kun saat tehtävää koskevan ILMOITUKSEN, et saa itse lähettää kyseistä tehtävää koskevaa ILMOITUSTA, ennen kuin olet ensin HAKENUT ja SYNKRONOINUT saapuneen ILMOITUKSEN
  5. Kun samasta tehtävästä vastaanotetaan useita päivityksiä, vain viimeisin päivitys (eli se, jolla on suurin updateCount-arvo) otetaan huomioon. Vanhat päivitykset ohitetaan.
  6. Tehtävä koskee aina yhtä TEHTÄVÄÄ yhdellä yhteydellä. Olemassa olevan tehtävän yhteyttä (DHid) ja tehtävätyyppiä (taskType) ei saa muuttaa.

Yritä uudelleen -malli

Asiat voivat mennä pieleen, ja niin myös tapahtuu jossain vaiheessa. Aina kun olemassa olevan tehtävän päivitys epäonnistuu, osapuolen on noudatettava uudelleenkäynnistysmenettelyä:

  • Ellei SYNC-viestiä lähetetä takaisin, vastapuoli lähettää INDICATION-viestejä loputtomiin.
  • Koska INDICATION-pyynnön vastaanottamista käytetään usein FETCH- ja SYNC-komentojen suorittamisen laukaisijana, kahden samaa tehtävää koskevan INDICATION-pyynnön välinen vähimmäisaika on 10 sekuntia, ja tuotantoympäristössä se on yleensä vähintään 1 minuutti.
  • Equitri-sovelluksissa voitaisiin toteuttaa asteittainen varmuuskopiointi, jossa kahden INDICATION-pyynnön välinen uudelleenkäynnistysaika pidentyy jokaisen pyynnön jälkeen, kunnes se on enintään yksi INDICATION-pyyntö neljän tunnin välein.

Kaikki INDICATON-pyynnöt, joissa tehtävän ja päivitysmäärän yhdistelmä on sama, kuuluvat samaan keskusteluun.

Tehtävien suhteellinen versiointi

On mahdollista, ja jopa todennäköistä, että jonkin tehtävän osapuolten järjestelmistä yksi tai useampi on ajoittain poissa käytöstä. Lisäksi osapuolilla on erilainen tahti reagoida tehtävän päivityksiin. Versiointiongelmien ehkäisemiseksi Equitri-tehtävällä on aina päivitysluku (updatecount). Päivitysluku toimii eräänlaisena versionumerona. Uuden tehtävän kohdalla sen on aina aloitettava kokonaisluvulla 1. Jokaisen päivityksen yhteydessä, jonka osapuoli välittää muille osapuolille, updateCount-arvoa on korotettava (vähintään) yhdellä verrattuna nykyiseen arvoon.
Kun updateCount-arvo on 500 tai enemmän, tehtävä on ajautunut (mahdollisesti loputtomaan) silmukkaan. Integroitu järjestelmä ei saa lähettää enää INDICATION-viestejä tälle tehtävälle, ja sen on varmistettava, että tilanne korjataan manuaalisesti.

UpdateCount on pienempi tai yhtä suuri kuin nykyinen updateCount

Tämä tapahtuu, kun toinen osapuoli lähettää päivityksen tehtävän aiempaan versioon. Toinen osapuoli oli todennäköisesti offline-tilassa eikä saanut tehtävän viimeisimpiä päivityksiä. GRIDSZversio tehtävästä toimii pääversiona.
Esimerkiksi kommentit, joita ei ollut integroidun järjestelmän versiossa, lisätään oikeassa järjestyksessä. Liitteitä voidaan lisätä. Jopa tehtävän tila voidaan päivittää, mutta vain, jos se ei ole ristiriidassa nykyisen tehtävän version tilan kanssa.
Yhdistämisen jälkeen järjestelmä suorittaa SYNC-toiminnon toisen osapuolen kanssa ilmoittaakseen, että tehtävän päivitys on vastaanotettu ja käsitelty. Synkronointia varten on tärkeää, että integroidulla järjestelmällä on sama updateCount kuin GRIDSZ tällä hetkellä olevalla versiolla. Jos synkronoidaan pienempi updateCount, INDICATION-viestin aloittaneen järjestelmän tulisi silti lähettää INDICATION-viestejä synkronoimattomalle uusimmalle updateCount-arvolle.
Tämän jälkeen integroitu järjestelmä voi aloittaa uuden muunnoksen, joka alkaa INDICATION-viestillä, jotta toinen osapuoli saadaan ajan tasalle tehtävän versiostasi.
Huomautus: GRIDSZ EI ole mahdollista GRIDSZ edelliseen versioon. Nykyinen versio on ja pysyy totuudena, vaikka toinen järjestelmä ei voisi sitä hyväksyä.

UpdateCount on suurempi kuin nykyinen UpdateCount

Tämä on ihannetilanne. Toinen osapuoli on tehnyt päivityksen ja on nyt päivitysten suhteen pidemmällä kuin toinen osapuoli. Tehtävän versio, jonka updateCount-arvo on pienempi, jää käytöstä. Ja vastaanotettu tehtävän versio (jonka updateCount-arvo on suurempi) toimii uutena ”totuutena”.
Tehtävänä on nyt yhdistää vastaanotettu tehtävä ja tallennettu tehtävä uudeksi johdonmukaiseksi versioksi. Useimmiten tämä voi olla yhtä yksinkertaista kuin vanhan tehtävän version korvaaminen haetulla versiolla. Tilanne monimutkaistuu, kun vastaanotettua päivitystä ei voida hyväksyä toisella puolella. Esimerkiksi jos GRIDSZ tehtävä lopetustilassa ja GRIDSZ vastaanottaa sitten integroidusta järjestelmästä päivityksen, joka palauttaa sen avoimeen tilaan.
Tässä tapauksessa GRIDSZ takaisin SYNC-viestin, johon GRIDSZ täytetty selvennys ja syy. Tämä tarkoittaa automaattisesti, että versiota ei hyväksytä ja että edellinen versio on edelleen voimassa. Koska GRIDSZ palata edelliseen versioon, kaikki SYNC-viestit, joiden updateCount-arvo on sama kuin nykyinen updateCount, katsotaan integroidun järjestelmän lähettämiksi SYNC-ok-viesteiksi, vaikka selvennys ja syy olisi täytetty.
Jos SYNC-viestiä ei lähetetä lainkaan, toinen järjestelmä käynnistää uudelleenkokeilumenettelyn ja jatkaa INDICATION-viestien lähettämistä. Näissä tilanteissa suositellaan selvittämään syy, miksi päivitystä ei hyväksytä. Jos kyseessä on odottamaton JSON-vastaus tai -arvo, on parasta ottaa yhteyttä GRIDSZ asiaa voidaan tutkia yhdessä tarkemmin.
Huomautus: GRIDSZ ei ole mahdollista GRIDSZ edelliseen versioon. Nykyinen versio on ja pysyy oikeana, vaikka toinen järjestelmä ei sitä hyväksyisikään.

Savutestien Support

Protokolla tukee valinnaista HTTP-otsikkoa nimeltägridsz”. Kun HTTP-otsikko esiintyy pyynnössä ja sen arvo on ”TRUE”, se on merkki siitä, että kyseinen keskustelu on osa testiä. Tyypillisesti tätä otsikkoa käytetään tuotantoympäristön savutesteissä. Se on käsiteltävä normaalisti, mutta mitään varsinaisia fyysisiä toimia ei tule suorittaa. Equitri-protokollaa toteuttavia osapuolia kannustetaan ottamaan käyttöön vianmääritystason lokitallennus, joka laukeaa tämängridsz perusteella.

Tavallinen tehtävä (joka on luotu ilmangridszotsikkoa) ja joka vastaanottaa päivityksen, jossa ongridszotsikko, on syy huoleen. Mahdollisesti testitehtävät ja tavalliset tehtävät sekoittuvat keskenään. Testitehtävä (luotugridsz), joka vastaanottaa päivityksen ilmangridsz, ei aiheuta huolta. Mahdollisesti vastapuoli ei support .
Testitehtävien käytössä tuotantoympäristössä on noudatettava varovaisuutta. Varmista, että kaikki osapuolet ovat samalla linjalla, jotta vältetään todellisen työn fyysinen suorittaminen.

GRIDSZ : olemassa olevan tehtävän GRIDSZ tai uuden tehtävän luominen

Tämä jakautuu kolmeen vaiheeseen: saapuva ilmoituspyyntö (Gridsz integroitua järjestelmää), hakupyyntö (integroitu järjestelmä toimittaa tietoja Gridsz) sekä synkronointi vahvistusta varten.

1. Saapuvan viestin ilmaisin

Gridsz esittämä ilmoitus:

  1. Hyväksy pyyntö toteutuksen yhteydessä sovitun mukaisesti Gridsz tallennettujen valtuutustietojen perusteella Gridsz saattaa edellyttää OAuth 2.0 -tunnisteiden keräämistä)
  2. (Josgridsz-otsikon arvo on ”TRUE”, ota virheenkorjauslokitus käyttöön)
  3. Lue updateCount-arvo INDICATION-kohdasta
  4. (Voisiko: kirjata lokiin ”vastaanotettu päivityskehotus updatecount tehtävän tunnukselle taskId organisaation tunnuksesta orgId”)
  5. Tallenna tieto siitä, että tehtävälle on saatavilla päivitys, seuraavien tietojen avulla:
    • orgId (pakollinen)
    • systemId (pakollinen)
    • taskId (pakollinen)
    • updateCount (pakollinen)
    • x-request-id (voisi),
    • x-korrelaatio-tunnus (voisi olla)
    • pyyntöaika (voisi)
    • gridsztestin arvo (pakollinen, jos määritetty)
  6. Poista samalle orgId- ja taskId-tunnukselle kuuluvat aiemmat päivitystiedot, joiden updatecount-arvo on pienempi

2. Lähetettävä haku

HGridsz Gridszista:

  1. Määritä kutsuttava päätepiste INDICATION-kohdassa olevien ympäristön, orgId:n ja taskId:n perusteella
  2. (Lue x-gridz-test-arvo ja, jos se löytyy, asetagridsz-otsikon arvoksi kyseinen arvo)
  3. suorita FETCH-pyyntö päätepisteeseen; hae uuden tehtävän tiedot
  4. Tarkista, ovatko tehtävätiedot oikeassa muodossa:
    • Kelvollinen JSON-muotoinen data, joka noudattaa uusimman API-version avoimen API-määrittelyn vaatimuksia
    • Kelvollinen JSON-muotoinen data, joka läpäisee liiketoimintatarkistukset
  5. Jos tehtävä ei ole oikein muotoiltu: selvitä syy ja ota Gridsz yhteyttä Gridsz
    Huomautus: GRIDSZ INDICATION-viestien lähettämistä, kunnes SYNC-viesti on lähetetty
    (PROESSIN LOPPU)
  6. Jos tiedot ovat oikeassa muodossa:
    • Lukitse tehtävä tehtävätallennustilaan
    • Lue vanhoja tehtävätietoja tehtävätietokannasta
    • Yhdistä vanhat ja uudet tehtävätiedot
    • Jos yhdistämisen tulos eroaa vanhoista tehtävätiedoista, tallenna yhdistetyt tehtävätiedot tehtävätietokantaan
    • Avaa tehtävä tehtävävarastosta
  7. Lähetä SYNC-komento päätepisteeseen.

3. Lähetettävien tietojen synkronointi

Vahvistettava synkronointi:

  1. Lähetä SYNC-pyyntö FETCH-päätepisteeseen
  2. SYNC-viestille ei ole uudelleenkäynnistystä. Jos pyyntö tai vastaus epäonnistuu, voit kirjata lokiin poikkeuksen sekä mahdolliset virhekoodit ja selitykset, jotka on annettu synkronointiviestissä. Luota vastapuolen uudelleenkäynnistysmenettelyyn, kun yrität uudelleen.
  3. Poista ilmoituksen aikana tallennetut päivitystiedot

Integroitu järjestelmä, joka päivittää olemassa olevan tehtävän tai luo uuden tehtävän

Tämä jakautuu jälleen kolmeen vaiheeseen: tietopyyntö (integroitu järjestelmä Gridszlle), hakupyyntö (Gridsz tietoja integroidusta järjestelmästä) ja synkronointi vahvistusta varten.

1. Lähetysilmoitus

Integroitu järjestelmä havaitsee muutoksen (joka ei johtunut Gridsz edellisessä Gridsz ) ja haluaa ilmoittaa Gridsz lähettämällä Gridsz ilmoituksen:

  1. Vahvista pyyntö toteutuksen yhteydessä sovitulla tavalla (saattaa edellyttää OAuth 2.0 -tunnisteen keräämistä)
  2. (Josgridsz-otsikon arvo on ”TRUE”, ota virheenkorjauslokitus käyttöön)
  3. Lisää 1 integroidun järjestelmän olemassa olevaan tehtävätietueeseen tallennettuun updateCount-arvoon (käytä arvoa 1 uusille tehtäville)
  4. (Voisiko: kirjata lokiin ”lähetetään päivitysilmoitus updateCount:lle tehtävän tunnuksella taskId organisaatiotunnuksesta orgId”)
  5. Lähetä Gridsz ilmoitus, Gridsz seuraavat tiedot:
    • orgId (pakollinen)
    • systemId (pakollinen)
    • taskId (pakollinen)
    • updateCount (pakollinen)
    • x-request-id (voisi),
    • x-korrelaatio-tunnus (voisi olla)
    • pyyntöaika (voisi)
    • gridsztestin arvo (pakollinen, jos määritetty)

Älä odota vastausta tai yritä lukea sitä. Älä yritä käsitellä poikkeuksia, vaan luota uudelleenkäynnistysmekanismiin, joka yrittää uudelleen.

2. Saapuva haku

Gridsz edellisessä vaiheessa annettuun ohjeeseen hakemalla tehtävän sovitusta päätepisteestä:

  1. Vastaa päätelaitteeseen saapuvaan puheluun sovitun todennusmenettelyn mukaisesti
  2. (Lue x-gridz-test-arvo ja, jos se löytyy, asetagridsz-otsikon arvoksi kyseinen arvo)
  3. Palauta 404-virhekoodi, jos tehtävää ei löydy integroidusta järjestelmästä
  4. Toimita FETCH-tiedot lataamalla ja muotoilemalla tehtävätiedot integroidusta järjestelmästä

3. Saapuva synkronointi

Gridsz edellisessä vaiheessa saadut tiedot ja lähettää PUT-pyynnön päätepisteeseen synkronoinnin vahvistamiseksi:

  1. Käsittele todennettu SYNC-pyyntö FETCH-päätelaitteeseen
  2. Kun SYNC-tiedostossa on syy ja selvennys kentät täytettyinä, se tarkoittaa, että GRIDSZ hyväksynyt päivitystä ja että edellinen versio on edelleen pääversio

Indication-Fetch-Sync-prosessi ei välttämättä aina suju täydellisesti, mutta protokollan tulisi yrittää uudelleen sujuvasti edellä kuvatulla tavalla. Synkronointivaiheesta saatavat syykoodit ja selvennykset tulisi kuitenkin käsitellä asianmukaisesti (ja ilmoittaa käyttäjille), jotta vältytään loputtomilta silmukoilta.