[GENERIC] Zend_Translate:
[zend.git] / documentation / manual / ja / module_specs / Zend_Service_StrikeIron-Overview.xml
blobb7d8c6449797c7c3072e622f840a63db8b69e6f2
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- Reviewed: no -->
3 <!-- EN-Revision: 21740 -->
4 <sect1 id="zend.service.strikeiron">
5     <title>Zend_Service_StrikeIron</title>
7     <para>
8         <classname>Zend_Service_StrikeIron</classname> は、StrikeIron
9         ウェブサービス用の <acronym>PHP</acronym> 5 クライアントです。以下のセクションを参照ください。
10     </para>
12     <para>
13         <itemizedlist>
14             <listitem><para><xref linkend="zend.service.strikeiron" /></para></listitem>
15         </itemizedlist>
16         <itemizedlist>
17             <listitem><para><xref linkend="zend.service.strikeiron.bundled-services" /></para></listitem>
18         </itemizedlist>
19         <itemizedlist>
20             <listitem><para><xref linkend="zend.service.strikeiron.advanced-uses" /></para></listitem>
21         </itemizedlist>
22     </para>
24     <sect2 id="zend.service.strikeiron.overview">
25         <title>概要</title>
27         <para>
28           <ulink url="http://www.strikeiron.com">StrikeIron</ulink>
29           は、さまざまな商用データサービス ("Data as a Service") を提供しています。たとえば
30           Online Sales Tax, Currency Rates, Stock Quotes, Geocodes, Global
31           Address Verification, Yellow/White Pages, MapQuest Driving Directions,
32           Dun &amp; Bradstreet Business Credit Checks などのサービスがあります。
33         </para>
35         <para>
36           StrikeIron ウェブサービスの各サービスは、標準の <acronym>SOAP</acronym> (および REST)
37           <acronym>API</acronym> を共有しています。これにより、複数のサービスを統合して管理するのが簡単になります。
38           StrikeIron はまた、すべてのサービスの支払いを単一のアカウントで管理しています。
39           ソリューションプロバイダにとって完璧な環境といえます。
40           <ulink url="http://www.strikeiron.com/sdp">http://www.strikeiron.com/sdp</ulink>
41           で、フリーなウェブサービスを試してみましょう。
42         </para>
44         <para>
45           StrikeIron のサービスは、
46           <ulink url="http://jp.php.net/soap"><acronym>PHP</acronym> 5 の <acronym>SOAP</acronym> 拡張モジュール</ulink>
47           のみでも使用することができるでしょう。
48           しかし、StrikeIron をこの方法で使用すると、
49           真の <acronym>PHP</acronym> 風インターフェイスを活用することができません。
50           <classname>Zend_Service_StrikeIron</classname> コンポーネントは、<acronym>SOAP</acronym>
51           拡張モジュールの上にもう一枚薄い皮をかぶせることによって、
52           StrikeIron のサービスをより便利かつ <acronym>PHP</acronym>
53           らしく使えるようにしています。
54         </para>
56         <note>
57           <para>
58             <classname>Zend_Service_StrikeIron</classname> を使うには、
59             <acronym>PHP</acronym> 5 の <acronym>SOAP</acronym> 拡張モジュールがインストールされて有効になっている必要があります。
60           </para>
61         </note>
63         <para>
64           <classname>Zend_Service_StrikeIron</classname> コンポーネントが提供する機能を以下にまとめます。
66           <itemizedlist>
67             <listitem>
68               <para>
69                 StrikeIron の認証情報の一元管理により、
70                 さまざまな StrikeIron サービスで使用可能。
71               </para>
72             </listitem>
74             <listitem>
75               <para>
76                 StrikeIron のさまざまな登録情報
77                 (ライセンスの状態や残りの使用回数など)
78                 の標準的な方法での取得。
79               </para>
80             </listitem>
82             <listitem>
83               <para>
84                 <acronym>PHP</acronym> のラッパークラスを作成しなくても、WSDL
85                 だけで StrikeIcon サービスが使用可能。
86                 また、ラッパーを作成することで、
87                 より便利なインターフェイスを使用することも可能。
88               </para>
89             </listitem>
91             <listitem>
92               <para>
93                 StrikeIron のサービスのうち、人気のある 3 つについてのラッパー。
94               </para>
95             </listitem>
96           </itemizedlist>
97         </para>
99     </sect2>
101     <sect2 id="zend.service.strikeiron.registering">
102       <title>StrikeIron への登録</title>
103       <para>
104         <classname>Zend_Service_StrikeIron</classname> を使用するには、まず
105         StrikeIron 開発者アカウントを取得するために
106         <ulink url="http://strikeiron.com/Register.aspx">登録</ulink>
107         する必要があります。
108       </para>
110       <para>
111         登録したら、StrikeIron のユーザ名とパスワードを受け取ります。
112         <classname>Zend_Service_StrikeIron</classname> で StrikeIron に接続する際には、
113         このユーザ名とパスワードを使用します。
114       </para>
116       <para>
117         また、StrikeIron の Super Data Pack Web Service にも
118         <ulink url="http://www.strikeiron.com/ProductDetail.aspx?p=257">登録</ulink>
119         する必要があります。
120       </para>
122       <para>
123         どちらの登録処理も無料です。
124         StrikeIron のウェブサイト上で比較的速やかに行えます。
125       </para>
126     </sect2>
128     <sect2 id="zend.service.strikeiron.getting-started">
129       <title>では、はじめましょう</title>
130       <para>
131         StrikeIron のアカウントを
132         <ulink url="http://strikeiron.com/Register.aspx">取得</ulink>
133         して
134         <ulink url="http://www.strikeiron.com/ProductDetail.aspx?p=257">Super Data Pack</ulink>
135         にも参加したら、<classname>Zend_Service_StrikeIron</classname>
136         を使うための準備は完了です。
137       </para>
139       <para>
140         StrikeIron には何百ものさまざまなウェブサービスが存在します。
141         Zend_Service_StrikeIron はこれらのサービスの多くで利用可能ですが、
142         特に以下の 3 つについてはラッパークラスを用意しています。
143       </para>
145       <itemizedlist>
146         <listitem>
147           <para><link linkend="zend.service.strikeiron.bundled-services.zip-code-information">ZIP Code Information</link></para>
148         </listitem>
149         <listitem>
150           <para><link linkend="zend.service.strikeiron.bundled-services.us-address-verification">US Address Verification</link></para>
151         </listitem>
152         <listitem>
153           <para><link linkend="zend.service.strikeiron.bundled-services.sales-use-tax-basic">Sales &amp; Use Tax Basic</link></para>
154         </listitem>
155       </itemizedlist>
157       <para>
158         <classname>Zend_Service_StrikeIron</classname> クラスには、
159         そのコンストラクタで StrikeIron アカウント情報やその他のオプションを設定できます。
160         また、StrikeIron の各種サービス用のクライアントを帰すファクトリメソッドも用意しています。
162         <programlisting language="php"><![CDATA[
163 $strikeIron = new Zend_Service_StrikeIron(array('username' => 'あなたのユーザ名',
164                                                 'password' => 'あなたのパスワード'));
166 $taxBasic = $strikeIron->getService(array('class' => 'SalesUseTaxBasic'));
167 ]]></programlisting>
168       </para>
170       <para>
171         <methodname>getService()</methodname> メソッドは、StrikeIron
172         のサービス用のクライアントを帰します。引数には
173         <acronym>PHP</acronym> のラッパークラスの名前を指定します。
174         この場合の <code>SalesUseTaxBasic</code> は、ラッパークラス
175         <classname>Zend_Service_StrikeIron_SalesUseTaxBasic</classname>
176         を指しています。標準で組み込まれている 3 つのラッパーについては
177         <link linkend="zend.service.strikeiron.bundled-services">バンドルされているサービス</link>
178         で説明します。
179       </para>
181       <para>
182         <methodname>getService()</methodname> は、対応する <acronym>PHP</acronym>
183         ラッパーを持たない StrikeIron サービス用のクライアントも返すことができます。
184         この機能については
185         <link linkend="zend.service.strikeiron.advanced-uses.services-by-wsdl">WSDL によるサービスの使用</link>
186         で説明します。
187       </para>
188     </sect2>
190     <sect2 id="zend.service.strikeiron.making-first-query">
191       <title>はじめてのクエリ</title>
193       <para>
194         <methodname>getService()</methodname> で StrikeIron サービス用のクライアントを取得したら、
195         あとは普通の <acronym>PHP</acronym> オブジェクトと同様にそのメソッドをコールできます。
197         <programlisting language="php"><![CDATA[
198 $strikeIron = new Zend_Service_StrikeIron(array('username' => 'あなたのユーザ名',
199                                                 'password' => 'あなたのパスワード'));
201 // Sales & Use Tax Basic サービス用のクライアントを取得します
202 $taxBasic = $strikeIron->getService(array('class' => 'SalesUseTaxBasic'));
204 // カナダのオンタリオ州の税率を取得します
205 $rateInfo = $taxBasic->getTaxRateCanada(array('province' => 'ontario'));
206 echo $rateInfo->province;
207 echo $rateInfo->abbreviation;
208 echo $rateInfo->GST;
209 ]]></programlisting>
211         上の例では、<methodname>getService()</methodname> メソッドを使用して
212         <link linkend="zend.service.strikeiron.bundled-services.sales-use-tax-basic">Sales &amp; Use Tax Basic</link>
213         サービス用のクライアントを取得しています。
214         取得したオブジェクトは <code>$taxBasic</code> に保存します。
215       </para>
217       <para>
218         次に、そのサービスの <methodname>getTaxRateCanada()</methodname>
219         メソッドをコールします。メソッドに対してキーワードパラメータを渡すには
220         連想配列を使用します。これは、すべての StrikeIron
221         のメソッドで共通の方法です。
222       </para>
224       <para>
225         <methodname>getTaxRateCanada()</methodname> の返り値を
226         <code>$rateInfo</code> に取得し、そのプロパティ <code>province</code>
227         や <constant>GST</constant> を参照しています。
228       </para>
230       <para>
231         StrikeIron のサービスの多くは、この例と同じくらい簡単に使用できます。
232         3 つの StrikeIron サービスについての詳細は
233         <link linkend="zend.service.strikeiron.bundled-services">バンドルされているサービス</link>
234         を参照ください。
235       </para>
236     </sect2>
238     <sect2 id="zend.service.strikeiron.examining-results">
239       <title>結果の吟味</title>
240       <para>
241         StrikeIron サービスについて学習したりデバッグしたりする際には、
242         メソッドから返された内容を出力できると便利です。
243         メソッドの返り値は常に
244         <classname>Zend_Service_StrikeIron_Decorator</classname> のインスタンスとなります。
245         これはちょっとした
246         <ulink url="http://ja.wikipedia.org/wiki/Decorator_%E3%83%91%E3%82%BF%E3%83%BC%E3%83%B3">デコレータ</ulink>
247         オブジェクトであり、メソッドのコール結果をラップしています。
248       </para>
250       <para>
251         サービスが返した結果を調べる最も単純な方法は、
252         <ulink url="http://www.php.net/print_r">print_r()</ulink>
253         のような <acronym>PHP</acronym> の組み込み関数を使うことです。
255         <programlisting language="php"><![CDATA[
256 <?php
257 $strikeIron = new Zend_Service_StrikeIron(array('username' => 'あなたのユーザ名',
258                                                 'password' => 'あなたのパスワード'));
260 $taxBasic = $strikeIron->getService(array('class' => 'SalesUseTaxBasic'));
262 $rateInfo = $taxBasic->getTaxRateCanada(array('province' => 'ontario'));
263 print_r($rateInfo);
266 Zend_Service_StrikeIron_Decorator Object
268     [_name:protected] => GetTaxRateCanadaResult
269     [_object:protected] => stdClass Object
270         (
271             [abbreviation] => ON
272             [province] => ONTARIO
273             [GST] => 0.06
274             [PST] => 0.08
275             [total] => 0.14
276             [HST] => Y
277         )
279 ]]></programlisting>
280       </para>
282       <para>
283         上の例でわかるように、デコレータ (<code>$rateInfo</code>) が
284         <code>GetTaxRateCanadaResult</code> というオブジェクトをラップしています。
285         これが <methodname>getTaxRateCanada()</methodname> の返り値です。
286       </para>
288       <para>
289         この結果から、<code>$rateInfo</code> には <code>abbreviation</code>
290         や <code>province</code>、<constant>GST</constant>
291         といった公開プロパティがあることがわかります。これらは
292         <code>$rateInfo->province</code> のようにしてアクセスできます。
293       </para>
295       <tip>
296         <para>
297           StrikeIron の結果のプロパティは、場合によっては大文字で始まっていることもあります
298           (<code>Foo</code> や <code>Bar</code> など)。一方、たいていの <acronym>PHP</acronym>
299           オブジェクトのプロパティは、普通は小文字で始まる形式 (<code>foo</code>
300           や <code>bar</code> など) です。このあたりはデコレータがうまく処理するので、
301           プロパティが <code>Foo</code> であっても
302           <code>foo</code> として取得できるようになります。
303         </para>
304       </tip>
306       <para>
307         もしデコレータではなく中身のオブジェクトそのものやその名前がほしい場合は、
308         それぞれ <methodname>getDecoratedObject()</methodname> および
309         <methodname>getDecoratedObjectName()</methodname> を使用します。
310       </para>
311     </sect2>
313     <sect2 id="zend.service.strikeiron.handling-errors">
314       <title>エラー処理</title>
315       <para>
316         先ほどの例はあまりにも無邪気すぎるところがありました。
317         エラー処理を一切していなかったのです。
318         メソッドをコールした際に、StrikeIron がエラーを返す可能性だってあります。
319         認証情報が間違っていたり、アカウントが有効期限切れになっていた場合などに
320         StrikeIron はエラーを発します。
321       </para>
323       <para>
324         このような場合は例外がスローされます。
325         例外が発生することを想定して、
326         サービスのメソッドをコールする際には例外処理を書く必要があります。
328         <programlisting language="php"><![CDATA[
329 $strikeIron = new Zend_Service_StrikeIron(array('username' => 'あなたのユーザ名',
330                                                 'password' => 'あなたのパスワード'));
332 $taxBasic = $strikeIron->getService(array('class' => 'SalesUseTaxBasic'));
334 try {
336   $taxBasic->getTaxRateCanada(array('province' => 'ontario'));
338 } catch (Zend_Service_StrikeIron_Exception $e) {
340   // 接続時のエラーなどの場合の
341   // エラー処理をここで行います
344 ]]></programlisting>
345         スローされる例外は、常に <classname>Zend_Service_StrikeIron_Exception</classname>
346         となります。
347       </para>
349       <para>
350         メソッドコール時の通常の失敗と例外の違いはしっかり把握しておきましょう。
351         例外が発生するのは、<emphasis>例外的な</emphasis>
352         状態です。たとえばネットワークの障害が発生したとか
353         アカウントが有効期限切れになっていたとかいった状況がそれにあたります。
354         通常の失敗とは、もっと頻繁に起こりえるものです。
355         たとえば <methodname>getTaxRateCanada()</methodname> で指定した
356         <code>province</code> が見つけられないときなどは例外とはなりません。
357       </para>
359       <note>
360         <para>
361           StrikeIron サービスのメソッドをコールする際には
362           常に返り値をチェックするようにしましょう。
363           もちろん例外処理も必要です。
364         </para>
365       </note>
367       <para><!-- included for whitespace --></para>
368     </sect2>
370     <sect2 id="zend.service.strikeiron.checking-subscription">
371       <title>購入内容の確認</title>
372       <para>
373         StrikeIron にはさまざまなサービスがあります。
374         その中には無料で使えるものもあればお試し版のものもあります。
375         また、有料サービスのみのものもあります。
376         StrikeIron を使用するにあたっては、
377         そのサービスの購入状況を常に確認することが必要です。
378       </para>
380       <para>
381         <code>getService</code> メソッドが返す StrikeIron クライアントにはすべて、
382         そのサービスの購入状況を調べる
383         <methodname>getSubscriptionInfo()</methodname> メソッドが存在します。
385         <programlisting language="php"><![CDATA[
386 // Sales & Use Tax Basic サービス用のクライアントを取得します
387 $strikeIron = new Zend_Service_StrikeIron(array('username' => 'あなたのユーザ名',
388                                                 'password' => 'あなたのパスワード'));
390 $taxBasic = $strikeIron->getService(array('class => 'SalesUseTaxBasic'));
392 // Sales & Use Tax Basic サービスをあと何回使用できるかを調べます
393 $subscription = $taxBasic->getSubscriptionInfo();
394 echo $subscription->remainingHits;
395 ]]></programlisting>
396       </para>
398       <para>
399         <methodname>getSubscriptionInfo()</methodname> メソッドが返すオブジェクトの多くには、
400         <code>remainingHits</code> プロパティが含まれます。
401         これを調べて、使用しているサービスの状態を確認します。
402         残りの使用回数を超える数のメソッドコールを行うと、
403         StrikeIron は例外をスローします。
404       </para>
406       <para>
407         サービスの購入状況を調べる問い合わせを送っても、
408         残りの使用可能回数は減りません。
409         サービスのメソッドをコールする際にはいつも残りの回数を自動的に取得します。
410         この値は、サービスに接続しなくても
411         <methodname>getSubscriptionInfo()</methodname> で取得できます。
412         キャッシュを使用せずにもう一度情報を問い合わせるよう
413         <methodname>getSubscriptionInfo()</methodname> に指示するには、
414         <methodname>getSubscriptionInfo(true)</methodname> とします。
415       </para>
416     </sect2>
417 </sect1>