documentation/manual/ja/module_specs/Zend_Service_Nirvanix.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <!-- EN-Revision: 20843 -->
   4 <sect1 id="zend.service.nirvanix">
   5     <title>Zend_Service_Nirvanix</title>
   6
   7     <sect2 id="zend.service.nirvanix.introduction">
   8         <title>導入</title>
   9
  10         <para>
  11             Nirvanix は Internet Media File System (<acronym>IMFS</acronym>)
  12             です。インターネット上のストレージサービスに対して
  13             ファイルをアップロードして保存し、ファイルを管理します。
  14             また、標準的なウェブサービスインターフェイスでファイルにアクセスできます。
  15             <acronym>IMFS</acronym> はクラスタ形式のファイルシステムで、インターネット越しにアクセスします。
  16             また、メディアファイル (音声や動画など) に最適化されています。
  17             <acronym>IMFS</acronym> の目標は、ますます増えていくメディアストレージに対応する
  18             スケーラビリティを提供すること、
  19             そしていつでもどこでもそこにアクセスできることを保証することです。
  20             最後に、<acronym>IMFS</acronym> を使用すればアプリケーションからデータに対して
  21             セキュアにアクセスできるようになります。また、
  22             物理的なストレージを確保したり保守したりするためのコストも回避できます。
  23         </para>
  24     </sect2>
  25
  26     <sect2 id="zend.service.nirvanix.registering">
  27         <title>Nirvanix への登録</title>
  28
  29         <para>
  30             <classname>Zend_Service_Nirvanix</classname> を使う前に、
  31             まずアカウントを取得する必要があります。詳細な情報は、
  32             Nirvanix のウェブサイトにある
  33             <ulink url="http://www.nirvanix.com/gettingStarted.aspx">Getting Started</ulink>
  34             を参照ください。
  35         </para>
  36
  37         <para>
  38             登録を済ませると、ユーザ名とパスワードそしてアプリケーションキーが得られます。
  39             <classname>Zend_Service_Nirvanix</classname> を使うには、
  40             これらすべてが必要となります。
  41         </para>
  42     </sect2>
  43
  44     <sect2 id="zend.service.nirvanix.apiDocumentation">
  45         <title>API ドキュメント</title>
  46
  47         <para>
  48             Nirvanix <acronym>IMFS</acronym> へのアクセス方法には、<acronym>SOAP</acronym> を使用する方法と
  49             (より高速な) REST サービスを使用する方法があります。
  50             <classname>Zend_Service_Nirvanix</classname>
  51             は、REST サービスに対する比較的軽量な <acronym>PHP</acronym> 5 ラッパーを提供します。
  52         </para>
  53
  54         <para>
  55             <classname>Zend_Service_Nirvanix</classname> の狙いは
  56             Nirvanix REST サービスをより簡単に使用できるようにすることですが、
  57             Nirvanix サービス自体についてきちんと理解しておくことも大切です。
  58         </para>
  59
  60         <para>
  61             <ulink url="http://developer.nirvanix.com/sitefiles/1000/API.html">Nirvanix <acronym>API</acronym> Documentation</ulink>
  62             に、このサービスについての概要から詳細な情報までがまとめられています。
  63             このドキュメントを熟読し、
  64             <classname>Zend_Service_Nirvanix</classname>
  65             を使う際にも常に参照するようにしましょう。
  66         </para>
  67     </sect2>
  68
  69     <sect2 id="zend.service.nirvanix.features">
  70         <title>機能</title>
  71
  72         <para>
  73             Nirvanix の REST サービスは、<acronym>PHP</acronym> の
  74             <ulink url="http://www.php.net/simplexml">SimpleXML</ulink>
  75             拡張モジュールと <classname>Zend_Http_Client</classname>
  76             を使うだけでもうまく操作できます。しかしこの方法だと、
  77             リクエスト時にセッショントークンを毎回渡したり、
  78             レスポンスの内容を確認してエラーコードを調べたりといった繰り返し処理が面倒です。
  79         </para>
  80
  81         <para>
  82             <classname>Zend_Service_Nirvanix</classname> には次のような機能があります。
  83
  84             <itemizedlist>
  85                 <listitem>
  86                     <para>
  87                         Nirvanix の認証情報を一元管理し、
  88                         Nirvanix 名前空間内で使いまわします。
  89                     </para>
  90                 </listitem>
  91
  92                 <listitem>
  93                     <para>
  94                         HTTP クライアントをそのまま使うよりもより便利なプロキシオブジェクトを用意し、
  95                         REST サービスへのアクセス時に毎回 HTTP POST
  96                         リクエストを手で作成させるような手間を省きます。
  97                     </para>
  98                 </listitem>
  99
 100                 <listitem>
 101                     <para>
 102                         レスポンスオブジェクトのラッパーを用意し、
 103                         レスポンスをパースしてエラー時には例外をスローするようにします。
 104                         これにより、コマンドが成功したかどうかを調べるような
 105                         面倒くさい処理を軽減させることができます。
 106                     </para>
 107                 </listitem>
 108
 109                 <listitem>
 110                     <para>
 111                         ありがちな操作を行うための、便利なメソッドを提供します。
 112                     </para>
 113                 </listitem>
 114             </itemizedlist>
 115         </para>
 116     </sect2>
 117
 118     <sect2 id="zend.service.nirvanix.storing-your-first">
 119         <title>さぁはじめましょう</title>
 120
 121         <para>
 122             Nirvanix への登録をすませたら、
 123             <acronym>IMFS</acronym> 上にファイルを格納する準備は完了です。
 124             <acronym>IMFS</acronym> 上で必要となる作業として最もよくあるものは、
 125             新規ファイルの作成や既存ファイルのダウンロード、
 126             そしてファイルの削除といったところでしょう。
 127             <classname>Zend_Service_Nirvanix</classname>
 128             には、これら 3 つの操作のための便利なメソッドが用意されています。
 129         </para>
 130
 131         <programlisting language="php"><![CDATA[
 132 $auth = array('username' => 'your-username',
 133               'password' => 'your-password',
 134               'appKey'   => 'your-app-key');
 135
 136 $nirvanix = new Zend_Service_Nirvanix($auth);
 137 $imfs = $nirvanix->getService('IMFS');
 138
 139 $imfs->putContents('/foo.txt', 'contents to store');
 140
 141 echo $imfs->getContents('/foo.txt');
 142
 143 $imfs->unlink('/foo.txt');
 144 ]]></programlisting>
 145
 146         <para>
 147             <classname>Zend_Service_Nirvanix</classname>
 148             を利用する際の最初の手続きは常に、サービスに対する認証となります。
 149             これは、認証情報を上のように <classname>Zend_Service_Nirvanix</classname>
 150             のコンストラクタに渡すことで行います。
 151             連想配列の内容が、Nirvanix に対する POST パラメータとして直接渡されます。
 152         </para>
 153
 154         <para>
 155             Nirvanix は、ウェブサービスを
 156             <ulink url="http://developer.nirvanix.com/sitefiles/1000/API.html#_Toc175999879">名前空間</ulink>
 157             で区別しています。個々の名前空間が、関連する操作群をカプセル化しています。
 158             <classname>Zend_Service_Nirvanix</classname> のインスタンスを取得したら、
 159             <methodname>getService()</methodname> メソッドをコールして
 160             使いたい名前空間へのプロキシを作成します。
 161             上の例では、<code>IMFS</code> 名前空間へのプロキシを作成しています。
 162         </para>
 163
 164         <para>
 165             使いたい名前空間へのプロキシを取得したら、そのメソッドをコールします。
 166             プロキシ上では、REST <acronym>API</acronym> の任意のコマンドを使用できます。
 167             また、プロキシにはウェブサービスのコマンドをラップする便利なメソッドも用意されています。
 168             上の例では、<acronym>IMFS</acronym> の便利なメソッドを使用して新規ファイルを作成し、
 169             それを取得して表示し、最後にファイルを削除しています。
 170         </para>
 171     </sect2>
 172
 173     <sect2 id="zend.service.nirvanix.understanding-proxy">
 174         <title>プロキシについて</title>
 175
 176         <para>
 177             先ほどの理恵では、<methodname>getService()</methodname> メソッドを使用して
 178             <code>IMFS</code> 名前空間へのプロキシオブジェクトを取得しました。
 179             このプロキシオブジェクトを使用すると、Nirvanix の REST
 180             サービスを通常の <acronym>PHP</acronym> のメソッドコールと同じ方式で行うことができます。
 181             自分で HTTP リクエストオブジェクトを作成する方式ではこのようにはいきません。
 182         </para>
 183
 184         <para>
 185             プロキシオブジェクトには、その他の便利なメソッドも用意されています。
 186             <classname>Zend_Service_Nirvanix</classname> が用意するこれらのメソッドを使用すれば、
 187             Nirvanix ウェブサービスをよりシンプルに使用できます。
 188             先ほどの例では
 189             <methodname>putContents()</methodname> や <methodname>getContents()</methodname>、
 190             そして <methodname>unlink()</methodname> といったメソッドを使用していますが、
 191             REST <acronym>API</acronym> にはこれらに直接対応するものは存在しません。
 192             これらのメソッドは <classname>Zend_Service_Nirvanix</classname>
 193             が提供しているもので、REST <acronym>API</acronym> 上でのより複雑な操作を抽象化したものです。
 194         </para>
 195
 196         <para>
 197             プロキシオブジェクトに対するその他のすべてのメソッドコールは、
 198             プロキシによって動的に変換され、同等の REST <acronym>API</acronym>
 199             に対する HTTP POST リクエストとなります。
 200             これは、メソッド名を <acronym>API</acronym> のコマンドとして使用し、
 201             最初の引数に渡した連想配列を POST パラメータとして使用します。
 202         </para>
 203
 204         <para>
 205             たとえば、REST <acronym>API</acronym> のメソッド
 206             <ulink url="http://developer.nirvanix.com/sitefiles/1000/API.html#_Toc175999923">RenameFile</ulink>
 207             をコールすることを考えてみましょう。このメソッドに対応する便利なメソッドは
 208             <classname>Zend_Service_Nirvanix</classname> には用意されていません。
 209         </para>
 210
 211         <programlisting language="php"><![CDATA[
 212 $auth = array('username' => 'your-username',
 213               'password' => 'your-password',
 214               'appKey'   => 'your-app-key');
 215
 216 $nirvanix = new Zend_Service_Nirvanix($auth);
 217 $imfs = $nirvanix->getService('IMFS');
 218
 219 $result = $imfs->renameFile(array('filePath' => '/path/to/foo.txt',
 220                                   'newFileName' => 'bar.txt'));
 221 ]]></programlisting>
 222
 223         <para>
 224             上の例では、<code>IMFS</code> 名前空間へのプロキシを作成します。
 225             そして、プロキシ上で <methodname>renameFile()</methodname> メソッドをコールします。
 226             このメソッドは <acronym>PHP</acronym> のコード上では定義されていないので、
 227             <methodname>__call()</methodname> に渡されます。
 228             そして、REST <acronym>API</acronym> に対する POST リクエストに変換され、
 229             連想配列を POST パラメータとして使用します。
 230         </para>
 231
 232         <para>
 233             Nirvanix の <acronym>API</acronym> ドキュメントには、このメソッドには <code>sessionToken</code>
 234             が必須であるとかかれていますが、プロキシオブジェクトにこれを渡していません。
 235             これは、利便性を考慮して自動的に付加されるようになっています。
 236         </para>
 237
 238         <para>
 239             この操作の結果は <classname>Zend_Service_Nirvanix_Response</classname>
 240             オブジェクトで返されます。これは Nirvanix が返す XML
 241             をラップしたものです。エラーが発生した場合は
 242             <classname>Zend_Service_Nirvanix_Exception</classname>
 243             を返します。
 244         </para>
 245     </sect2>
 246
 247     <sect2 id="zend.service.nirvanix.examining-results">
 248         <title>結果の吟味</title>
 249
 250         <para>
 251             Nirvanix の REST <acronym>API</acronym> は、常に結果を XML で返します。
 252             <classname>Zend_Service_Nirvanix</classname> は、この XML を
 253             <code>SimpleXML</code> 拡張モジュールでパースして、
 254             結果として得られた <code>SimpleXMLElement</code>
 255             を <classname>Zend_Service_Nirvanix_Response</classname>
 256             オブジェクトに変換します。
 257         </para>
 258
 259         <para>
 260             サービスから返された結果の内容を調べるいちばん簡単な方法は、
 261             <acronym>PHP</acronym> の組み込み関数である <methodname>print_r()</methodname>
 262             などを使用することです。
 263         </para>
 264
 265         <programlisting language="php"><![CDATA[
 266 <?php
 267 $auth = array('username' => 'your-username',
 268               'password' => 'your-password',
 269               'appKey'   => 'your-app-key');
 270
 271 $nirvanix = new Zend_Service_Nirvanix($auth);
 272 $imfs = $nirvanix->getService('IMFS');
 273
 274 $result = $imfs->putContents('/foo.txt', 'fourteen bytes');
 275 print_r($result);
 276 ?>
 277
 278 Zend_Service_Nirvanix_Response Object
 279 (
 280     [_sxml:protected] => SimpleXMLElement Object
 281         (
 282             [ResponseCode] => 0
 283             [FilesUploaded] => 1
 284             [BytesUploaded] => 14
 285         )
 286 )
 287 ]]></programlisting>
 288
 289         <para>
 290             <code>SimpleXMLElement</code> の任意のプロパティやメソッドにアクセスできます。
 291             上の例では、<code>$result->BytesUploaded</code> を使用して
 292             取得したバイト数を調べています。<code>SimpleXMLElement</code>
 293             に直接アクセスしたい場合は <code>$result->getSxml()</code> を使用します。
 294         </para>
 295
 296         <para>
 297             Nirvanix からの帰り値のほとんどは、成功を表すもの (<code>ResponseCode</code> がゼロ)
 298             です。通常は <code>ResponseCode</code> をチェックする必要はありません。
 299             というのも、結果がゼロ以外になる場合は
 300             <classname>Zend_Service_Nirvanix_Exception</classname> がスローされるからです。
 301             エラー処理については次のセクションを参照ください。
 302         </para>
 303     </sect2>
 304
 305     <sect2 id="zend.service.nirvanix.handling-errors">
 306         <title>エラー処理</title>
 307
 308         <para>
 309             Nirvanix を使用する際には、
 310             サービスからエラーが返されることも想定して
 311             適切にエラー処理を行うようにすることが大切です。
 312         </para>
 313
 314         <para>
 315             REST サービスに対するすべて操作の結果は XML で返され、
 316             その中には <code>ResponseCode</code> 要素が含まれています。
 317             たとえば次のようになります。
 318         </para>
 319
 320         <programlisting language="xml"><![CDATA[
 321 <Response>
 322    <ResponseCode>0</ResponseCode>
 323 </Response>
 324 ]]></programlisting>
 325
 326         <para>
 327             上の例のように <code>ResponseCode</code> がゼロの場合は、
 328             その操作が成功したことを表します。操作が成功しなかった場合は
 329             <code>ResponseCode</code> がゼロ以外の値となり、さらに
 330             <code>ErrorMessage</code> 要素が含まれるようになります。
 331         </para>
 332
 333         <para>
 334             <code>ResponseCode</code> がゼロでないかどうかを
 335             毎回チェックするのは手間がかかるので、
 336             <classname>Zend_Service_Nirvanix</classname> は自動的に
 337             Nirvanix が返す各レスポンスの内容をチェックします。
 338             <code>ResponseCode</code> がエラーを表す値であった場合は
 339             <classname>Zend_Service_Nirvanix_Exception</classname> がスローされます。
 340         </para>
 341
 342         <programlisting language="xml"><![CDATA[
 343 $auth = array('username' => 'your-username',
 344               'password' => 'your-password',
 345               'appKey'   => 'your-app-key');
 346 $nirvanix = new Zend_Service_Nirvanix($auth);
 347
 348 try {
 349
 350   $imfs = $nirvanix->getService('IMFS');
 351   $imfs->unlink('/a-nonexistant-path');
 352
 353 } catch (Zend_Service_Nirvanix_Exception $e) {
 354   echo $e->getMessage() . "\n";
 355   echo $e->getCode();
 356 }
 357 ]]></programlisting>
 358
 359         <para>
 360             上の例で使用している <methodname>unlink()</methodname> は、REST <acronym>API</acronym> の
 361             <code>DeleteFiles</code> コマンドをラップした便利なメソッドです。
 362             <ulink url="http://developer.nirvanix.com/sitefiles/1000/API.html#_Toc175999918">DeleteFiles</ulink>
 363             コマンドが要求する The <code>filePath</code> パラメータに、
 364             存在しないパスを指定しています。その結果、
 365             <classname>Zend_Service_Nirvanix</classname> からは例外がスローされます。
 366             メッセージは "Invalid path"、そしてコードは 70005 となります。
 367         </para>
 368
 369         <para>
 370             <ulink url="http://developer.nirvanix.com/sitefiles/1000/API.html">Nirvanix
 371             <acronym>API</acronym> ドキュメント</ulink> に、各コマンドに関連するエラーが説明されています。
 372             必要に応じて、各コマンドを <code>try</code> ブロックでラップするようにしましょう。
 373             あるいは複数のコマンドをひとつの <code>try</code> ブロックにまとめてもかまいません。
 374         </para>
 375     </sect2>
 376
 377 </sect1>