[ZF-10089] Zend_Log

[zend.git] / documentation / manual / ja / module_specs / Zend_Service_StrikeIron-Overview.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 21740 -->
<sect1 id="zend.service.strikeiron">
    <title>Zend_Service_StrikeIron</title>

    <para>
        <classname>Zend_Service_StrikeIron</classname> は、StrikeIron
        ウェブサービス用の <acronym>PHP</acronym> 5 クライアントです。以下のセクションを参照ください。
    </para>

    <para>
        <itemizedlist>
            <listitem><para><xref linkend="zend.service.strikeiron" /></para></listitem>
        </itemizedlist>
        <itemizedlist>
            <listitem><para><xref linkend="zend.service.strikeiron.bundled-services" /></para></listitem>
        </itemizedlist>
        <itemizedlist>
            <listitem><para><xref linkend="zend.service.strikeiron.advanced-uses" /></para></listitem>
        </itemizedlist>
    </para>

    <sect2 id="zend.service.strikeiron.overview">
        <title>概要</title>

        <para>
          <ulink url="http://www.strikeiron.com">StrikeIron</ulink>
          は、さまざまな商用データサービス ("Data as a Service") を提供しています。たとえば
          Online Sales Tax, Currency Rates, Stock Quotes, Geocodes, Global
          Address Verification, Yellow/White Pages, MapQuest Driving Directions,
          Dun &amp; Bradstreet Business Credit Checks などのサービスがあります。
        </para>

        <para>
          StrikeIron ウェブサービスの各サービスは、標準の <acronym>SOAP</acronym> (および REST)
          <acronym>API</acronym> を共有しています。これにより、複数のサービスを統合して管理するのが簡単になります。
          StrikeIron はまた、すべてのサービスの支払いを単一のアカウントで管理しています。
          ソリューションプロバイダにとって完璧な環境といえます。
          <ulink url="http://www.strikeiron.com/sdp">http://www.strikeiron.com/sdp</ulink>
          で、フリーなウェブサービスを試してみましょう。
        </para>

        <para>
          StrikeIron のサービスは、
          <ulink url="http://jp.php.net/soap"><acronym>PHP</acronym> 5 の <acronym>SOAP</acronym> 拡張モジュール</ulink>
          のみでも使用することができるでしょう。
          しかし、StrikeIron をこの方法で使用すると、
          真の <acronym>PHP</acronym> 風インターフェイスを活用することができません。
          <classname>Zend_Service_StrikeIron</classname> コンポーネントは、<acronym>SOAP</acronym>
          拡張モジュールの上にもう一枚薄い皮をかぶせることによって、
          StrikeIron のサービスをより便利かつ <acronym>PHP</acronym>
          らしく使えるようにしています。
        </para>

        <note>
          <para>
            <classname>Zend_Service_StrikeIron</classname> を使うには、
            <acronym>PHP</acronym> 5 の <acronym>SOAP</acronym> 拡張モジュールがインストールされて有効になっている必要があります。
          </para>
        </note>

        <para>
          <classname>Zend_Service_StrikeIron</classname> コンポーネントが提供する機能を以下にまとめます。

          <itemizedlist>
            <listitem>
              <para>
                StrikeIron の認証情報の一元管理により、
                さまざまな StrikeIron サービスで使用可能。
              </para>
            </listitem>

            <listitem>
              <para>
                StrikeIron のさまざまな登録情報
                (ライセンスの状態や残りの使用回数など)
                の標準的な方法での取得。
              </para>
            </listitem>

            <listitem>
              <para>
                <acronym>PHP</acronym> のラッパークラスを作成しなくても、WSDL
                だけで StrikeIcon サービスが使用可能。
                また、ラッパーを作成することで、
                より便利なインターフェイスを使用することも可能。
              </para>
            </listitem>

            <listitem>
              <para>
                StrikeIron のサービスのうち、人気のある 3 つについてのラッパー。
              </para>
            </listitem>
          </itemizedlist>
        </para>

    </sect2>

    <sect2 id="zend.service.strikeiron.registering">
      <title>StrikeIron への登録</title>
      <para>
        <classname>Zend_Service_StrikeIron</classname> を使用するには、まず
        StrikeIron 開発者アカウントを取得するために
        <ulink url="http://strikeiron.com/Register.aspx">登録</ulink>
        する必要があります。
      </para>

      <para>
        登録したら、StrikeIron のユーザ名とパスワードを受け取ります。
        <classname>Zend_Service_StrikeIron</classname> で StrikeIron に接続する際には、
        このユーザ名とパスワードを使用します。
      </para>

      <para>
        また、StrikeIron の Super Data Pack Web Service にも
        <ulink url="http://www.strikeiron.com/ProductDetail.aspx?p=257">登録</ulink>
        する必要があります。
      </para>

      <para>
        どちらの登録処理も無料です。
        StrikeIron のウェブサイト上で比較的速やかに行えます。
      </para>
    </sect2>

    <sect2 id="zend.service.strikeiron.getting-started">
      <title>では、はじめましょう</title>
      <para>
        StrikeIron のアカウントを
        <ulink url="http://strikeiron.com/Register.aspx">取得</ulink>
        して
        <ulink url="http://www.strikeiron.com/ProductDetail.aspx?p=257">Super Data Pack</ulink>
        にも参加したら、<classname>Zend_Service_StrikeIron</classname>
        を使うための準備は完了です。
      </para>

      <para>
        StrikeIron には何百ものさまざまなウェブサービスが存在します。
        Zend_Service_StrikeIron はこれらのサービスの多くで利用可能ですが、
        特に以下の 3 つについてはラッパークラスを用意しています。
      </para>

      <itemizedlist>
        <listitem>
          <para><link linkend="zend.service.strikeiron.bundled-services.zip-code-information">ZIP Code Information</link></para>
        </listitem>
        <listitem>
          <para><link linkend="zend.service.strikeiron.bundled-services.us-address-verification">US Address Verification</link></para>
        </listitem>
        <listitem>
          <para><link linkend="zend.service.strikeiron.bundled-services.sales-use-tax-basic">Sales &amp; Use Tax Basic</link></para>
        </listitem>
      </itemizedlist>

      <para>
        <classname>Zend_Service_StrikeIron</classname> クラスには、
        そのコンストラクタで StrikeIron アカウント情報やその他のオプションを設定できます。
        また、StrikeIron の各種サービス用のクライアントを帰すファクトリメソッドも用意しています。

        <programlisting language="php"><![CDATA[
$strikeIron = new Zend_Service_StrikeIron(array('username' => 'あなたのユーザ名',
                                                'password' => 'あなたのパスワード'));

$taxBasic = $strikeIron->getService(array('class' => 'SalesUseTaxBasic'));
]]></programlisting>
      </para>

      <para>
        <methodname>getService()</methodname> メソッドは、StrikeIron
        のサービス用のクライアントを帰します。引数には
        <acronym>PHP</acronym> のラッパークラスの名前を指定します。
        この場合の <code>SalesUseTaxBasic</code> は、ラッパークラス
        <classname>Zend_Service_StrikeIron_SalesUseTaxBasic</classname>
        を指しています。標準で組み込まれている 3 つのラッパーについては
        <link linkend="zend.service.strikeiron.bundled-services">バンドルされているサービス</link>
        で説明します。
      </para>

      <para>
        <methodname>getService()</methodname> は、対応する <acronym>PHP</acronym>
        ラッパーを持たない StrikeIron サービス用のクライアントも返すことができます。
        この機能については
        <link linkend="zend.service.strikeiron.advanced-uses.services-by-wsdl">WSDL によるサービスの使用</link>
        で説明します。
      </para>
    </sect2>

    <sect2 id="zend.service.strikeiron.making-first-query">
      <title>はじめてのクエリ</title>

      <para>
        <methodname>getService()</methodname> で StrikeIron サービス用のクライアントを取得したら、
        あとは普通の <acronym>PHP</acronym> オブジェクトと同様にそのメソッドをコールできます。

        <programlisting language="php"><![CDATA[
$strikeIron = new Zend_Service_StrikeIron(array('username' => 'あなたのユーザ名',
                                                'password' => 'あなたのパスワード'));

// Sales & Use Tax Basic サービス用のクライアントを取得します
$taxBasic = $strikeIron->getService(array('class' => 'SalesUseTaxBasic'));

// カナダのオンタリオ州の税率を取得します
$rateInfo = $taxBasic->getTaxRateCanada(array('province' => 'ontario'));
echo $rateInfo->province;
echo $rateInfo->abbreviation;
echo $rateInfo->GST;
]]></programlisting>

        上の例では、<methodname>getService()</methodname> メソッドを使用して
        <link linkend="zend.service.strikeiron.bundled-services.sales-use-tax-basic">Sales &amp; Use Tax Basic</link>
        サービス用のクライアントを取得しています。
        取得したオブジェクトは <code>$taxBasic</code> に保存します。
      </para>

      <para>
        次に、そのサービスの <methodname>getTaxRateCanada()</methodname>
        メソッドをコールします。メソッドに対してキーワードパラメータを渡すには
        連想配列を使用します。これは、すべての StrikeIron
        のメソッドで共通の方法です。
      </para>

      <para>
        <methodname>getTaxRateCanada()</methodname> の返り値を
        <code>$rateInfo</code> に取得し、そのプロパティ <code>province</code>
        や <constant>GST</constant> を参照しています。
      </para>

      <para>
        StrikeIron のサービスの多くは、この例と同じくらい簡単に使用できます。
        3 つの StrikeIron サービスについての詳細は
        <link linkend="zend.service.strikeiron.bundled-services">バンドルされているサービス</link>
        を参照ください。
      </para>
    </sect2>

    <sect2 id="zend.service.strikeiron.examining-results">
      <title>結果の吟味</title>
      <para>
        StrikeIron サービスについて学習したりデバッグしたりする際には、
        メソッドから返された内容を出力できると便利です。
        メソッドの返り値は常に
        <classname>Zend_Service_StrikeIron_Decorator</classname> のインスタンスとなります。
        これはちょっとした
        <ulink url="http://ja.wikipedia.org/wiki/Decorator_%E3%83%91%E3%82%BF%E3%83%BC%E3%83%B3">デコレータ</ulink>
        オブジェクトであり、メソッドのコール結果をラップしています。
      </para>

      <para>
        サービスが返した結果を調べる最も単純な方法は、
        <ulink url="http://www.php.net/print_r">print_r()</ulink>
        のような <acronym>PHP</acronym> の組み込み関数を使うことです。

        <programlisting language="php"><![CDATA[
<?php
$strikeIron = new Zend_Service_StrikeIron(array('username' => 'あなたのユーザ名',
                                                'password' => 'あなたのパスワード'));

$taxBasic = $strikeIron->getService(array('class' => 'SalesUseTaxBasic'));

$rateInfo = $taxBasic->getTaxRateCanada(array('province' => 'ontario'));
print_r($rateInfo);
?>

Zend_Service_StrikeIron_Decorator Object
(
    [_name:protected] => GetTaxRateCanadaResult
    [_object:protected] => stdClass Object
        (
            [abbreviation] => ON
            [province] => ONTARIO
            [GST] => 0.06
            [PST] => 0.08
            [total] => 0.14
            [HST] => Y
        )
)
]]></programlisting>
      </para>

      <para>
        上の例でわかるように、デコレータ (<code>$rateInfo</code>) が
        <code>GetTaxRateCanadaResult</code> というオブジェクトをラップしています。
        これが <methodname>getTaxRateCanada()</methodname> の返り値です。
      </para>

      <para>
        この結果から、<code>$rateInfo</code> には <code>abbreviation</code>
        や <code>province</code>、<constant>GST</constant>
        といった公開プロパティがあることがわかります。これらは
        <code>$rateInfo->province</code> のようにしてアクセスできます。
      </para>

      <tip>
        <para>
          StrikeIron の結果のプロパティは、場合によっては大文字で始まっていることもあります
          (<code>Foo</code> や <code>Bar</code> など)。一方、たいていの <acronym>PHP</acronym>
          オブジェクトのプロパティは、普通は小文字で始まる形式 (<code>foo</code>
          や <code>bar</code> など) です。このあたりはデコレータがうまく処理するので、
          プロパティが <code>Foo</code> であっても
          <code>foo</code> として取得できるようになります。
        </para>
      </tip>

      <para>
        もしデコレータではなく中身のオブジェクトそのものやその名前がほしい場合は、
        それぞれ <methodname>getDecoratedObject()</methodname> および
        <methodname>getDecoratedObjectName()</methodname> を使用します。
      </para>
    </sect2>

    <sect2 id="zend.service.strikeiron.handling-errors">
      <title>エラー処理</title>
      <para>
        先ほどの例はあまりにも無邪気すぎるところがありました。
        エラー処理を一切していなかったのです。
        メソッドをコールした際に、StrikeIron がエラーを返す可能性だってあります。
        認証情報が間違っていたり、アカウントが有効期限切れになっていた場合などに
        StrikeIron はエラーを発します。
      </para>

      <para>
        このような場合は例外がスローされます。
        例外が発生することを想定して、
        サービスのメソッドをコールする際には例外処理を書く必要があります。

        <programlisting language="php"><![CDATA[
$strikeIron = new Zend_Service_StrikeIron(array('username' => 'あなたのユーザ名',
                                                'password' => 'あなたのパスワード'));

$taxBasic = $strikeIron->getService(array('class' => 'SalesUseTaxBasic'));

try {

  $taxBasic->getTaxRateCanada(array('province' => 'ontario'));

} catch (Zend_Service_StrikeIron_Exception $e) {

  // 接続時のエラーなどの場合の
  // エラー処理をここで行います

}
]]></programlisting>
        スローされる例外は、常に <classname>Zend_Service_StrikeIron_Exception</classname>
        となります。
      </para>

      <para>
        メソッドコール時の通常の失敗と例外の違いはしっかり把握しておきましょう。
        例外が発生するのは、<emphasis>例外的な</emphasis>
        状態です。たとえばネットワークの障害が発生したとか
        アカウントが有効期限切れになっていたとかいった状況がそれにあたります。
        通常の失敗とは、もっと頻繁に起こりえるものです。
        たとえば <methodname>getTaxRateCanada()</methodname> で指定した
        <code>province</code> が見つけられないときなどは例外とはなりません。
      </para>

      <note>
        <para>
          StrikeIron サービスのメソッドをコールする際には
          常に返り値をチェックするようにしましょう。
          もちろん例外処理も必要です。
        </para>
      </note>

      <para><!-- included for whitespace --></para>
    </sect2>

    <sect2 id="zend.service.strikeiron.checking-subscription">
      <title>購入内容の確認</title>
      <para>
        StrikeIron にはさまざまなサービスがあります。
        その中には無料で使えるものもあればお試し版のものもあります。
        また、有料サービスのみのものもあります。
        StrikeIron を使用するにあたっては、
        そのサービスの購入状況を常に確認することが必要です。
      </para>

      <para>
        <code>getService</code> メソッドが返す StrikeIron クライアントにはすべて、
        そのサービスの購入状況を調べる
        <methodname>getSubscriptionInfo()</methodname> メソッドが存在します。

        <programlisting language="php"><![CDATA[
// Sales & Use Tax Basic サービス用のクライアントを取得します
$strikeIron = new Zend_Service_StrikeIron(array('username' => 'あなたのユーザ名',
                                                'password' => 'あなたのパスワード'));

$taxBasic = $strikeIron->getService(array('class => 'SalesUseTaxBasic'));

// Sales & Use Tax Basic サービスをあと何回使用できるかを調べます
$subscription = $taxBasic->getSubscriptionInfo();
echo $subscription->remainingHits;
]]></programlisting>
      </para>

      <para>
        <methodname>getSubscriptionInfo()</methodname> メソッドが返すオブジェクトの多くには、
        <code>remainingHits</code> プロパティが含まれます。
        これを調べて、使用しているサービスの状態を確認します。
        残りの使用回数を超える数のメソッドコールを行うと、
        StrikeIron は例外をスローします。
      </para>

      <para>
        サービスの購入状況を調べる問い合わせを送っても、
        残りの使用可能回数は減りません。
        サービスのメソッドをコールする際にはいつも残りの回数を自動的に取得します。
        この値は、サービスに接続しなくても
        <methodname>getSubscriptionInfo()</methodname> で取得できます。
        キャッシュを使用せずにもう一度情報を問い合わせるよう
        <methodname>getSubscriptionInfo()</methodname> に指示するには、
        <methodname>getSubscriptionInfo(true)</methodname> とします。
      </para>
    </sect2>
</sect1>