documentation/manual/ja/module_specs/Zend_Rest_Client.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <!-- EN-Revision: 20854 -->
   4 <sect1 id="zend.rest.client">
   5     <title>Zend_Rest_Client</title>
   6
   7     <sect2 id="zend.rest.client.introduction">
   8         <title>導入</title>
   9
  10         <para>
  11             <classname>Zend_Rest_Client</classname> の使用法は、
  12             <code>SoapClient</code> オブジェクト (<ulink
  13             url="http://www.php.net/soap">SOAP ウェブサービス拡張モジュール</ulink>)
  14             の使用法と非常によく似ています。REST サービスのプロシージャは、簡単に
  15             <classname>Zend_Rest_Client</classname> のメソッドとしてコールできます。
  16             まず、そのサービスのアドレスを <classname>Zend_Rest_Client</classname> のコンストラクタに指定します。
  17         </para>
  18
  19         <example id="zend.rest.client.introduction.example-1">
  20             <title>基本的な REST リクエスト</title>
  21
  22             <programlisting language="php"><![CDATA[
  23 /**
  24  * framework.zend.com サーバに接続し、挨拶を受け取ります
  25  */
  26 $client = new Zend_Rest_Client('http://framework.zend.com/rest');
  27
  28 echo $client->sayHello('Davey', 'Day')->get(); // "Hello Davey, Good Day"
  29 ]]></programlisting>
  30         </example>
  31
  32         <note>
  33             <title>コール方法の違い</title>
  34
  35             <para>
  36                 <classname>Zend_Rest_Client</classname> は、
  37                 リモートメソッドのコールをできるだけネイティブなメソッドと同様に行おうとします。
  38                 唯一の違いは、続けて <methodname>get()</methodname> か <methodname>post()</methodname>、
  39                 <methodname>put()</methodname> あるいは <methodname>delete()</methodname>
  40                 のいずれかのメソッドをコールしなければならないということです。
  41                 これは、メソッドの連結で行ってもかまいませんし、
  42                 独立したメソッドコールにしてもかまいません。
  43             </para>
  44
  45             <programlisting language="php"><![CDATA[
  46 $client->sayHello('Davey', 'Day');
  47 echo $client->get();
  48 ]]></programlisting>
  49         </note>
  50     </sect2>
  51
  52     <sect2 id="zend.rest.client.return">
  53         <title>レスポンス</title>
  54
  55         <para>
  56             <classname>Zend_Rest_Client</classname> を使用して行ったリクエストは、すべて
  57             <classname>Zend_Rest_Client_Response</classname> オブジェクトを返します。
  58             このオブジェクトには多くのプロパティがあり、結果に簡単にアクセスできます。
  59         </para>
  60
  61         <para>
  62             <classname>Zend_Rest_Server</classname> に基づくサービスにアクセスした場合には、
  63             <classname>Zend_Rest_Client</classname> は結果についていくつかの前提条件を想定しています。
  64             たとえばレスポンスステータス (成功あるいは失敗) や返り値の型などです。
  65         </para>
  66
  67         <example id="zend.rest.client.return.example-1">
  68             <title>レスポンスステータス</title>
  69
  70             <programlisting language="php"><![CDATA[
  71 $result = $client->sayHello('Davey', 'Day')->get();
  72
  73 if ($result->isSuccess()) {
  74     echo $result; // "Hello Davey, Good Day"
  75 }
  76 ]]></programlisting>
  77         </example>
  78
  79         <para>
  80             上の例で、リクエストの結果をオブジェクトとして扱い、
  81             <methodname>isSuccess()</methodname> をコールしていることがごらんいただけるでしょう。
  82             また、<methodname>__toString()</methodname> をサポートしているため、
  83             単に <code>echo</code> とするだけでオブジェクトの結果を取得できます。
  84             <classname>Zend_Rest_Client_Response</classname> は、任意のスカラー値を
  85             echo することが可能です。複雑な形式の場合は、
  86             配列記法あるいはオブジェクト記法が使用できます。
  87         </para>
  88
  89         <para>
  90             しかし、<classname>Zend_Rest_Server</classname>
  91             を使用していないサービスに問い合わせたいこともあるでしょう。このような場合、
  92             <classname>Zend_Rest_Client_Response</classname> オブジェクトは
  93             <code>SimpleXMLElement</code> と同様の振る舞いをします。
  94             しかし、より簡単に処理するため、プロパティがルート要素の直下にない場合には
  95             自動的に XPath で <acronym>XML</acronym> を探すようにしています。さらに、
  96             プロパティに対してメソッドとしてアクセスすると、
  97             <acronym>PHP</acronym> の値あるいは値の配列としてそのオブジェクトを取得できます。
  98         </para>
  99
 100         <example id="zend.rest.client.return.example-2">
 101             <title>Technorati の Rest サービスの使用</title>
 102
 103             <programlisting language="php"><![CDATA[
 104 $technorati = new Zend_Rest_Client('http://api.technorati.com/bloginfo');
 105 $technorati->key($key);
 106 $technorati->url('http://pixelated-dreams.com');
 107 $result = $technorati->get();
 108 echo $result->firstname() .' '. $result->lastname();
 109 ]]></programlisting>
 110         </example>
 111
 112         <example id="zend.rest.client.return.example-3">
 113             <title>Technorati からのレスポンスの例</title>
 114
 115             <programlisting language="xml"><![CDATA[
 116 <?xml version="1.0" encoding="utf-8"?>
 117 <!-- generator="Technorati API version 1.0 /bloginfo" -->
 118 <!DOCTYPE tapi PUBLIC "-//Technorati, Inc.//DTD TAPI 0.02//EN"
 119                       "http://api.technorati.com/dtd/tapi-002.xml">
 120 <tapi version="1.0">
 121     <document>
 122         <result>
 123             <url>http://pixelated-dreams.com</url>
 124             <weblog>
 125                 <name>Pixelated Dreams</name>
 126                 <url>http://pixelated-dreams.com</url>
 127                 <author>
 128                     <username>DShafik</username>
 129                     <firstname>Davey</firstname>
 130                     <lastname>Shafik</lastname>
 131                 </author>
 132                 <rssurl>
 133                     http://pixelated-dreams.com/feeds/index.rss2
 134                 </rssurl>
 135                 <atomurl>
 136                     http://pixelated-dreams.com/feeds/atom.xml
 137                 </atomurl>
 138                 <inboundblogs>44</inboundblogs>
 139                 <inboundlinks>218</inboundlinks>
 140                 <lastupdate>2006-04-26 04:36:36 GMT</lastupdate>
 141                 <rank>60635</rank>
 142             </weblog>
 143             <inboundblogs>44</inboundblogs>
 144             <inboundlinks>218</inboundlinks>
 145         </result>
 146     </document>
 147 </tapi>
 148 ]]></programlisting>
 149         </example>
 150
 151         <para>
 152             ここで、<code>firstname</code> や
 153             <code>lastname</code> といったプロパティにアクセスできます。
 154             これらはトップレベル要素ではありませんが、
 155             名前を指定するだけで自動的に取得できます。
 156         </para>
 157
 158         <note>
 159             <title>複数の要素</title>
 160
 161             <para>
 162                 名前でアクセスしているときにもし複数の項目が見つかったら、
 163                 SimpleXMLElements の配列を返します。メソッド記法でアクセスすると、
 164                 <acronym>PHP</acronym> の値の配列を返します。
 165             </para>
 166         </note>
 167     </sect2>
 168
 169     <sect2 id="zend.rest.client.args">
 170         <title>リクエストの引数</title>
 171
 172         <para>
 173             <classname>Zend_Rest_Server</classname> ベースのサービスにリクエストを送るのではない場合は、
 174             リクエストの際に複数の引数を指定する必要があります。
 175             これを行うには、引数名と同じ名前のメソッドをコールし、
 176             その最初の (そして唯一の) 引数として値を指定します。
 177             これらのメソッドコールはそのオブジェクト自身を返すので、
 178             メソッドを連結する "流れるような" 形式で使用できます。
 179             最初のコール (あるいは複数の引数を指定した場合の最初の引数)
 180             は常に、<classname>Zend_Rest_Server</classname>
 181             サービスをコールする際のメソッドとみなされます。
 182         </para>
 183
 184         <example id="zend.rest.client.args.example-1">
 185             <title>リクエストの引数の設定</title>
 186
 187             <programlisting language="php"><![CDATA[
 188 $client = new Zend_Rest_Client('http://example.org/rest');
 189
 190 $client->arg('value1');
 191 $client->arg2('value2');
 192 $client->get();
 193
 194 // あるいは
 195
 196 $client->arg('value1')->arg2('value2')->get();
 197 ]]></programlisting>
 198         </example>
 199
 200         <para>
 201             上の例の二通りの方法はいずれも、次のような get 引数となります。
 202             <code>?method=arg&amp;arg1=value1&amp;arg=value1&amp;arg2=value2</code>
 203         </para>
 204
 205         <para>
 206             最初の <code>$client->arg('value1');</code> のコールが
 207             <code>method=arg&amp;arg1=value1</code> および <code>arg=value1</code>
 208             の二通りの結果となることにお気づきでしょう。これによって、
 209             <classname>Zend_Rest_Server</classname> がリクエストを適切に理解できるようになるのです。
 210             そのサービスを使用するにあたっての前提知識を必要としなくなります。
 211         </para>
 212
 213         <warning>
 214             <title>Zend_Rest_Client の厳格性</title>
 215
 216             <para>
 217                 受け取る引数について厳格な REST サービスでは、
 218                 <classname>Zend_Rest_Client</classname> の使用に失敗することがあります。
 219                 これは上で説明した挙動のせいです。
 220                 これはそう頻繁に起こることではないので、特に問題とはならないでしょう。
 221             </para>
 222         </warning>
 223     </sect2>
 224 </sect1>
 225
 226 <!--
 227 vim:se ts=4 sw=4 et:
 228 -->