JSON -RPC - JSON-RPC

JSON-RPC on etäproseduurikutsun protokolla koodattu JSON . Se on samanlainen kuin XML-RPC- protokolla, joka määrittää vain muutamia tietotyyppejä ja komentoja. JSON-RPC mahdollistaa ilmoitusten (palvelimelle lähetetyt tiedot, jotka eivät vaadi vastausta) ja useiden puhelujen lähettämisen palvelimelle, joihin voidaan vastata asynkronisesti.

Historia

Versio Kuvaus Päivätty
1.0 Alkuperäinen versio 2005
1.1 WD Työskentelyluonnos . Lisää nimettyjä parametreja, lisää erityisiä virhekoodeja ja lisää introspection -toimintoja. 2006-08-07
1.1 Vaihtoehto Ehdotus yksinkertaiseksi JSON-RPC: ksi 1.1 . Vaihtoehtoinen ehdotus 1.1 WD: lle. 2007-05-06
1.1 Kohteen määrittely Kohteen määritys . Vaihtoehtoinen ehdotus versioon 1.1 WD/1.1ALT. 2007-07-30
1.2 Ehdotus . Tämän asiakirjan myöhempi versio nimettiin uudelleen versioon 2.0. 2007-12-27
2.0 Erittelyehdotus 2009-05-24
2.0 (tarkistettu) Erittely 2010-03-26

Käyttö

JSON-RPC toimii lähettämällä pyynnön palvelimelle, joka toteuttaa tämän protokollan. Tässä tapauksessa asiakas on tyypillisesti ohjelmisto, joka aikoo soittaa yksittäiselle etäjärjestelmän menetelmälle. Useita syöttöparametreja voidaan välittää etämenetelmälle matriisina tai objektina, kun taas itse menetelmä voi palauttaa myös useita lähtötietoja. (Tämä riippuu toteutetusta versiosta.)

Kaikki siirtotyypit ovat yksittäisiä objekteja, jotka on sarjoitettu JSON: n avulla. Pyyntö on puhelu tiettyyn etäjärjestelmän tarjoamaan menetelmään. Se voi sisältää kolme jäsentä:

  • method- Merkkijono, jolla on kutsuttavan menetelmän nimi. Menetelmien nimet, jotka alkavat "rpc". on varattu rpc-internal -menetelmille.
  • params- Objekti tai joukko arvoja, jotka välitetään parametreina määritellylle menetelmälle. Tämä jäsen voidaan jättää pois.
  • id- Merkkijono tai murtoluku, jota käytetään vastaamaan vastausta pyyntöön, johon se vastaa. Tämä jäsen voidaan jättää pois, jos vastausta ei palauteta.

Pyynnön vastaanottajan on vastattava pätevästi kaikkiin vastaanotettuihin pyyntöihin. Vastaus voi sisältää alla mainitut jäsenet.

  • result- Kutsutulla menetelmällä palautetut tiedot. Tämä elementti on muotoiltu JSON-stat-objektiksi. Jos menetelmää kutsuttaessa tapahtui virhe, tätä jäsentä ei saa olla olemassa.
  • error- Virheobjekti, jos menetelmää kutsuttaessa tapahtui virhe, muuten tätä jäsentä ei saa olla olemassa. Esineen sisältää jäseniä koodi (kokonaisluku), ja viesti (string). Valinnainen tiedot jäsen voi sisältää muita palvelin-erityisiä tietoja. On olemassa ennalta määritettyjä virhekoodeja, jotka seuraavat XML-RPC: lle määritettyjä virhekoodeja.
  • id - Sen pyynnön tunnus, johon se vastaa.

Koska on tilanteita, joissa vastausta ei tarvita tai edes halutaan, ilmoitukset otettiin käyttöön. Ilmoitus on samanlainen kuin pyyntö, paitsi tunnus, jota ei tarvita, koska vastausta ei palauteta. Tässä tapauksessa idominaisuus tulee jättää pois (versio 2.0) tai olla null(versio 1.0).

Esimerkkejä

Näissä esimerkeissä -->tarkoittaa palvelulle lähetettyjä tietoja ( pyyntö ), kun taas <--palveluista tulevia tietoja. Vaikka <--sitä kutsutaan usein vastaukseksi asiakas-palvelin-laskennassa, se ei JSON-RPC-versiosta riippuen välttämättä tarkoita vastausta pyyntöön .

Versio 2.0

Pyyntö ja vastaus: 

--> {"jsonrpc": "2.0", "method": "subtract", "params": {"minuend": 42, "subtrahend": 23}, "id": 3}
<-- {"jsonrpc": "2.0", "result": 19, "id": 3}

Ilmoitus (ei vastausta): 

--> {"jsonrpc": "2.0", "method": "update", "params": [1,2,3,4,5]}

Versio 1.1 (Working Draft)

Pyyntö ja vastaus: 

--> {"version": "1.1", "method": "confirmFruitPurchase", "params": [["apple", "orange", "mangoes"], 1.123], "id": "194521489"}
<-- {"version": "1.1", "result": "done", "error": null, "id": "194521489"}

Versio 1.0

Pyyntö ja vastaus: 

--> {"method": "echo", "params": ["Hello JSON-RPC"], "id": 1}
<-- {"result": "Hello JSON-RPC", "error": null, "id": 1}

Katso myös

Viitteet

  1. ^ "tekniset tiedot - JSON -RPC - Trac" . Arkistoitu alkuperäisestä päälle 2008-05-17 . Haettu 2008-05-14 .
  2. ^ "JSON-RPC 2.0 -määritys" . id: Asiakkaan määrittämä tunniste, joka TÄYTYY sisältää merkkijonon, numeron tai NULL -arvon, jos se sisältyy. Jos se ei sisälly siihen, sen oletetaan olevan ilmoitus. Arvo ei normaalisti saisi olla tyhjä ja numerot EI saisi sisältää murto -osia
  3. ^ "JSON-RPC 2.0 -määritys" . Ilmoitus on pyyntöobjekti ilman "id" -jäsentä. Pyyntöobjekti, joka on ilmoitus, osoittaa, että asiakas ei ole kiinnostunut vastaavasta vastausobjektista, eikä vastausobjektia tarvitse palauttaa asiakkaalle. Palvelin EI saa vastata ilmoitukseen, mukaan lukien ne, jotka sisältyvät eräpyyntöön. Ilmoituksia ei voida määritelmän mukaan vahvistaa, koska niillä ei ole palautettavaa vastausobjektia. Näin ollen Asiakas ei olisi tietoinen virheistä (kuten "Virheelliset parametrit", "Sisäinen virhe").
  4. ^ "JSON-RPC 2.0 -määritys" . tulos: Tämä jäsen vaaditaan menestykseen. Tätä jäsentä EI saa olla olemassa, jos menetelmää kutsuttaessa tapahtui virhe. Tämän jäsenen arvo määräytyy palvelimella käytetyllä menetelmällä.
  5. ^ "JSON-RPC 2.0 -määritys" . virhe: Tämä jäsen vaaditaan virheen vuoksi. Tätä jäsentä EI saa olla olemassa, jos kutsun aikana ei tapahtunut virhettä. Tämän jäsenen arvon TÄYTYY olla objekti, kuten kohdassa 5.1 on määritelty.
  6. ^ "JSON-RPC 2.0 -määritys" . Virheobjekti: Kun rpc -puhelu kohtaa virheen, vastausobjektin PITÄÄ sisältää virhejäsenen, jonka arvo on objekti, jossa on seuraavat jäsenet: (koodi) - Numero, joka ilmaisee tapahtuneen virhetyypin. Tämän PITÄÄ olla kokonaisluku. (viesti) - Jono, joka antaa lyhyen kuvauksen virheestä. Viesti PITÄISI rajoittaa yhteen ytimeen. (data) - Primitiivinen tai strukturoitu arvo, joka sisältää lisätietoja virheestä. Tämä voidaan jättää pois. Tämän jäsenen arvon määrittää palvelin (esim. Yksityiskohtaiset virhetiedot, sisäkkäiset virheet jne.).

Ulkoiset linkit