XML-RPC - szybki przewodnik

RPC to skrót od Remote Procedure Call. Jak sama nazwa wskazuje, jest to mechanizm wywołujący procedurę lub funkcję dostępną na zdalnym komputerze. RPC to znacznie starsza technologia niż sieć. W efekcie RPC zapewnia programistom mechanizm definiowania interfejsów, które mogą być wywoływane przez sieć. Te interfejsy mogą być tak proste, jak pojedyncze wywołanie funkcji lub złożone, jak duży interfejs API.

Co to jest XML-RPC?

XML-RPC jest jednym z najprostszych i najbardziej niezawodnych podejść do usług sieciowych, które ułatwia komputerom wywoływanie procedur na innych komputerach.

XML-RPC umożliwia programom wykonywanie wywołań funkcji lub procedur w sieci.
XML-RPC używa protokołu HTTP do przekazywania informacji z komputera klienckiego do serwera.
XML-RPC używa małego słownictwa XML do opisu natury żądań i odpowiedzi.
Klient XML-RPC określa nazwę procedury i parametry w żądaniu XML, a serwer zwraca błąd lub odpowiedź w odpowiedzi XML.
Parametry XML-RPC to prosta lista typów i treści - struktury i tablice są najbardziej złożonymi dostępnymi typami.
XML-RPC nie ma pojęcia obiektów ani mechanizmu dołączania informacji, które wykorzystują inne słownictwo XML.
Jednak dzięki XML-RPC i usługom sieciowym sieć WWW staje się zbiorem połączeń proceduralnych, w których komputery wymieniają informacje ściśle powiązanymi ścieżkami.
XML-RPC pojawił się na początku 1998 roku; został opublikowany przez UserLand Software i początkowo zaimplementowany w ich produkcie Frontier.

Dlaczego XML-RPC?

Jeśli potrzebujesz zintegrować wiele środowisk obliczeniowych, ale nie musisz bezpośrednio udostępniać złożonych struktur danych, przekonasz się, że XML-RPC umożliwia szybkie i łatwe nawiązywanie komunikacji.

Nawet jeśli pracujesz w jednym środowisku, może się okazać, że podejście RPC ułatwia łączenie programów, które mają różne modele danych lub oczekiwania dotyczące przetwarzania, oraz zapewnia łatwy dostęp do logiki wielokrotnego użytku.

XML-RPC to doskonałe narzędzie do nawiązywania różnorodnych połączeń między komputerami.
XML-RPC oferuje integratorom możliwość korzystania ze standardowego słownictwa i podejścia do wymiany informacji.
Najbardziej oczywistym obszarem zastosowania XML-RPC jest łączenie różnych rodzajów środowisk, umożliwiając Javie komunikację z Perlem, Pythonem, ASP i tak dalej.

Przegląd techniczny XML-RPC

XML-RPC składa się z trzech stosunkowo małych części:

XML-RPC data model : Zestaw typów używanych do przekazywania parametrów, zwracanych wartości i błędów (komunikatów o błędach).
XML-RPC request structures : Żądanie HTTP POST zawierające informacje o metodzie i parametrach.
XML-RPC response structures : Odpowiedź HTTP zawierająca zwracane wartości lub informacje o błędzie.

W następnych trzech rozdziałach przestudiujemy wszystkie te trzy elementy.

Specyfikacja XML-RPC definiuje sześć podstawowych typów danych i dwa złożone typy danych, które reprezentują kombinacje typów.

Podstawowe typy danych w XML-RPC

Rodzaj	Wartość	Przykłady
int lub i4	32-bitowe liczby całkowite od - 2,147 483648 do 2 147 483 647.	<int> 27 </int> <i4> 27 </i4>
podwójnie	64-bitowe liczby zmiennoprzecinkowe	<double> 27.31415 </double> <double> -1,1465 </double>
Boolean	prawda (1) lub fałsz (0)	<boolean> 1 </boolean> <boolean> 0 </boolean>
strunowy	Tekst ASCII, chociaż wiele implementacji obsługuje Unicode	<string> Witaj </string> <string> zwariowany! @ </string>
dateTime.iso8601	Daty w formacie ISO8601: CCRRMMDDTHH: MM: SS	<dateTime.iso8601> 20021125T02: 20: 04 </dateTime.iso8601> <dateTime.iso8601> 20020104T17: 27: 30 </dateTime.iso8601>
base64	Informacje binarne zakodowane jako Base 64, zgodnie z definicją w RFC 2045	<base64> SGVsbG8sIFdvcmxkIQ == </base64>

Te podstawowe typy są zawsze zawarte w elementach wartości . Łańcuchy (i tylko łańcuchy) mogą być zawarte w elemencie wartości , ale pomijać element string . Te podstawowe typy można łączyć w dwa bardziej złożone typy, tablice i struktury. Tablice reprezentują informacje sekwencyjne, podczas gdy struktury reprezentują pary nazwa-wartość, podobnie jak tabele skrótów, tablice asocjacyjne lub właściwości.

Tablice są wskazywane przez element tablicy , który zawiera element danych zawierający listę wartości. Podobnie jak inne typy danych, element tablicy musi być ujęty w element wartości . Na przykład poniższa tablica zawiera cztery ciągi:

<value>
   <array>
      <data>
         <value><string>This </string></value>
         <value><string>is </string></value>
         <value><string>an </string></value>
         <value><string>array.</string></value>
      </data>
   </array>
</value>

Poniższa tablica zawiera cztery liczby całkowite:

<value>
   <array>
      <data>
         <value><int>7</int></value>
         <value><int>1247</int></value>
         <value><int>-91</int></value>
         <value><int>42</int></value>
      </data>
   </array>
</value>

Tablice mogą również zawierać mieszanki różnych typów, jak pokazano tutaj:

<value>
   <array>
      <data>
         <value><boolean>1</boolean></value>
         <value><string>Chaotic collection, eh?</string></value>
         <value><int>-91</int></value>
         <value><double>42.14159265</double></value>
      </data>
   </array>
</value>

Tworzenie wielowymiarowych tablic jest proste - wystarczy dodać tablicę wewnątrz tablicy:

<value>
   <array>
      <data>
		
         <value>
            <array>
               <data>
                  <value><int>10</int></value>
                  <value><int>20</int></value>
                  <value><int>30</int></value>
               </data>
            </array>
         </value>
			
         <value>
            <array>
               <data>
                  <value><int>15</int></value>
                  <value><int>25</int></value>
                  <value><int>35</int></value>
               </data>
            </array>
         </value>
			
      </data>
   </array>
</value>

Prosta struktura może wyglądać następująco:

<value>
   <struct>
      <member>
         <name>givenName</name>
         <value><string>Joseph</string></value>
      </member>
		
      <member>
         <name>familyName</name>
         <value><string>DiNardo</string></value>
      </member>
		
      <member>
         <name>age</name>
         <value><int>27</int></value>
      </member>
   </struct>
</value>

W ten sposób możesz zaimplementować prawie wszystkie typy danych obsługiwane przez dowolny język programowania.

Żądania XML-RPC to połączenie treści XML i nagłówków HTTP. Treść XML wykorzystuje strukturę typowania danych do przekazywania parametrów i zawiera dodatkowe informacje identyfikujące wywoływaną procedurę, podczas gdy nagłówki HTTP zapewniają otokę do przekazywania żądania przez sieć WWW.

Każde żądanie zawiera pojedynczy dokument XML, którego elementem głównym jest element methodCall . Każdy element methodCall zawiera element methodName i element params . Element methodName identyfikuje nazwę procedury, która ma zostać wywołana, natomiast element params zawiera listę parametrów i ich wartości. Każdy element params zawiera listę elementów param, które z kolei zawierają elementy wartości .

Na przykład, aby przekazać żądanie do metody o nazwie circleArea , która przyjmuje parametr Double (dla promienia), żądanie XML-RPC wyglądałoby następująco:

<?xml version="1.0"?>
<methodCall>
   <methodName>circleArea</methodName>
      <params>
         <param>
            <value><double>2.41</double></value>
         </param>
      </params>
</methodCall>

Nagłówki HTTP dla tych żądań będą odzwierciedlać nadawców i zawartość. Podstawowy szablon wygląda następująco:

POST /target HTTP 1.0
User-Agent: Identifier
Host: host.making.request
Content-Type: text/xml
Content-Length: length of request in bytes

Na przykład, jeśli metoda circleArea była dostępna z serwera XML-RPC nasłuchującego w / xmlrpc , żądanie może wyglądać następująco:

POST /xmlrpc HTTP 1.0
User-Agent: myXMLRPCClient/1.0
Host: 192.168.124.2
Content-Type: text/xml
Content-Length: 169

Po złożeniu całe żądanie wyglądałoby następująco:

POST /xmlrpc HTTP 1.0
User-Agent: myXMLRPCClient/1.0
Host: 192.168.124.2
Content-Type: text/xml
Content-Length: 169
<?xml version="1.0"?>
<methodCall>
   <methodName>circleArea</methodName>
      <params>
         <param>
            <value><double>2.41</double></value>
         </param>
      </params>
</methodCall>

To zwykłe żądanie HTTP ze starannie skonstruowanym ładunkiem.

Odpowiedzi są bardzo podobne do próśb, z kilkoma dodatkowymi zwrotami akcji. Jeśli odpowiedź się powiedzie - procedura została znaleziona, wykonana poprawnie i zwróciła wyniki - wówczas odpowiedź XML-RPC będzie wyglądać podobnie do żądania, z tą różnicą, że element methodCall zostanie zastąpiony elementem methodResponse i nie ma elementu methodName :

<?xml version="1.0"?>
<methodResponse>
   <params>
      <param>
         <value><double>18.24668429131</double></value>
      </param>
   </params>
</methodResponse>

Odpowiedź XML-RPC może zawierać tylko jeden parametr.
Ten parametr może być tablicą lub strukturą, więc możliwe jest zwrócenie wielu wartości.
W odpowiedzi zawsze wymagane jest zwrócenie wartości. „Wartość sukcesu” - być może wartość logiczna ustawiona na true (1).

Podobnie jak żądania, odpowiedzi są pakowane w protokole HTTP i mają nagłówki HTTP. Wszystkie odpowiedzi XML-RPC używają kodu odpowiedzi 200 OK, nawet jeśli komunikat zawiera błąd. Nagłówki używają wspólnej struktury podobnej do struktury żądań, a typowy zestaw nagłówków może wyglądać następująco:

HTTP/1.1 200 OK
Date: Sat, 06 Oct 2001 23:20:04 GMT
Server: Apache.1.3.12 (Unix)
Connection: close
Content-Type: text/xml
Content-Length: 124

XML-RPC wymaga tylko obsługi protokołu HTTP 1.0, ale protokół HTTP 1.1 jest zgodny.
Typ zawartości musi być ustawiony na text / xml.
Nagłówek Content-Length określa długość odpowiedzi w bajtach.

Pełna odpowiedź, z nagłówkami i ładunkiem odpowiedzi, wyglądałaby następująco:

HTTP/1.1 200 OK
Date: Sat, 06 Oct 2001 23:20:04 GMT
Server: Apache.1.3.12 (Unix)
Connection: close
Content-Type: text/xml
Content-Length: 124

<?xml version="1.0"?>
<methodResponse>
   <params>
      <param>
         <value><double>18.24668429131</double></value>
      </param>
   </params>
</methodResponse>

Po dostarczeniu odpowiedzi z serwera XML-RPC do klienta XML-RPC połączenie jest zamykane. Kolejne żądania należy przesyłać jako oddzielne połączenia XML-RPC.

Błędy XML-RPC to typ odpowiedzi. Jeśli wystąpił problem podczas przetwarzania żądania XML-RPC, element methodResponse będzie zawierał element błędu zamiast elementu params. Element fault, podobnie jak element params , ma tylko jedną wartość, która wskazuje, że coś poszło nie tak. Odpowiedź błędu może wyglądać następująco:

<?xml version="1.0"?>
<methodResponse>
   <fault>
      <value><string>No such method!</string></value>
   </fault>
</methodResponse>

Usterka będzie miała również kod błędu. XML-RPC w ogóle nie standaryzuje kodów błędów. Będziesz musiał sprawdzić dokumentację poszczególnych pakietów, aby zobaczyć, jak radzą sobie z błędami.

Reakcja na błąd może również wyglądać następująco:

<?xml version="1.0"?>
<methodResponse>
   <fault>
      <value>
         <struct>
            <member>
               <name>code</name>
               <value><int>26</int></value>
            </member>
				
            <member>
               <name>message</name>
               <value><string>No such method!</string></value>
            </member>
				
         </struct>
      </value>
   </fault>
</methodResponse>

Aby zademonstrować XML-RPC, utworzymy serwer, który używa Javy do przetwarzania komunikatów XML-RPC, i stworzymy klienta Java do wywoływania procedur na tym serwerze.

Strona Java konwersacji wykorzystuje Apache XML-RPC projektu Apache XML Project, dostępny pod adresem http://xml.apache.org/xmlrpc/

Umieść wszystkie pliki .jar w odpowiedniej ścieżce i stwórzmy jednego klienta i jeden mały serwer XML-RPC przy użyciu JAVA.

Klient XML-RPC

Napiszmy klienta XML-RPC, który wywoła funkcję o nazwie funkcja sum . Ta funkcja przyjmuje dwa parametry i zwraca ich sumę.

import java.util.*;
import org.apache.xmlrpc.*;

public class JavaClient 
{
   public static void main (String [] args) 
   {
      try {

         XmlRpcClient client = new XmlRpcClient("http://localhost/RPC2"); 
         Vector params = new Vector();
         params.addElement(new Integer(17));
         params.addElement(new Integer(13));

         Object result = server.execute("sample.sum", params);

         int sum = ((Integer) result).intValue();
         System.out.println("The sum is: "+ sum);

      } catch (Exception exception) {
         System.err.println("JavaClient: " + exception);
      }
   }
}

Zobaczmy, co się stało w powyższym przykładowym kliencie.

Pakiet Java org.apache.xmlrpc zawiera klasy dla klientów XML-RPC Java i serwera XML-RPC, np. XmlRpcClient.
Pakiet java.util jest niezbędny dla klasy Vector.
Funkcja server.execute (...) wysyła żądanie do serwera. Suma procedur (17,13) jest wywoływana na serwerze tak, jakby była to procedura lokalna. Zwracaną wartością wywołania procedury jest zawsze Object.
Tutaj „sample” oznacza procedurę obsługi zdefiniowaną na serwerze.
Zauważ, że wszystkie parametry wywołania procedury są zawsze gromadzone w wektorze.
Klasa XmlRpcClient jest konstruowana przez określenie „adresu internetowego” serwera, po którym następuje / RPC2.
- localhost - oznacza komputer lokalny
- Możesz podać numer IP zamiast localhost, np. 194.80.215.219
- Możesz określić nazwę domeny, na przykład xyz.dyndns.org
- Możesz określić numer portu wraz z nazwą domeny jako xyz.dyndns.org:8080. Domyślny port to 80
Zauważ, że wynikiem zdalnego wywołania procedury jest zawsze Object i musi on zostać rzutowany na odpowiedni typ.
W przypadku wystąpienia problemów (brak połączenia itp.) Zgłaszany jest wyjątek i musi zostać przechwycony za pomocą instrukcji catch .

W związku z powyższym wezwaniem klient wysyła do serwera następującą wiadomość. Zauważ, że jest to obsługiwane wewnętrznie przez server.execute (...) i nie masz z tym nic wspólnego.

<?xml version="1.0" encoding="ISO-8859-1"?>
<methodCall>
   <methodName>sample.sum</methodName>
   <params>
      <param>
         <value><int>17</int></value>
      </param>
		 
      <param>
         <value><int>13</int></value>
      </param>
   </params>
</methodCall>

Serwer XML-RPC

Poniżej znajduje się kod źródłowy serwera XML-RPC napisany w języku Java. Wykorzystuje wbudowane klasy dostępne w org.apache.xmlrpc. *

import org.apache.xmlrpc.*;

public class JavaServer 
{ 

   public Integer sum(int x, int y) 
   {
      return new Integer(x+y);
   }

   public static void main (String [] args) 
   {
      try {

         System.out.println("Attempting to start XML-RPC Server...");
         WebServer server = new WebServer(80);
         server.addHandler("sample", new JavaServer());
         server.start();
         System.out.println("Started successfully.");
         System.out.println("Accepting requests. (Halt program to stop.)");
      } catch (Exception exception) 
      {
         System.err.println("JavaServer: " + exception);
      }
   }
}

Zobaczmy, co zrobiliśmy na powyższym przykładowym serwerze.

Pakiet org.apache.xmlrpc zawiera klasę WebServer dla implementacji serwera XML-RPC.
Suma procedury, która jest wywoływana zdalnie, jest implementowana jako metoda publiczna w klasie.
Instancja tej samej klasy serwera jest następnie kojarzona z procedurą obsługi, do której klient ma dostęp.
Serwer jest inicjowany przez numer portu (tutaj: 80).
Gdy występują problemy, zgłaszany jest wyjątek i musi zostać przechwycony za pomocą instrukcji catch .

W przypadku wywołania wymienionego w podanym przykładowym kliencie, serwer odsyła klientowi następującą odpowiedź:

<?xml version="1.0" encoding="ISO-8859-1"?>
<methodResponse>
   <params>
      <param>
         <value><int>30</int></value>
      </param>
   </params>
</methodResponse>

Teraz twój serwer jest gotowy, więc skompiluj i uruchom go po wyświetleniu monitu w następujący sposób:

C:\ora\xmlrpc\java>java JavaServer
Attempting to start XML-RPC Server...
Started successfully.
Accepting requests. (Halt program to stop.)

Teraz, aby przetestować funkcjonalność, wywołaj ten serwer w następujący sposób:

C:\ora\xmlrpc\java>java JavaClient
30

W tym samouczku dowiedziałeś się, czym jest XML-RPC i dlaczego potrzebujemy XML-RPC. Omówiliśmy jego model danych, a także format wiadomości żądania i odpowiedzi, które mają być wymieniane między klientem a serwerem. Podaliśmy jeden przykład, aby zademonstrować, jak klient i serwer XML-RPC współpracują przy wymianie informacji.

XML-RPC to bardzo prosta koncepcja z ograniczonym zestawem możliwości. Ograniczenia te są pod wieloma względami najbardziej atrakcyjną cechą XML-RPC, ponieważ znacznie zmniejszają trudność implementacji protokołu i testowania jego interoperacyjności.

Chociaż XML-RPC jest prosty, kreatywne zastosowanie prostych narzędzi może stworzyć wyrafinowaną i potężną architekturę. W przypadkach, w których istnieje potrzeba komunikacji wielu różnych systemów, XML-RPC może być najwłaściwszym najniższym wspólnym mianownikiem.