repo_zf1/documentation/manual/ja/module_specs/Zend_Rest_Client.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 15103 -->
<sect1 id="zend.rest.client">
    <title>Zend_Rest_Client</title>
    <sect2 id="zend.rest.client.introduction">
        <title>導入</title>
        <para>
            <classname>Zend_Rest_Client</classname> の使用法は、
            <code>SoapClient</code> オブジェクト (<ulink
            url="http://www.php.net/soap">SOAP ウェブサービス拡張モジュール</ulink>)
            の使用法と非常によく似ています。REST サービスのプロシージャは、簡単に
            <classname>Zend_Rest_Client</classname> のメソッドとしてコールすることができます。
            まず、そのサービスのアドレスを <classname>Zend_Rest_Client</classname> のコンストラクタに指定します。
        </para>

        <example id="zend.rest.client.introduction.example-1">
            <title>基本的な REST リクエスト</title>

            <programlisting role="php"><![CDATA[
/**
 * framework.zend.com サーバに接続し、挨拶を受け取ります
 */
$client = new Zend_Rest_Client('http://framework.zend.com/rest');

echo $client->sayHello('Davey', 'Day')->get(); // "Hello Davey, Good Day"
]]>
            </programlisting>
        </example>

        <note>
            <title>コール方法の違い</title>
            <para>
                <classname>Zend_Rest_Client</classname> は、
                リモートメソッドのコールをできるだけネイティブなメソッドと同様に行おうとします。
                唯一の違いは、続けて <code>get()</code> か <code>post()</code>、
                <code>put()</code> あるいは <code>delete()</code>
                のいずれかのメソッドをコールしなければならないということです。
                これは、メソッドの連結で行ってもかまいませんし、
                独立したメソッドコールにしてもかまいません。
            </para>

            <programlisting role="php"><![CDATA[
$client->sayHello('Davey', 'Day');
echo $client->get();
]]>
            </programlisting>
        </note>
    </sect2>

    <sect2 id="zend.rest.client.return">
        <title>レスポンス</title>

        <para>
            <classname>Zend_Rest_Client</classname> を使用して行ったリクエストは、すべて
            <classname>Zend_Rest_Client_Response</classname> オブジェクトを返します。
            このオブジェクトには多くのプロパティがあり、結果に簡単にアクセスすることができます。
        </para>

        <para>
            <classname>Zend_Rest_Server</classname> に基づくサービスにアクセスした場合には、
            <classname>Zend_Rest_Client</classname> は結果についていくつかの前提条件を想定しています。
            たとえばレスポンスステータス (成功あるいは失敗) や返り値の型などです。
        </para>

        <example id="zend.rest.client.return.example-1">
            <title>レスポンスステータス</title>
            <programlisting role="php"><![CDATA[
$result = $client->sayHello('Davey', 'Day')->get();

if ($result->isSuccess()) {
    echo $result; // "Hello Davey, Good Day"
}
]]>
            </programlisting>
        </example>

        <para>
            上の例で、リクエストの結果をオブジェクトとして扱い、
            <code>isSuccess()</code> をコールしていることがごらんいただけるでしょう。
            また、<code>__toString()</code> をサポートしているため、
            単に <code>echo</code> とするだけでオブジェクトの結果を取得できます。
            <classname>Zend_Rest_Client_Response</classname> は、任意のスカラー値を
            echo することが可能です。複雑な形式の場合は、
            配列記法あるいはオブジェクト記法が使用できます。
        </para>

        <para>
            しかし、<classname>Zend_Rest_Server</classname>
            を使用していないサービスに問い合わせたいこともあるでしょう。このような場合、
            <classname>Zend_Rest_Client_Response</classname> オブジェクトは
            <code>SimpleXMLElement</code> と同様の振る舞いをします。
            しかし、より簡単に処理するため、プロパティがルート要素の直下にない場合には
            自動的に XPath で XML を探すようにしています。さらに、
            プロパティに対してメソッドとしてアクセスすると、
            PHP の値あるいは値の配列としてそのオブジェクトを取得できます。
        </para>

        <example id="zend.rest.client.return.example-2">
            <title>Technorati の Rest サービスの使用</title>

            <programlisting role="php"><![CDATA[
$technorati = new Zend_Rest_Client('http://api.technorati.com/bloginfo');
$technorati->key($key);
$technorati->url('http://pixelated-dreams.com');
$result = $technorati->get();
echo $result->firstname() .' '. $result->lastname();
]]>
            </programlisting>
        </example>

        <example id="zend.rest.client.return.example-3">
            <title>Technorati からのレスポンスの例</title>
            <programlisting role="xml"><![CDATA[
<?xml version="1.0" encoding="utf-8"?>
<!-- generator="Technorati API version 1.0 /bloginfo" -->
<!DOCTYPE tapi PUBLIC "-//Technorati, Inc.//DTD TAPI 0.02//EN"
                      "http://api.technorati.com/dtd/tapi-002.xml">
<tapi version="1.0">
    <document>
        <result>
            <url>http://pixelated-dreams.com</url>
            <weblog>
                <name>Pixelated Dreams</name>
                <url>http://pixelated-dreams.com</url>
                <author>
                    <username>DShafik</username>
                    <firstname>Davey</firstname>
                    <lastname>Shafik</lastname>
                </author>
                <rssurl>
                    http://pixelated-dreams.com/feeds/index.rss2
                </rssurl>
                <atomurl>
                    http://pixelated-dreams.com/feeds/atom.xml
                </atomurl>
                <inboundblogs>44</inboundblogs>
                <inboundlinks>218</inboundlinks>
                <lastupdate>2006-04-26 04:36:36 GMT</lastupdate>
                <rank>60635</rank>
            </weblog>
            <inboundblogs>44</inboundblogs>
            <inboundlinks>218</inboundlinks>
        </result>
    </document>
</tapi>
]]>
</programlisting>
        </example>

        <para>
            ここで、<code>firstname</code> や
            <code>lastname</code> といったプロパティにアクセスすることができます。
            これらはトップレベル要素ではありませんが、
            名前を指定するだけで自動的に取得することができます。
        </para>

        <note>
            <title>複数の要素</title>

            <para>
                名前でアクセスしているときにもし複数の項目が見つかったら、
                SimpleXMLElements の配列を返します。メソッド記法でアクセスすると、
                PHP の値の配列を返します。
            </para>
        </note>
    </sect2>

    <sect2 id="zend.rest.client.args">
        <title>リクエストの引数</title>

        <para>
            <classname>Zend_Rest_Server</classname> ベースのサービスにリクエストを送るのではない場合は、
            リクエストの際に複数の引数を指定する必要があります。
            これを行うには、引数名と同じ名前のメソッドをコールし、
            その最初の (そして唯一の) 引数として値を指定します。
            これらのメソッドコールはそのオブジェクト自身を返すので、
            メソッドを連結する "流れるような" 形式で使用できます。
            最初のコール (あるいは複数の引数を指定した場合の最初の引数)
            は常に、<classname>Zend_Rest_Server</classname>
            サービスをコールする際のメソッドとみなされます。
        </para>

        <example id="zend.rest.client.args.example-1">
            <title>リクエストの引数の設定</title>

            <programlisting role="php"><![CDATA[
$client = new Zend_Rest_Client('http://example.org/rest');

$client->arg('value1');
$client->arg2('value2');
$client->get();

// あるいは

$client->arg('value1')->arg2('value2')->get();
]]>
            </programlisting>
        </example>

        <para>
            上の例の二通りの方法はいずれも、次のような get 引数となります。
            <code>?method=arg&amp;arg1=value1&amp;arg=value1&amp;arg2=value2</code>
        </para>

        <para>
            最初の <code>$client->arg('value1');</code> のコールが
            <code>method=arg&amp;arg1=value1</code> および <code>arg=value1</code>
            の二通りの結果となることにお気づきでしょう。これによって、
            <classname>Zend_Rest_Server</classname> がリクエストを適切に理解できるようになるのです。
            そのサービスを使用するにあたっての前提知識を必要としなくなります。
        </para>

        <warning>
            <title>Zend_Rest_Client の厳格性</title>

            <para>
                受け取る引数について厳格な REST サービスでは、
                <classname>Zend_Rest_Client</classname> の使用に失敗することがあります。
                これは上で説明した挙動のせいです。
                これはそう頻繁に起こることではないので、特に問題とはならないでしょう。
            </para>
        </warning>
    </sect2>
</sect1>

<!--
vim:se ts=4 sw=4 et:
-->