Zend_XmlRpc_Client の使用法は、
SoapClient オブジェクト
(SOAP 拡張モジュール)
の使用法と非常によく似ています。XML-RPC サービスのプロシージャを、単純に
Zend_XmlRpc_Client のメソッドとしてコールすることができます。
サービスの完全なアドレスを Zend_XmlRpc_Client
のコンストラクタで指定します。
例 17.1. 基本的な XML-RPC リクエスト
<?php
/**
* framework.zend.com のサーバに接続し、使用可能なメソッドを表す
* 配列を取得します。
*/
require_once 'Zend/XmlRpc/Client.php';
$server = new Zend_XmlRpc_Client('http://framework.zend.com/xmlrpc');
print_r( $server->system->listMethods() );
?>
![[注意]](images/note.png) |
注意 |
|---|---|
Zend_XmlRpc_Client は、
リモートメソッドを可能な限りネイティブメソッドと同様に扱おうとします。
上の system.listMethods() のように
リモートメソッドが名前空間を含んでいる場合は、
PHP 風にオブジェクトを連結して
$server->system->listMethods() のようにコールします。
|
XML-RPC サービスのプロシージャの中にはパラメータが必要なものがあります。
必要なパラメータは、Zend_XmlRpc_Client
メソッドのパラメータとして渡すことになります。
XML-RPC プロシージャのパラメータは、指定された XML-RPC 型でなければなりません。
パラメータを渡す方法は 2 通りあります。PHP のネイティブ型で渡すか、
あるいは XML-RPC 型を表す Zend_XmlRpc_Value
オブジェクトで渡すかのいずれかです。
パラメータは、ネイティブの PHP 型、つまり string, integer, float, boolean, array あるいは object として渡します。 このとき、PHP のネイティブ型は自動的に検出され、 以下の表にしたがって XML-RPC 型に変換されます。
表 17.1. PHP ネイティブ値から XML-RPC 型への変換
| PHP ネイティブ型 | XML-RPC 型 |
|---|---|
| integer | int |
| double | double |
| boolean | boolean |
| string | string |
| 配列 | array |
| 連想配列 | struct |
| object | array |
...
/** このプロシージャには 2 つのパラメータが渡されます。
* 最初のパラメータは文字列で、XML-RPC の string 型に自動的に変換されます。
* 2 番目のパラメータは連想配列で、これは XML-RPC の構造体に変換されます。
*/
$p1 = 'parameter 1';
$p2 = array('name' => 'Joe', 'age' => 30);
$service->serviceProcedure($p1, $p2);
...
パラメータを Zend_XmlRpc_Value オブジェクトで渡します。
パラメータに対応する XML-RPC 型を表す
Zend_XmlRpc_Value のインスタンスを作成することができます。
XML-RPC 型を明示的に指定する主な理由としては、以下が考えられるでしょう。
- プロシージャに正しい型で渡されることを確実にしたいことがある (例えば、integer を要求しているプロシージャに対して $_GET 配列の中の文字列を渡したい場合など)。
- プロシージャが base64 型や dateTime.iso8601 型を要求していることがある (これらは PHP のネイティブ型には存在しません)。
- 自動変換が失敗することがある (例えば、空の XML-RPC 構造体をパラメータとして渡すことを考えましょう。 これは、PHP では空の配列に対応します。しかし、 空の配列をパラメータとして渡すと、それが自動変換されたときに XML-RPC の array になってしまいます。なぜなら、 からの配列は連想配列ではないからです)。
Zend_XmlRpc_Value オブジェクトを作成する方法は
2 通りあります。明示的に作成する (オブジェクトのコンストラクタをコールする)
か、静的関数 Zend_XmlRpc_Value::getXmlRpcValue()
を使用して XML-RPC 型の定数を指定します。
表 17.2. Zend_XmlRpc_Value オブジェクトと対応する XML-RPC 型
| XML-RPC 型 | 対応する Zend_XmlRpc_Value 定数 |
Zend_XmlRpc_Value オブジェクト |
|---|---|---|
| int | Zend_XmlRpc_Value::XMLRPC_TYPE_INTEGER |
Zend_XmlRpc_Value_Integer |
| double | Zend_XmlRpc_Value::XMLRPC_TYPE_DOUBLE |
Zend_XmlRpc_Value_Double |
| boolean | Zend_XmlRpc_Value::XMLRPC_TYPE_BOOLEAN |
Zend_XmlRpc_Value_Boolean |
| string | Zend_XmlRpc_Value::XMLRPC_TYPE_STRING |
Zend_XmlRpc_Value_String |
| base64 | Zend_XmlRpc_Value::XMLRPC_TYPE_BASE64 |
Zend_XmlRpc_Value_Base64 |
| dateTime.iso8601 | Zend_XmlRpc_Value::XMLRPC_TYPE_DATETIME |
Zend_XmlRpc_Value_DateTime |
| array | Zend_XmlRpc_Value::XMLRPC_TYPE_ARRAY |
Zend_XmlRpc_Value_Array |
| struct | Zend_XmlRpc_Value::XMLRPC_TYPE_STRUCT |
Zend_XmlRpc_Value_Struct |
...
/** このプロシージャには 2 つのパラメータが渡されます。
* 最初のパラメータは XML-RPC の base64 型で、静的関数
* Zend_XmlRpc_Value::getXmlRpcValue() を使用して作成します。
* 2 番目のパラメータは XML-RPC の構造体で、これは 明示的に作成します。
*/
$p1 = ZXmlRpcValue::getXmlRpcValue('encoded string', Zend_XmlRpc_Value::XMLRPC_TYPE_BASE64);
$p2 = new Zend_XmlRpc_Value_Struct(array('name' => 'Joe', 'age' => 30));
$service->serviceProcedure($p1, $p2);
...
|
注意 |
|---|---|
この場合もパラメータの値は PHP の変数で渡していますが、
指定した型に PHP の変換機能によって変換されます
(もし Zend_XmlRpc_Value_Integer
オブジェクトの値として文字列が渡されたら、
(int)$value を使用して変換されます)。
|
この方式によるパラメータ渡しは Zend_XmlRpc
パッケージで内部的に使用されているもので、推奨されません。
それでもこの方式を使用したいというのなら、静的関数
Zend_XmlRpc_Value::getXmlRpcValue() を使用して XML
文字列をパースし、対応する XML-RPC 型を表す
Zend_XmlRpc_Value オブジェクトに格納してください。
Zend_XmlRpc_Value::getXmlRpcValue() 関数は 2
つのパラメータ、XML 文字列と
Zend_XmlRpc_Value::XML_STRING 定数を受け取ります。
XML-RPC と SOAP ウェブサービスの主な違いは WSDL ファイルの存在です。 SOAP プロトコルは通常 WSDL ファイルを使用しており、 ここにウェブサービスのインターフェイスが記述されています。 このインターフェイスにより、SOAP クライアントがサーバに送信するパラメータの型、 サーバから返される型を知ることができるのです。 WSDL ファイルがなければ、それらの型を知るのは難しくなるでしょう。
XML-RPC プロトコルでは、system.methodSignature
という名前の特別なプロシージャを使用することでこの問題を解決します。
このプロシージャは、プロシージャ名をパラメータとして受け取り、
そのプロシージャのシグネチャを返します。シグネチャには、
必須パラメータの型および返り値の型が含まれます。
|
注意 |
|---|---|
すべての XML-RPC サーバが system.methodSignature
プロシージャをサポートしているわけではありません。
サポートしていないサーバの場合は、型指定を使用することはできません。
|
Zend_XmlRpc_Client では、system.methodSignature
プロシージャを使用することで、ある種の 'WSDL' ファイルを XML-RPC
サーバ用に実装しています。
要求を受けると、Zend_XmlRpc_Client は
XML-RPC サーバ上の全プロシージャの一覧を調べ、
それらのシグネチャを調べたうえでそれを XML ファイル
(SOAP の WSDL ファイルに似た形式です) に保存します。
同じ XML-RPC サーバを再度使用する際には、その XML
ファイルを指定すると、Zend_XmlRpc_Client
がプロシージャのパラメータの型を判定します。
プロシージャのシグネチャの XML ファイルを作成するには
Zend_XmlRpc_Client::__getMethodsXml() 関数をコールします
(この関数は、シグネチャのデータを含む XML 文字列を返します)。
既存のシグネチャ XML ファイルを使用するには、
Zend_XmlRpc_Client コンストラクタのパラメータとして
XML データを渡すか、あるいは
Zend_XmlRpc_Client::__setMethodsXml() 関数をコールします。
例 17.2. 型指定を使用した XML-RPC サービスのコール
<?php
/**
* XML-RPC サーバに接続し、シグネチャファイルを保存します
* (SOAP の WSDL ファイルと同等の XML-RPC 版になります)
*/
require_once 'Zend/XmlRpc/Client.php';
$service = new Zend_XmlRpc_Client('http://www.example.org/xmlrpc');
file_put_contents('/tmp/xmlrpc-signatures/example.xml', $service->__getMethodsXml());
/* $service オブジェクトは、XML-RPC サーバのすべてのシグネチャを含むようになります。
serviceProcedure がコールされると、そのパラメータ ($param) は
プロシージャのシグネチャに応じて適切に型変換されます。
*/
$service->serviceProcedure($param);
?>
<?php
/**
* 既存のシグネチャファイルを使用して XML-RPC サーバに接続します。これにより、
* プロシージャに渡すパラメータの型が適切に変換されるようになります。
*/
require_once 'Zend/XmlRpc/Client.php';
$signature_file_xml = file_get_contents('/tmp/xmlrpc-signatures/example.xml');
$service = new Zend_XmlRpc_Client('http://www.example.org/xmlrpc', 'namespace', $signature_file_xml);
/* $service オブジェクトは、XML-RPC サーバのすべてのシグネチャを含むようになります。
serviceProcedure がコールされると、そのパラメータ ($param) は
プロシージャのシグネチャに応じて適切に型変換されます。
*/
$service->serviceProcedure($param);
?>
XML-RPC プロシージャは、 XML-RPC 型の値を返します。
XML-RPC プロシージャをコールする Zend_XmlRpc_Client メソッドは、
返される XML-RPC 型を PHP のネイティブ型に変換したものを返します。
要求したプロシージャの返り値を取得するには、
Zend_XmlRpc_Client::__getResponse() 関数を使用します。
__getResponse() 関数は、返り値の型を示すパラメータを受け取ります。
応答内容として指定できるオプションは以下のとおりです。
-
Zend_XmlRpc_Client::RESPONSE_PHP_NATIVE- プロシージャの返り値を、PHP のネイティブ型として返します (XML-RPC 型を PHP 型に変換します)。 -
Zend_XmlRpc_Client::RESPONSE_XML_STRING- XML-RPC の応答を、XML 文字列形式で返します。 -
Zend_XmlRpc_Client::RESPONSE_ZXMLRPC_OBJECT- XML-RPC 型を表すZend_XmlRpc_Valueオブジェクトを返します。
...
$service->serviceProcedure();
$response = $service->__getResponse();
// $response は、XML-RPC 型の返り値を PHP 変数に変換したものです
$response = $service->__getResponse(ZXmlRpcClient::RESPONSE_XML_STRING);
// $response は、プロシージャの返り値を表す XML を含む文字列です
$response = $service->__getResponse(ZXmlRpcClient::RESPONSE_ZXMLRPC_OBJECT);
// $response は、XML-RPC 型の返り値を表す Zend_XmlRpc_Value インスタンスです
...