documentation/manual/ja/module_specs/Zend_Service_Akismet.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <!-- EN-Revision: 17409 -->
   4 <sect1 id="zend.service.akismet">
   5     <title>Zend_Service_Akismet</title>
   6
   7     <sect2 id="zend.service.akismet.introduction">
   8         <title>導入</title>
   9
  10         <para>
  11             <classname>Zend_Service_Akismet</classname> は、
  12             <ulink url="http://akismet.com/development/api/">Akismet <acronym>API</acronym></ulink>
  13             のクライアント機能を提供します。Akismet サービスは、
  14             入力データがスパムかどうかを判定するために用いられます。
  15             また、あるデータを「スパムである」とか「無実である (ハム)」
  16             などと登録するためのメソッドも公開しています。
  17             もともとは Wordpress 向けのスパムを識別するために作られたものですが、
  18             あらゆる型のデータに対して使用できます。
  19         </para>
  20
  21         <para>
  22             Akismet を使用するには API キーが必要です。
  23             キーを取得するには <ulink url="http://wordpress.com/">WordPress.com</ulink>
  24             でアカウントを作成します。blog を作成する必要はありません。
  25             単にアカウントを作成するだけで API キーが使用できます。
  26         </para>
  27
  28         <para>
  29             さらに、Akismet を使用する場合は、
  30             フィルタリングしたいデータを指す URL を指定してリクエストする必要があります。
  31             Akismet は WordPress 向けに作られたものであることから、
  32             これは blog url と呼ばれます。
  33             これは、コンストラクタの二番目の引数として渡さなければなりません。
  34             ただ、いつでも <methodname>setBlogUrl()</methodname> で変更することができますし、
  35             その他のメソッドコールの際に 'blog' キーを指定して上書きすることもできます。
  36         </para>
  37     </sect2>
  38
  39     <sect2 id="zend.service.akismet.verifykey">
  40         <title>API キーの検証</title>
  41
  42         <para>
  43             <methodname>Zend_Service_Akismet::verifyKey($key)</methodname>
  44             を使用して、Akismet API キーが有効かどうかを検証します。
  45             たいていの場合は特に検証する必要もないでしょうが、
  46             改ざんされていないかどうか調べたり、
  47             新しく取得したキーが実際に使用可能かどうかを調べたり
  48             といった場合にこのメソッドを使用します。
  49         </para>
  50
  51         <programlisting language="php"><![CDATA[
  52 // API キー、そしてアプリケーションやリソースへの URL
  53 // を指定してインスタンスを作成します
  54 $akismet = new Zend_Service_Akismet($apiKey,
  55                                     'http://framework.zend.com/wiki/');
  56 if ($akismet->verifyKey($apiKey) {
  57     echo "このキーは有効です。\n";
  58 } else {
  59     echo "このキーは無効です。\n";
  60 }
  61 ]]></programlisting>
  62
  63         <para>
  64             引数を指定せずにコールすると、<methodname>verifyKey()</methodname>
  65             はコンストラクタで指定した API キーを使用します。
  66         </para>
  67
  68         <para>
  69             <methodname>verifyKey()</methodname> は、Akismet の
  70             <code>verify-key</code> REST メソッドを実装したものです。
  71         </para>
  72     </sect2>
  73
  74     <sect2 id="zend.service.akismet.isspam">
  75         <title>スパムのチェック</title>
  76
  77         <para>
  78             <methodname>Zend_Service_Akismet::isSpam($data)</methodname>
  79             を使用して、Akismet がそのデータをスパムとみなすかどうかを調べます。
  80             引数はひとつで、ここに連想配列を指定することができます。
  81             この配列には、次のキーを設定しなければなりません。
  82         </para>
  83
  84         <itemizedlist>
  85             <listitem>
  86                 <para>
  87                     <code>user_ip</code> は、データを送信したユーザの
  88                     IP アドレスです (あなたの IP アドレスではなく、
  89                     あなたのサイトを使用しているユーザの IP アドレスです)。
  90                 </para>
  91             </listitem>
  92
  93             <listitem>
  94                 <para>
  95                     <code>user_agent</code> は、データを送信したユーザの
  96                     UserAgent 文字列 (ブラウザおよびバージョン) です。
  97                 </para>
  98             </listitem>
  99         </itemizedlist>
 100
 101         <para>
 102             以下のキーも、API 側で認識されます。
 103         </para>
 104
 105         <itemizedlist>
 106             <listitem>
 107                 <para>
 108                     <code>blog</code> は、リソースやアプリケーションを指す
 109                     完全な URL です。指定しなかった場合は、
 110                     コンストラクタに渡した URL を使用します。
 111                 </para>
 112             </listitem>
 113
 114             <listitem>
 115                 <para>
 116                     <code>referrer</code> は、送信時の
 117                     HTTP_REFERER ヘッダの内容です
 118                     (スペルに注意しましょう。ヘッダの名前とは異なります)。
 119                 </para>
 120             </listitem>
 121
 122             <listitem>
 123                 <para>
 124                     <code>permalink</code> は、送信するデータの永続的な場所
 125                     (もしあれば) です。
 126                 </para>
 127             </listitem>
 128
 129             <listitem>
 130                 <para>
 131                     <code>comment_type</code> は、データの形式です。
 132                     ここで指定する値は API で定義されており、
 133                     'comment'、'trackback'、'pingback' および
 134                     空の文字列 ('') などがあります。しかし、
 135                     任意の値を指定することができます。
 136                 </para>
 137             </listitem>
 138
 139             <listitem>
 140                 <para>
 141                     <code>comment_author</code> は、データの送信者の名前です。
 142                 </para>
 143             </listitem>
 144
 145             <listitem>
 146                 <para>
 147                     <code>comment_author_email</code> は、
 148                     データの送信者のメールアドレスです。
 149                 </para>
 150             </listitem>
 151
 152             <listitem>
 153                 <para>
 154                     <code>comment_author_url</code> は、
 155                     データの送信者の URL あるいはホームページです。
 156                 </para>
 157             </listitem>
 158
 159             <listitem>
 160                 <para>
 161                     <code>comment_content</code> は、
 162                     実際に送信されたデータの内容です。
 163                 </para>
 164             </listitem>
 165         </itemizedlist>
 166
 167         <para>
 168             その他の環境変数の内容を送信し、
 169             そのデータがスパムであるかどうかの判断材料とさせることもできます。
 170             Akismet は、$_SERVER 配列の中身をすべて送信することを推奨しています。
 171         </para>
 172
 173         <para>
 174             <methodname>isSpam()</methodname> メソッドは true あるいは false を返します。
 175             API キーが無効な場合は例外をスローします。
 176         </para>
 177
 178         <example id="zend.service.akismet.isspam.example-1">
 179             <title>isSpam() の使用法</title>
 180
 181             <programlisting language="php"><![CDATA[
 182 $data = array(
 183     'user_ip'              => '111.222.111.222',
 184     'user_agent'           => 'Mozilla/5.0 ' . (Windows; U; Windows NT ' .
 185                               '5.2; en-GB; rv:1.8.1) Gecko/20061010 ' .
 186                               'Firefox/2.0',
 187     'comment_type'         => 'contact',
 188     'comment_author'       => '誰かさん',
 189     'comment_author_email' => 'nospam@myhaus.net',
 190     'comment_content'      => "スパマーじゃないもん。信じて!"
 191 );
 192 if ($akismet->isSpam($data)) {
 193     echo "悪いけど、たぶんあなたはスパマーでしょう。";
 194 } else {
 195     echo "私たちのサイトへようこそ!";
 196 }
 197 ]]></programlisting>
 198         </example>
 199
 200         <para>
 201             <methodname>isSpam()</methodname> は、Akismet API のメソッド
 202             <code>comment-check</code> を実装したものです。
 203         </para>
 204     </sect2>
 205
 206     <sect2 id="zend.service.akismet.submitspam">
 207         <title>既知のスパムの送信</title>
 208
 209         <para>
 210             時には、スパムがフィルタを通過してしまうこともあります。
 211             フィルタを通過したデータの中に、もし「これはスパムだろう」
 212             というものが見つかったら、それを Akismet
 213             に送信しましょう。それにより、フィルタの性能が向上します。
 214         </para>
 215
 216         <para>
 217             <methodname>Zend_Service_Akismet::submitSpam()</methodname> に指定する配列は、
 218             <methodname>isSpam()</methodname> に渡すものと同じ形式です。
 219             しかし、このメソッドは値を返しません。
 220             API キーが無効な場合は例外が発生します。
 221         </para>
 222
 223         <example id="zend.service.akismet.submitspam.example-1">
 224             <title>submitSpam() の使用法</title>
 225
 226             <programlisting language="php"><![CDATA[
 227 $data = array(
 228     'user_ip'              => '111.222.111.222',
 229     'user_agent'           => 'Mozilla/5.0 (Windows; U; Windows NT 5.2;' .
 230                               'en-GB; rv:1.8.1) Gecko/20061010 Firefox/2.0',
 231     'comment_type'         => 'contact',
 232     'comment_author'       => '誰かさん',
 233     'comment_author_email' => 'nospam@myhaus.net',
 234     'comment_content'      => "スパマーじゃないもん。信じて!"
 235 );
 236 $akismet->submitSpam($data));
 237 ]]></programlisting>
 238         </example>
 239
 240         <para>
 241             <methodname>submitSpam()</methodname> は、Akismet API のメソッド
 242             <code>submit-spam</code> を実装したものです。
 243         </para>
 244     </sect2>
 245
 246     <sect2 id="zend.service.akismet.submitham">
 247         <title>無実のデータ (ハム) の送信</title>
 248
 249         <para>
 250             時には、Akismet が間違ってスパムと判定してしまうこともあります。
 251             そのため、Akismet がスパムと判断したデータのログを定期的にチェックする必要があります。
 252             このような現象を発見したら、そのデータを Akismet に「ハム」
 253             あるいは無実のデータとして送信しましょう
 254             (ハムは善玉、スパムは悪玉です)。
 255         </para>
 256
 257         <para>
 258             <methodname>Zend_Service_Akismet::submitHam()</methodname> に指定する配列は、
 259             <methodname>isSpam()</methodname> や <methodname>submitSpam()</methodname>
 260             に渡すものと同じ形式です。また、
 261             <methodname>submitSpam()</methodname> と同様、値を返しません。
 262             API キーが無効な場合は例外が発生します。
 263         </para>
 264
 265         <example id="zend.service.akismet.submitham.example-1">
 266             <title>submitHam() の使用法</title>
 267
 268             <programlisting language="php"><![CDATA[
 269 $data = array(
 270     'user_ip'              => '111.222.111.222',
 271     'user_agent'           => 'Mozilla/5.0 (Windows; U; Windows NT 5.2;' .
 272                               'en-GB; rv:1.8.1) Gecko/20061010 Firefox/2.0',
 273     'comment_type'         => 'contact',
 274     'comment_author'       => '誰かさん',
 275     'comment_author_email' => 'nospam@myhaus.net',
 276     'comment_content'      => "スパマーじゃないもん。信じて!"
 277 );
 278 $akismet->submitHam($data));
 279 ]]></programlisting>
 280         </example>
 281
 282         <para>
 283             <methodname>submitHam()</methodname> は、Akismet API のメソッド
 284             <code>submit-ham</code> を実装したものです。
 285         </para>
 286     </sect2>
 287
 288     <sect2 id="zend.service.akismet.accessors">
 289         <title>Zend 固有のアクセス用メソッド</title>
 290
 291         <para>
 292             Akismet API では四つのメソッドしか定義されていませんが、
 293             <classname>Zend_Service_Akismet</classname> では
 294             それ以外のアクセス用メソッドも用意しています。
 295             これらを使用して、内部のプロパティを変更します。
 296         </para>
 297
 298         <itemizedlist>
 299             <listitem>
 300                 <para>
 301                     <methodname>getBlogUrl()</methodname> および <methodname>setBlogUrl()</methodname>
 302                     は、リクエストで使用する blog URL を取得したり変更したりします。
 303                 </para>
 304             </listitem>
 305
 306             <listitem>
 307                 <para>
 308                     <methodname>getApiKey()</methodname> および <methodname>setApiKey()</methodname>
 309                     は、リクエストで使用する API キーを取得したり変更したりします。
 310                 </para>
 311             </listitem>
 312
 313             <listitem>
 314                 <para>
 315                     <methodname>getCharset()</methodname> および <methodname>setCharset()</methodname>
 316                     は、リクエストで使用する文字セットを取得したり変更したりします。
 317                 </para>
 318             </listitem>
 319
 320             <listitem>
 321                 <para>
 322                     <methodname>getPort()</methodname> および <methodname>setPort()</methodname>
 323                     は、リクエストで使用する <acronym>TCP</acronym> ポートを取得したり変更したりします。
 324                 </para>
 325             </listitem>
 326
 327             <listitem>
 328                 <para>
 329                     <methodname>getUserAgent()</methodname> および <methodname>setUserAgent()</methodname>
 330                     は、リクエストで使用する HTTP ユーザエージェントを
 331                     取得したり変更したりします。
 332                     注意: これは、サービスに送信するデータの user_agent
 333                     ではありません。サービスへのリクエストを作成する際に
 334                     HTTP User-Agent ヘッダで指定する内容となります。
 335                 </para>
 336
 337                 <para>
 338                     ユーザエージェントに設定する値は
 339                     <code>some user agent/version | Akismet/version</code>
 340                     形式でなければなりません。デフォルトは
 341                     <code>Zend Framework/ZF-VERSION | Akismet/1.11</code>
 342                     です。<code>ZF-VERSION</code> の部分には現在の
 343                     Zend Framework のバージョン、つまり定数
 344                     <constant>Zend_Framework::VERSION</constant>
 345                     の値があてはまります。
 346                 </para>
 347             </listitem>
 348         </itemizedlist>
 349     </sect2>
 350 </sect1>
 351
 352 <!--
 353 vim:se ts=4 sw=4 et:
 354 -->