JSON-RPC - JSON-RPC

JSON-RPC to protokół zdalnego wywoływania procedur zakodowany w JSON . Jest podobny do protokołu XML-RPC , definiując tylko kilka typów danych i poleceń. JSON-RPC pozwala na wysyłanie powiadomień (dane wysyłane do serwera, które nie wymagają odpowiedzi) oraz wysyłanie wielu wywołań do serwera, na które można odpowiedzieć asynchronicznie.

Historia

Wersja Opis Przestarzały
1,0 Orginalna wersja 2005
1,1 WD Projekt roboczy . Dodaje nazwane parametry, dodaje określone kody błędów i dodaje funkcje introspekcji. 2006-08-07
1.1 Alt Propozycja prostego JSON-RPC 1.1 . Alternatywna propozycja do 1.1 WD. 2007-05-06
1.1 Specyfikacja obiektu Specyfikacja obiektu . Alternatywna propozycja dla 1.1 WD/1.1ALT. 2007-07-30
1.2 Propozycja . Późniejsza wersja tego dokumentu została przemianowana na 2.0. 2007-12-27
2,0 Propozycja specyfikacji 2009-05-24
2.0 (Poprawione-) Specyfikacja 2010-03-26

Stosowanie

JSON-RPC działa poprzez wysyłanie żądania do serwera implementującego ten protokół. Klientem w tym przypadku jest zazwyczaj oprogramowanie, które zamierza wywołać pojedynczą metodę zdalnego systemu. Wiele parametrów wejściowych można przekazać do metody zdalnej jako tablicę lub obiekt, podczas gdy sama metoda może również zwrócić wiele danych wyjściowych. (To zależy od zaimplementowanej wersji.)

Wszystkie typy transferu to pojedyncze obiekty, serializowane przy użyciu formatu JSON. Żądanie to wywołanie określonej metody dostarczonej przez system zdalny. Może zawierać trzech członków:

  • method- String z nazwą metody, która ma zostać wywołana. Nazwy metod zaczynające się od „rpc”. są zarezerwowane dla wewnętrznych metod RPC.
  • params— Obiekt lub tablica wartości, które mają zostać przekazane jako parametry do zdefiniowanej metody. Ten członek może zostać pominięty.
  • id— Ciąg znaków lub liczba nieułamkowa używana do dopasowania odpowiedzi do żądania, na które odpowiada. Ten element członkowski może zostać pominięty, jeśli odpowiedź nie powinna zostać zwrócona.

Odbiorca żądania musi odpowiedzieć prawidłową odpowiedzią na wszystkie otrzymane żądania. Odpowiedź może zawierać członków wymienionych poniżej.

  • result- Dane zwrócone przez wywołaną metodę. Ten element jest sformatowany jako obiekt JSON-stat. Jeśli wystąpił błąd podczas wywoływania metody, ten element członkowski nie może istnieć.
  • error- Obiekt błędu, jeśli wystąpił błąd podczas wywoływania metody, w przeciwnym razie ten element członkowski nie może istnieć. Obiekt musi zawierać kod członków (integer) i komunikat (string). Opcjonalny członek danych może zawierać dalsze dane specyficzne dla serwera. Istnieją predefiniowane kody błędów, które są zgodne z kodami zdefiniowanymi dla XML-RPC.
  • id – identyfikator żądania, na które odpowiada.

Ponieważ zdarzają się sytuacje, w których odpowiedź nie jest potrzebna, a nawet pożądana, wprowadzono powiadomienia. Powiadomienie jest podobne do żądania, z wyjątkiem identyfikatora, który nie jest potrzebny, ponieważ nie zostanie zwrócona żadna odpowiedź. W takim przypadku idwłaściwość powinna zostać pominięta (Wersja 2.0) lub być null(Wersja 1.0).

Przykłady

W tych przykładach -->oznacza dane wysłane do usługi ( request ), natomiast <--oznacza dane pochodzące z usługi. Chociaż <--często nazywa się to odpowiedzią w obliczeniach klient-serwer, w zależności od wersji JSON-RPC niekoniecznie oznacza odpowiedź na żądanie .

Wersja 2.0

Prośba i odpowiedź: 

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

Powiadomienie (brak odpowiedzi): 

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

Wersja 1.1 (wersja robocza)

Prośba i odpowiedź: 

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

Wersja 1.0

Prośba i odpowiedź: 

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

Zobacz też

Bibliografia

  1. ^ "specyfikacja - JSON-RPC - Trac" . Zarchiwizowane od oryginału w dniu 2008-05-17 . Źródło 2008-05-14 .
  2. ^ „Specyfikacja JSON-RPC 2.0” . id: Identyfikator ustalony przez Klienta, który MUSI zawierać ciąg, liczbę lub wartość NULL, jeśli jest uwzględniona. Jeśli nie jest uwzględniony, przyjmuje się, że jest to powiadomienie. Wartość POWINNA normalnie nie być zerem, a liczby NIE POWINNY zawierać części ułamkowych
  3. ^ „Specyfikacja JSON-RPC 2.0” . Powiadomienie to obiekt żądania bez elementu „id”. Obiekt Request, który jest Powiadomieniem, oznacza brak zainteresowania Klienta odpowiednim obiektem Response i jako taki obiekt Response nie musi być zwracany do klienta. Serwer NIE MOŻE odpowiadać na Powiadomienie, w tym na te, które znajdują się w żądaniu zbiorczym. Powiadomienia nie są z definicji potwierdzane, ponieważ nie mają obiektu Response do zwrócenia. W związku z tym Klient nie byłby świadomy żadnych błędów (np. „Nieprawidłowe parametry”, „Błąd wewnętrzny”).
  4. ^ „Specyfikacja JSON-RPC 2.0” . wynik: Ten członek jest WYMAGANY w przypadku sukcesu. Ten element NIE MOŻE istnieć, jeśli wystąpił błąd podczas wywoływania metody. Wartość tego elementu członkowskiego jest określana przez metodę wywołaną na serwerze.
  5. ^ „Specyfikacja JSON-RPC 2.0” . błąd: ten członek jest WYMAGANY w przypadku błędu. Ten członek NIE MOŻE istnieć, jeśli podczas wywoływania nie wystąpił błąd. Wartość dla tego członka MUSI być Obiektem zgodnie z definicją w sekcji 5.1.
  6. ^ „Specyfikacja JSON-RPC 2.0” . Obiekt błędu: Gdy wywołanie RPC napotka błąd, obiekt odpowiedzi MUSI zawierać element błędu o wartości będącej obiektem z następującymi elementami: (kod) — liczba wskazująca typ błędu, który wystąpił. MUSI to być liczba całkowita. (komunikat) - String zawierający krótki opis błędu. Wiadomość POWINNA być ograniczona do jednego zwięzłego zdania. (dane) — wartość pierwotna lub strukturalna, która zawiera dodatkowe informacje o błędzie. Można to pominąć. Wartość tego członka jest definiowana przez serwer (np. szczegółowe informacje o błędach, błędy zagnieżdżone itp.).

Zewnętrzne linki