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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 15103 -->
<sect1 id="zend.service.delicious">
    <title>Zend_Service_Delicious</title>
    <sect2 id="zend.service.delicious.introduction">
        <title>導入</title>
        <para>
            <classname>Zend_Service_Delicious</classname> は、
            <ulink url="http://del.icio.us">del.icio.us</ulink>
            の XML および JSON ウェブサービスを使用するためのシンプルな API です。
            このコンポーネントによって、del.icio.us への投稿のうち、
            権限を持っているものについての読み書きが可能になります。
            全ユーザの公開データへの読み込み専用のアクセスも可能です。
        </para>
        <example id="zend.service.delicious.introduction.getAllPosts">
            <title>すべての投稿の取得</title>
            <programlisting role="php"><![CDATA[
$delicious = new Zend_Service_Delicious('ユーザ名', 'パスワード');
$posts = $delicious->getAllPosts();

foreach ($posts as $post) {
    echo "--\n";
    echo "タイトル: {$post->getTitle()}\n";
    echo "URL: {$post->getUrl()}\n";
}
]]>
            </programlisting>
        </example>
    </sect2>
    <sect2 id="zend.service.delicious.retrieving_posts">
        <title>投稿の取得</title>
        <para>
            <classname>Zend_Service_Delicious</classname> には、投稿を取得するメソッドとして
            <code>getPosts()</code>、<code>getRecentPosts()</code>
            および <code>getAllPosts()</code> の三種類があります。
            これらはすべて <classname>Zend_Service_Delicious_PostList</classname>
            のインスタンスを返します。ここに、取得したすべての投稿が含まれます。
        </para>
        <programlisting role="php"><![CDATA[
/**
 * 引数にマッチする投稿を取得する。日付や url を省略した場合は
 * 直近の日付を使用する
 *
 * @param string $tag オプションで、タグによる絞込みを行う
 * @param Zend_Date $dt オプションで、日付による絞込みを行う
 * @param string $url オプションで、url による絞込みを行う
 * @return Zend_Service_Delicious_PostList
 */
public function getPosts($tag = null, $dt = null, $url = null);

/**
 * 直近の投稿を取得する
 *
 * @param string $tag   オプションで、タグによる絞込みを行う
 * @param string $count 返す投稿の最大数 (デフォルトは 15)
 * @return Zend_Service_Delicious_PostList
 */
public function getRecentPosts($tag = null, $count = 15);

/**
 * すべての投稿を取得する
 *
 * @param string $tag オプションで、タグによる絞込みを行う
 * @return Zend_Service_Delicious_PostList
 */
public function getAllPosts($tag = null);
]]>
        </programlisting>
    </sect2>
    <sect2 id="zend.service.delicious.postlist">
        <title>Zend_Service_Delicious_PostList</title>
        <para>
            <classname>Zend_Service_Delicious</classname> のメソッド <code>getPosts()</code>、<code>getAllPosts()</code>、
            <code>getRecentPosts()</code> および <code>getUserPosts()</code>
            が、このクラスのインスタンスを返します。
        </para>
        <para>
            データへのアクセスを簡単に行うため、このクラスは
            <code>Countable</code>、<code>Iterator</code> および
            <code>ArrayAccess</code> の三つのインターフェイスを実装しています。
        </para>
        <example id="zend.service.delicious.postlist.accessing_post_lists">
            <title>投稿一覧へのアクセス</title>
            <programlisting role="php"><![CDATA[
$delicious = new Zend_Service_Delicious('ユーザ名', 'パスワード');
$posts = $delicious->getAllPosts();

// 投稿数を数えます
echo count($posts);

// 投稿を順次処理します
foreach ($posts as $post) {
    echo "--\n";
    echo "タイトル: {$post->getTitle()}\n";
    echo "URL: {$post->getUrl()}\n";
}

// 配列風のアクセス方式で投稿を取得します
echo $posts[0]->getTitle();
]]>
            </programlisting>
        </example>
        <note>
            <para>
                メソッド <code>ArrayAccess::offsetSet()</code> および <code>ArrayAccess::offsetUnset()</code>
                は、この実装では例外をスローします。つまり、<code>unset($posts[0]);</code>
                や <code>$posts[0] = 'A';</code> といったコードを書くと例外が発生するということです。
                というのも、これらのプロパティは読み込み専用だからです。
            </para>
        </note>
        <para>
            投稿一覧オブジェクトには、二種類のフィルタリング機能が組み込まれています。
            タグによるフィルタリングと、URL によるフィルタリングです。
        </para>
        <example id="zend.service.delicious.postlist.example.withTags">
            <title>タグの指定による投稿一覧のフィルタリング</title>
            <para>
                特定のタグで投稿を絞り込むには、<code>withTags()</code> を使用します。
                ひとつのタグでだけ絞り込みを行う際に便利なように、
                <code>withTag()</code> も用意されています。
            </para>
            <programlisting role="php"><![CDATA[
$delicious = new Zend_Service_Delicious('ユーザ名', 'パスワード');
$posts = $delicious->getAllPosts();

// タグ "php" および "zend" が指定されている投稿のみを表示します
foreach ($posts->withTags(array('php', 'zend')) as $post) {
    echo "タイトル: {$post->getTitle()}\n";
    echo "URL: {$post->getUrl()}\n";
}
]]>
            </programlisting>
        </example>
        <example id="zend.service.delicious.postlist.example.byUrl">
            <title>URL の指定による投稿一覧のフィルタリング</title>
            <para>
                指定した正規表現にマッチする URL で投稿を絞り込むには
                <code>withUrl()</code> メソッドを使用します。
            </para>
            <programlisting role="php"><![CDATA[
$delicious = new Zend_Service_Delicious('ユーザ名', 'パスワード');
$posts = $delicious->getAllPosts();

// URL に "help" を含む投稿のみを表示します
foreach ($posts->withUrl('/help/') as $post) {
    echo "タイトル: {$post->getTitle()}\n";
    echo "URL: {$post->getUrl()}\n";
}
]]>
            </programlisting>
        </example>
    </sect2>
    <sect2 id="zend.service.delicious.editing_posts">
        <title>投稿の編集</title>
        <example id="zend.service.delicious.editing_posts.post_editing">
            <title>投稿の編集</title>
            <programlisting role="php"><![CDATA[
$delicious = new Zend_Service_Delicious('ユーザ名', 'パスワード');
$posts = $delicious->getPosts();

// タイトルを設定します
$posts[0]->setTitle('新しいタイトル');
// 変更を保存します
$posts[0]->save();
]]>
            </programlisting>
        </example>
        <example id="zend.service.delicious.editing_posts.method_call_chaining">
            <title>メソッドコールの連結</title>
            <para>
               すべての設定用メソッドは post オブジェクトを返すので、
               「流れるようなインターフェイス」を使用してメソッドコールを連結することができます。
            </para>
            <programlisting role="php"><![CDATA[
$delicious = new Zend_Service_Delicious('ユーザ名', 'パスワード');
$posts = $delicious->getPosts();

$posts[0]->setTitle('新しいタイトル')
         ->setNotes('新しいメモ')
         ->save();
]]>
            </programlisting>
        </example>
    </sect2>
    <sect2 id="zend.service.delicious.deleting_posts">
        <title>投稿の削除</title>
        <para>
            投稿を削除する方法は二通りあります。
            投稿の URL を指定するか、post オブジェクトの
            <code>delete()</code> メソッドを実行するかのいずれかです。
        </para>
        <example id="zend.service.delicious.deleting_posts.deleting_posts">
            <title>投稿の削除</title>
            <programlisting role="php"><![CDATA[
$delicious = new Zend_Service_Delicious('ユーザ名', 'パスワード');

// URL を指定します
$delicious->deletePost('http://framework.zend.com');

// あるいは、post オブジェクトのメソッドをコールします
$posts = $delicious->getPosts();
$posts[0]->delete();

// deletePost() を使用する、もうひとつの方法
$delicious->deletePost($posts[0]->getUrl());
]]>
            </programlisting>
        </example>
    </sect2>
    <sect2 id="zend.service.delicious.adding_posts">
        <title>新しい投稿の追加</title>
        <para>
            投稿を追加するには <code>createNewPost()</code> メソッドをコールする必要があります。
            このメソッドは <classname>Zend_Service_Delicious_Post</classname> オブジェクトを返します。
            投稿を編集したら、それを del.icio.us のデータベースに保存するために
            <code>save()</code> メソッドをコールします。
        </para>
        <example id="zend.service.delicious.adding_posts.adding_a_post">
            <title>投稿の追加</title>
            <programlisting role="php"><![CDATA[
$delicious = new Zend_Service_Delicious('ユーザ名', 'パスワード');

// 新しい投稿を作成し、保存します (メソッドコールの連結を使用します)
$delicious->createNewPost('Zend Framework', 'http://framework.zend.com')
          ->setNotes('Zend Framework Homepage')
          ->save();

// 新しい投稿を作成し、保存します (メソッドコールの連結を使用しません)
$newPost = $delicious->createNewPost('Zend Framework',
                                     'http://framework.zend.com');
$newPost->setNotes('Zend Framework Homepage');
$newPost->save();
]]>
            </programlisting>
        </example>
    </sect2>
    <sect2 id="zend.service.delicious.tags">
        <title>タグ</title>
        <example id="zend.service.delicious.tags.tags">
            <title>タグ</title>
            <programlisting role="php"><![CDATA[
$delicious = new Zend_Service_Delicious('ユーザ名', 'パスワード');

// すべてのタグを取得します
print_r($delicious->getTags());

// タグ ZF の名前を zendFramework に変更します
$delicious->renameTag('ZF', 'zendFramework');
]]>
            </programlisting>
        </example>
    </sect2>
    <sect2 id="zend.service.delicious.bundles">
        <title>バンドル</title>
        <example id="zend.service.delicious.bundles.example">
            <title>バンドル</title>
            <programlisting role="php"><![CDATA[
$delicious = new Zend_Service_Delicious('ユーザ名', 'パスワード');

// すべてのバンドルを取得します
print_r($delicious->getBundles());

// someBundle というバンドルを削除します
$delicious->deleteBundle('someBundle');

// バンドルを追加します
$delicious->addBundle('newBundle', array('tag1', 'tag2'));
]]>
            </programlisting>
        </example>
    </sect2>
    <sect2 id="zend.service.delicious.public_data">
        <title>公開データ</title>
        <para>
            del.icio.us のウェブ API を使用すると、全ユーザの公開データにアクセスできるようになります。
        </para>
        <table id="zend.service.delicious.public_data.functions_for_retrieving_public_data">
            <title>公開データを取得するためのメソッド</title>
            <tgroup cols="3">
                <thead>
                    <row>
                        <entry>名前</entry>
                        <entry>説明</entry>
                        <entry>返り値の型</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry><code>getUserFans()</code></entry>
                        <entry>あるユーザのファンを取得します</entry>
                        <entry>Array</entry>
                    </row>
                    <row>
                        <entry><code>getUserNetwork()</code></entry>
                        <entry>あるユーザのネットワークを取得します</entry>
                        <entry>Array</entry>
                    </row>
                    <row>
                        <entry><code>getUserPosts()</code></entry>
                        <entry>あるユーザの投稿を取得します</entry>
                        <entry>Zend_Service_Delicious_PostList</entry>
                    </row>
                    <row>
                        <entry><code>getUserTags()</code></entry>
                        <entry>あるユーザのタグを取得します</entry>
                        <entry>Array</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
        <note>
            <para>
                これらのメソッドを使用するだけなら、
                <classname>Zend_Service_Delicious</classname> オブジェクトの作成時に
                ユーザ名とパスワードを指定する必要はありません。
            </para>
        </note>
        <example id="zend.service.delicious.public_data.retrieving_public_data">
            <title>公開データの取得</title>
            <programlisting role="php"><![CDATA[
// ユーザ名とパスワードは不要です
$delicious = new Zend_Service_Delicious();

// someUser のファンを取得します
print_r($delicious->getUserFans('someUser'));

// someUser のネットワークを取得します
print_r($delicious->getUserNetwork('someUser'));

// someUser のタグを取得します
print_r($delicious->getUserTags('someUser'));
]]>
            </programlisting>
        </example>
        <sect3 id="zend.service.delicious.public_data.posts">
            <title>公開投稿</title>
            <para>
                公開投稿を <code>getUserPosts()</code> メソッドで取得すると、
                <classname>Zend_Service_Delicious_PostList</classname> オブジェクトが返されます。ここには
                <classname>Zend_Service_Delicious_SimplePost</classname> オブジェクトが含まれ、
                その中には URL やタイトル、メモ、タグといった投稿に関する基本情報が含まれます。
            </para>
            <table id="zend.service.delicious.public_data.posts.SimplePost_methods">
                <title><classname>Zend_Service_Delicious_SimplePost</classname> クラスのメソッド</title>
                <tgroup cols="3">
                    <thead>
                        <row>
                            <entry>名前</entry>
                            <entry>説明</entry>
                            <entry>返り値の型</entry>
                        </row>
                    </thead>
                    <tbody>
                        <row>
                            <entry><code>getNotes()</code></entry>
                            <entry>投稿のメモを返します</entry>
                            <entry>String</entry>
                        </row>
                        <row>
                            <entry><code>getTags()</code></entry>
                            <entry>投稿のタグを返します</entry>
                            <entry>Array</entry>
                        </row>
                        <row>
                            <entry><code>getTitle()</code></entry>
                            <entry>投稿のタイトルを返します</entry>
                            <entry>String</entry>
                        </row>
                        <row>
                            <entry><code>getUrl()</code></entry>
                            <entry>投稿の URL を返します</entry>
                            <entry>String</entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
        </sect3>
    </sect2>
    <sect2 id="zend.service.delicious.httpclient">
        <title>HTTP クライアント</title>
        <para>
            <classname>Zend_Service_Delicious</classname> は、<code>Zend_Rest_Client</code>
            を使用して del.icio.us ウェブサービスへの HTTP リクエストを作成します。
            <classname>Zend_Service_Delicious</classname> が使用する HTTP
            クライアントを変更するには、<classname>Zend_Rest_Client</classname>
            の HTTP クライアントを変更する必要があります。
        </para>
        <example id="zend.service.delicious.httpclient.changing">
            <title><classname>Zend_Rest_Client</classname> の HTTP クライアントの変更</title>
            <programlisting role="php"><![CDATA[
$myHttpClient = new My_Http_Client();
Zend_Rest_Client::setHttpClient($myHttpClient);
]]>
            </programlisting>
        </example>
        <para>
            <classname>Zend_Service_Delicious</classname> で複数のリクエストを作成する際に
            それを高速化するなら、接続をキープするように HTTP クライアントを設定するとよいでしょう。
        </para>
        <example id="zend.service.delicious.httpclient.keepalive">
            <title>HTTP クライアントを、接続を保持し続けるように設定する</title>
            <programlisting role="php"><![CDATA[
Zend_Rest_Client::getHttpClient()->setConfig(array(
        'keepalive' => true
));
]]>
            </programlisting>
        </example>
        <note>
            <para>
                <classname>Zend_Service_Delicious</classname> オブジェクトを作成する際に、
                <classname>Zend_Rest_Client</classname> の SSL トランスポートは
                <code>'ssl'</code> と設定されます。デフォルトの <code>'ssl2'</code>
                ではありません。これは、del.icio.us 側の問題で、
                <code>'ssl2'</code> を使用するとリクエストの処理に時間がかかる
                (ほぼ 2 秒くらい) ためです。
            </para>
        </note>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->