documentation/manual/ja/module_specs/Zend_Service_Delicious.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <!-- EN-Revision: 20854 -->
   4 <sect1 id="zend.service.delicious">
   5     <title>Zend_Service_Delicious</title>
   6     <sect2 id="zend.service.delicious.introduction">
   7         <title>導入</title>
   8         <para>
   9             <classname>Zend_Service_Delicious</classname> は、
  10             <ulink url="http://del.icio.us">del.icio.us</ulink>
  11             の <acronym>XML</acronym> および <acronym>JSON</acronym>
  12             ウェブサービスを使用するためのシンプルな <acronym>API</acronym> です。
  13             このコンポーネントによって、del.icio.us への投稿のうち、
  14             権限を持っているものについての読み書きが可能になります。
  15             全ユーザの公開データへの読み込み専用のアクセスも可能です。
  16         </para>
  17         <example id="zend.service.delicious.introduction.getAllPosts">
  18             <title>すべての投稿の取得</title>
  19             <programlisting language="php"><![CDATA[
  20 $delicious = new Zend_Service_Delicious('ユーザ名', 'パスワード');
  21 $posts = $delicious->getAllPosts();
  22
  23 foreach ($posts as $post) {
  24     echo "--\n";
  25     echo "タイトル: {$post->getTitle()}\n";
  26     echo "URL: {$post->getUrl()}\n";
  27 }
  28 ]]></programlisting>
  29         </example>
  30     </sect2>
  31     <sect2 id="zend.service.delicious.retrieving_posts">
  32         <title>投稿の取得</title>
  33         <para>
  34             <classname>Zend_Service_Delicious</classname> には、投稿を取得するメソッドとして
  35             <methodname>getPosts()</methodname>、<methodname>getRecentPosts()</methodname>
  36             および <methodname>getAllPosts()</methodname> の三種類があります。
  37             これらはすべて <classname>Zend_Service_Delicious_PostList</classname>
  38             のインスタンスを返します。ここに、取得したすべての投稿が含まれます。
  39         </para>
  40         <programlisting language="php"><![CDATA[
  41 /**
  42  * 引数にマッチする投稿を取得する。日付や url を省略した場合は
  43  * 直近の日付を使用する
  44  *
  45  * @param string $tag オプションで、タグによる絞込みを行う
  46  * @param Zend_Date $dt オプションで、日付による絞込みを行う
  47  * @param string $url オプションで、url による絞込みを行う
  48  * @return Zend_Service_Delicious_PostList
  49  */
  50 public function getPosts($tag = null, $dt = null, $url = null);
  51
  52 /**
  53  * 直近の投稿を取得する
  54  *
  55  * @param string $tag   オプションで、タグによる絞込みを行う
  56  * @param string $count 返す投稿の最大数 (デフォルトは 15)
  57  * @return Zend_Service_Delicious_PostList
  58  */
  59 public function getRecentPosts($tag = null, $count = 15);
  60
  61 /**
  62  * すべての投稿を取得する
  63  *
  64  * @param string $tag オプションで、タグによる絞込みを行う
  65  * @return Zend_Service_Delicious_PostList
  66  */
  67 public function getAllPosts($tag = null);
  68 ]]></programlisting>
  69     </sect2>
  70     <sect2 id="zend.service.delicious.postlist">
  71         <title>Zend_Service_Delicious_PostList</title>
  72         <para>
  73             <classname>Zend_Service_Delicious</classname> のメソッド <methodname>getPosts()</methodname>、<methodname>getAllPosts()</methodname>、
  74             <methodname>getRecentPosts()</methodname> および <methodname>getUserPosts()</methodname>
  75             が、このクラスのインスタンスを返します。
  76         </para>
  77         <para>
  78             データへのアクセスを簡単に行うため、このクラスは
  79             <code>Countable</code>、<code>Iterator</code> および
  80             <code>ArrayAccess</code> の三つのインターフェイスを実装しています。
  81         </para>
  82         <example id="zend.service.delicious.postlist.accessing_post_lists">
  83             <title>投稿一覧へのアクセス</title>
  84             <programlisting language="php"><![CDATA[
  85 $delicious = new Zend_Service_Delicious('ユーザ名', 'パスワード');
  86 $posts = $delicious->getAllPosts();
  87
  88 // 投稿数を数えます
  89 echo count($posts);
  90
  91 // 投稿を順次処理します
  92 foreach ($posts as $post) {
  93     echo "--\n";
  94     echo "タイトル: {$post->getTitle()}\n";
  95     echo "URL: {$post->getUrl()}\n";
  96 }
  97
  98 // 配列風のアクセス方式で投稿を取得します
  99 echo $posts[0]->getTitle();
 100 ]]></programlisting>
 101         </example>
 102         <note>
 103             <para>
 104                 メソッド <methodname>ArrayAccess::offsetSet()</methodname> および <methodname>ArrayAccess::offsetUnset()</methodname>
 105                 は、この実装では例外をスローします。つまり、<methodname>unset($posts[0]);</methodname>
 106                 や <code>$posts[0] = 'A';</code> といったコードを書くと例外が発生するということです。
 107                 というのも、これらのプロパティは読み込み専用だからです。
 108             </para>
 109         </note>
 110         <para>
 111             投稿一覧オブジェクトには、二種類のフィルタリング機能が組み込まれています。
 112             タグによるフィルタリングと、<acronym>URL</acronym> によるフィルタリングです。
 113         </para>
 114         <example id="zend.service.delicious.postlist.example.withTags">
 115             <title>タグの指定による投稿一覧のフィルタリング</title>
 116             <para>
 117                 特定のタグで投稿を絞り込むには、<methodname>withTags()</methodname> を使用します。
 118                 ひとつのタグでだけ絞り込みを行う際に便利なように、
 119                 <methodname>withTag()</methodname> も用意されています。
 120             </para>
 121             <programlisting language="php"><![CDATA[
 122 $delicious = new Zend_Service_Delicious('ユーザ名', 'パスワード');
 123 $posts = $delicious->getAllPosts();
 124
 125 // タグ "php" および "zend" が指定されている投稿のみを表示します
 126 foreach ($posts->withTags(array('php', 'zend')) as $post) {
 127     echo "タイトル: {$post->getTitle()}\n";
 128     echo "URL: {$post->getUrl()}\n";
 129 }
 130 ]]></programlisting>
 131         </example>
 132         <example id="zend.service.delicious.postlist.example.byUrl">
 133             <title>URL の指定による投稿一覧のフィルタリング</title>
 134             <para>
 135                 指定した正規表現にマッチする <acronym>URL</acronym> で投稿を絞り込むには
 136                 <methodname>withUrl()</methodname> メソッドを使用します。
 137             </para>
 138             <programlisting language="php"><![CDATA[
 139 $delicious = new Zend_Service_Delicious('ユーザ名', 'パスワード');
 140 $posts = $delicious->getAllPosts();
 141
 142 // URL に "help" を含む投稿のみを表示します
 143 foreach ($posts->withUrl('/help/') as $post) {
 144     echo "タイトル: {$post->getTitle()}\n";
 145     echo "URL: {$post->getUrl()}\n";
 146 }
 147 ]]></programlisting>
 148         </example>
 149     </sect2>
 150     <sect2 id="zend.service.delicious.editing_posts">
 151         <title>投稿の編集</title>
 152         <example id="zend.service.delicious.editing_posts.post_editing">
 153             <title>投稿の編集</title>
 154             <programlisting language="php"><![CDATA[
 155 $delicious = new Zend_Service_Delicious('ユーザ名', 'パスワード');
 156 $posts = $delicious->getPosts();
 157
 158 // タイトルを設定します
 159 $posts[0]->setTitle('新しいタイトル');
 160 // 変更を保存します
 161 $posts[0]->save();
 162 ]]></programlisting>
 163         </example>
 164         <example id="zend.service.delicious.editing_posts.method_call_chaining">
 165             <title>メソッドコールの連結</title>
 166             <para>
 167                すべての設定用メソッドは post オブジェクトを返すので、
 168                「流れるようなインターフェイス」を使用してメソッドコールを連結できます。
 169             </para>
 170             <programlisting language="php"><![CDATA[
 171 $delicious = new Zend_Service_Delicious('ユーザ名', 'パスワード');
 172 $posts = $delicious->getPosts();
 173
 174 $posts[0]->setTitle('新しいタイトル')
 175          ->setNotes('新しいメモ')
 176          ->save();
 177 ]]></programlisting>
 178         </example>
 179     </sect2>
 180     <sect2 id="zend.service.delicious.deleting_posts">
 181         <title>投稿の削除</title>
 182         <para>
 183             投稿を削除する方法は二通りあります。
 184             投稿の URL を指定するか、post オブジェクトの
 185             <methodname>delete()</methodname> メソッドを実行するかのいずれかです。
 186         </para>
 187         <example id="zend.service.delicious.deleting_posts.deleting_posts">
 188             <title>投稿の削除</title>
 189             <programlisting language="php"><![CDATA[
 190 $delicious = new Zend_Service_Delicious('ユーザ名', 'パスワード');
 191
 192 // URL を指定します
 193 $delicious->deletePost('http://framework.zend.com');
 194
 195 // あるいは、post オブジェクトのメソッドをコールします
 196 $posts = $delicious->getPosts();
 197 $posts[0]->delete();
 198
 199 // deletePost() を使用する、もうひとつの方法
 200 $delicious->deletePost($posts[0]->getUrl());
 201 ]]></programlisting>
 202         </example>
 203     </sect2>
 204     <sect2 id="zend.service.delicious.adding_posts">
 205         <title>新しい投稿の追加</title>
 206         <para>
 207             投稿を追加するには <methodname>createNewPost()</methodname> メソッドをコールする必要があります。
 208             このメソッドは <classname>Zend_Service_Delicious_Post</classname> オブジェクトを返します。
 209             投稿を編集したら、それを del.icio.us のデータベースに保存するために
 210             <methodname>save()</methodname> メソッドをコールします。
 211         </para>
 212         <example id="zend.service.delicious.adding_posts.adding_a_post">
 213             <title>投稿の追加</title>
 214             <programlisting language="php"><![CDATA[
 215 $delicious = new Zend_Service_Delicious('ユーザ名', 'パスワード');
 216
 217 // 新しい投稿を作成し、保存します (メソッドコールの連結を使用します)
 218 $delicious->createNewPost('Zend Framework', 'http://framework.zend.com')
 219           ->setNotes('Zend Framework Homepage')
 220           ->save();
 221
 222 // 新しい投稿を作成し、保存します (メソッドコールの連結を使用しません)
 223 $newPost = $delicious->createNewPost('Zend Framework',
 224                                      'http://framework.zend.com');
 225 $newPost->setNotes('Zend Framework Homepage');
 226 $newPost->save();
 227 ]]></programlisting>
 228         </example>
 229     </sect2>
 230     <sect2 id="zend.service.delicious.tags">
 231         <title>タグ</title>
 232         <example id="zend.service.delicious.tags.tags">
 233             <title>タグ</title>
 234             <programlisting language="php"><![CDATA[
 235 $delicious = new Zend_Service_Delicious('ユーザ名', 'パスワード');
 236
 237 // すべてのタグを取得します
 238 print_r($delicious->getTags());
 239
 240 // タグ ZF の名前を zendFramework に変更します
 241 $delicious->renameTag('ZF', 'zendFramework');
 242 ]]></programlisting>
 243         </example>
 244     </sect2>
 245     <sect2 id="zend.service.delicious.bundles">
 246         <title>バンドル</title>
 247         <example id="zend.service.delicious.bundles.example">
 248             <title>バンドル</title>
 249             <programlisting language="php"><![CDATA[
 250 $delicious = new Zend_Service_Delicious('ユーザ名', 'パスワード');
 251
 252 // すべてのバンドルを取得します
 253 print_r($delicious->getBundles());
 254
 255 // someBundle というバンドルを削除します
 256 $delicious->deleteBundle('someBundle');
 257
 258 // バンドルを追加します
 259 $delicious->addBundle('newBundle', array('tag1', 'tag2'));
 260 ]]></programlisting>
 261         </example>
 262     </sect2>
 263     <sect2 id="zend.service.delicious.public_data">
 264         <title>公開データ</title>
 265         <para>
 266             del.icio.us のウェブ <acronym>API</acronym> を使用すると、全ユーザの公開データにアクセスできるようになります。
 267         </para>
 268         <table id="zend.service.delicious.public_data.functions_for_retrieving_public_data">
 269             <title>公開データを取得するためのメソッド</title>
 270             <tgroup cols="3">
 271                 <thead>
 272                     <row>
 273                         <entry>名前</entry>
 274                         <entry>説明</entry>
 275                         <entry>返り値の型</entry>
 276                     </row>
 277                 </thead>
 278                 <tbody>
 279                     <row>
 280                         <entry><methodname>getUserFans()</methodname></entry>
 281                         <entry>あるユーザのファンを取得します</entry>
 282                         <entry>Array</entry>
 283                     </row>
 284                     <row>
 285                         <entry><methodname>getUserNetwork()</methodname></entry>
 286                         <entry>あるユーザのネットワークを取得します</entry>
 287                         <entry>Array</entry>
 288                     </row>
 289                     <row>
 290                         <entry><methodname>getUserPosts()</methodname></entry>
 291                         <entry>あるユーザの投稿を取得します</entry>
 292                         <entry>Zend_Service_Delicious_PostList</entry>
 293                     </row>
 294                     <row>
 295                         <entry><methodname>getUserTags()</methodname></entry>
 296                         <entry>あるユーザのタグを取得します</entry>
 297                         <entry>Array</entry>
 298                     </row>
 299                 </tbody>
 300             </tgroup>
 301         </table>
 302         <note>
 303             <para>
 304                 これらのメソッドを使用するだけなら、
 305                 <classname>Zend_Service_Delicious</classname> オブジェクトの作成時に
 306                 ユーザ名とパスワードを指定する必要はありません。
 307             </para>
 308         </note>
 309         <example id="zend.service.delicious.public_data.retrieving_public_data">
 310             <title>公開データの取得</title>
 311             <programlisting language="php"><![CDATA[
 312 // ユーザ名とパスワードは不要です
 313 $delicious = new Zend_Service_Delicious();
 314
 315 // someUser のファンを取得します
 316 print_r($delicious->getUserFans('someUser'));
 317
 318 // someUser のネットワークを取得します
 319 print_r($delicious->getUserNetwork('someUser'));
 320
 321 // someUser のタグを取得します
 322 print_r($delicious->getUserTags('someUser'));
 323 ]]></programlisting>
 324         </example>
 325         <sect3 id="zend.service.delicious.public_data.posts">
 326             <title>公開投稿</title>
 327             <para>
 328                 公開投稿を <methodname>getUserPosts()</methodname> メソッドで取得すると、
 329                 <classname>Zend_Service_Delicious_PostList</classname> オブジェクトが返されます。ここには
 330                 <classname>Zend_Service_Delicious_SimplePost</classname> オブジェクトが含まれ、
 331                 その中には <acronym>URL</acronym> やタイトル、メモ、タグといった投稿に関する基本情報が含まれます。
 332             </para>
 333             <table id="zend.service.delicious.public_data.posts.SimplePost_methods">
 334                 <title>Zend_Service_Delicious_SimplePost クラスのメソッド</title>
 335                 <tgroup cols="3">
 336                     <thead>
 337                         <row>
 338                             <entry>名前</entry>
 339                             <entry>説明</entry>
 340                             <entry>返り値の型</entry>
 341                         </row>
 342                     </thead>
 343                     <tbody>
 344                         <row>
 345                             <entry><methodname>getNotes()</methodname></entry>
 346                             <entry>投稿のメモを返します</entry>
 347                             <entry>String</entry>
 348                         </row>
 349                         <row>
 350                             <entry><methodname>getTags()</methodname></entry>
 351                             <entry>投稿のタグを返します</entry>
 352                             <entry>Array</entry>
 353                         </row>
 354                         <row>
 355                             <entry><methodname>getTitle()</methodname></entry>
 356                             <entry>投稿のタイトルを返します</entry>
 357                             <entry>String</entry>
 358                         </row>
 359                         <row>
 360                             <entry><methodname>getUrl()</methodname></entry>
 361                             <entry>投稿の <acronym>URL</acronym> を返します</entry>
 362                             <entry>String</entry>
 363                         </row>
 364                     </tbody>
 365                 </tgroup>
 366             </table>
 367         </sect3>
 368     </sect2>
 369     <sect2 id="zend.service.delicious.httpclient">
 370         <title>HTTP クライアント</title>
 371         <para>
 372             <classname>Zend_Service_Delicious</classname> は、<code>Zend_Rest_Client</code>
 373             を使用して del.icio.us ウェブサービスへの <acronym>HTTP</acronym> リクエストを作成します。
 374             <classname>Zend_Service_Delicious</classname> が使用する <acronym>HTTP</acronym>
 375             クライアントを変更するには、<classname>Zend_Rest_Client</classname>
 376             の <acronym>HTTP</acronym> クライアントを変更する必要があります。
 377         </para>
 378         <example id="zend.service.delicious.httpclient.changing">
 379             <title>Zend_Rest_Client の HTTP クライアントの変更</title>
 380             <programlisting language="php"><![CDATA[
 381 $myHttpClient = new My_Http_Client();
 382 Zend_Rest_Client::setHttpClient($myHttpClient);
 383 ]]></programlisting>
 384         </example>
 385         <para>
 386             <classname>Zend_Service_Delicious</classname> で複数のリクエストを作成する際に
 387             それを高速化するなら、接続をキープするように <acronym>HTTP</acronym> クライアントを設定するとよいでしょう。
 388         </para>
 389         <example id="zend.service.delicious.httpclient.keepalive">
 390             <title>HTTP クライアントを、接続を保持し続けるように設定する</title>
 391             <programlisting language="php"><![CDATA[
 392 Zend_Rest_Client::getHttpClient()->setConfig(array(
 393         'keepalive' => true
 394 ));
 395 ]]></programlisting>
 396         </example>
 397         <note>
 398             <para>
 399                 <classname>Zend_Service_Delicious</classname> オブジェクトを作成する際に、
 400                 <classname>Zend_Rest_Client</classname> の <acronym>SSL</acronym> トランスポートは
 401                 <code>'ssl'</code> と設定されます。デフォルトの <code>'ssl2'</code>
 402                 ではありません。これは、del.icio.us 側の問題で、
 403                 <code>'ssl2'</code> を使用するとリクエストの処理に時間がかかる
 404                 (ほぼ 2 秒くらい) ためです。
 405             </para>
 406         </note>
 407     </sect2>
 408 </sect1>
 409 <!--
 410 vim:se ts=4 sw=4 et:
 411 -->