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

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

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

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

Zend_Service_StrikeIron を使用するには、まず StrikeIron 開発者アカウントを取得するために 登録 する必要があります。

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

また、StrikeIron の Super Data Pack Web Service にも 登録 する必要があります。

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

StrikeIron のアカウントを 取得 して Super Data Pack にも参加したら、Zend_Service_StrikeIron を使うための準備は完了です。

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

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

$strikeIron = new Zend_Service_StrikeIron(array('username' => 'あなたのユーザ名',
                                                'password' => 'あなたのパスワード'));

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

getService() メソッドは、StrikeIron のサービス用のクライアントを帰します。引数には PHP のラッパークラスの名前を指定します。 この場合の SalesUseTaxBasic は、ラッパークラス Zend_Service_StrikeIron_SalesUseTaxBasic を指しています。標準で組み込まれている 3 つのラッパーについては バンドルされているサービス で説明します。

getService() は、対応する PHP ラッパーを持たない StrikeIron サービス用のクライアントも返すことができます。 この機能については WSDL によるサービスの使用 で説明します。

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

$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;

上の例では、getService() メソッドを使用して Sales & Use Tax Basic サービス用のクライアントを取得しています。 取得したオブジェクトは $taxBasic に保存します。

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

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

StrikeIron のサービスの多くは、この例と同じくらい簡単に使用できます。 3 つの StrikeIron サービスについての詳細は バンドルされているサービス を参照ください。

StrikeIron サービスについて学習したりデバッグしたりする際には、 メソッドから返された内容を出力できると便利です。 メソッドの返り値は常に Zend_Service_StrikeIron_Decorator のインスタンスとなります。 これはちょっとした デコレータ オブジェクトであり、メソッドのコール結果をラップしています。

サービスが返した結果を調べる最も単純な方法は、 print_r() のような PHP の組み込み関数を使うことです。

<?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
        )
)

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

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

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

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

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

$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) {

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

}

スローされる例外は、常に Zend_Service_StrikeIron_Exception となります。

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

StrikeIron にはさまざまなサービスがあります。 その中には無料で使えるものもあればお試し版のものもあります。 また、有料サービスのみのものもあります。 StrikeIron を使用するにあたっては、 そのサービスの購入状況を常に確認することが必要です。

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

// 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;

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

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