[ZF-10089] Zend_Log
[zend.git] / documentation / manual / ja / module_specs / Zend_Service_Akismet.xml
blob23ab4b17294e7d86c647af99a0f8abd40960b1de
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>
7     <sect2 id="zend.service.akismet.introduction">
8         <title>導入</title>
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>
21         <para>
22             Akismet を使用するには API キーが必要です。
23             キーを取得するには <ulink url="http://wordpress.com/">WordPress.com</ulink>
24             でアカウントを作成します。blog を作成する必要はありません。
25             単にアカウントを作成するだけで API キーが使用できます。
26         </para>
28         <para>
29             さらに、Akismet を使用する場合は、
30             フィルタリングしたいデータを指す URL を指定してリクエストする必要があります。
31             Akismet は WordPress 向けに作られたものであることから、
32             これは blog url と呼ばれます。
33             これは、コンストラクタの二番目の引数として渡さなければなりません。
34             ただ、いつでも <methodname>setBlogUrl()</methodname> で変更することができますし、
35             その他のメソッドコールの際に 'blog' キーを指定して上書きすることもできます。
36         </para>
37     </sect2>
39     <sect2 id="zend.service.akismet.verifykey">
40         <title>API キーの検証</title>
42         <para>
43             <methodname>Zend_Service_Akismet::verifyKey($key)</methodname>
44             を使用して、Akismet API キーが有効かどうかを検証します。
45             たいていの場合は特に検証する必要もないでしょうが、
46             改ざんされていないかどうか調べたり、
47             新しく取得したキーが実際に使用可能かどうかを調べたり
48             といった場合にこのメソッドを使用します。
49         </para>
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";
61 ]]></programlisting>
63         <para>
64             引数を指定せずにコールすると、<methodname>verifyKey()</methodname>
65             はコンストラクタで指定した API キーを使用します。
66         </para>
68         <para>
69             <methodname>verifyKey()</methodname> は、Akismet の
70             <code>verify-key</code> REST メソッドを実装したものです。
71         </para>
72     </sect2>
74     <sect2 id="zend.service.akismet.isspam">
75         <title>スパムのチェック</title>
77         <para>
78             <methodname>Zend_Service_Akismet::isSpam($data)</methodname>
79             を使用して、Akismet がそのデータをスパムとみなすかどうかを調べます。
80             引数はひとつで、ここに連想配列を指定することができます。
81             この配列には、次のキーを設定しなければなりません。
82         </para>
84         <itemizedlist>
85             <listitem>
86                 <para>
87                     <code>user_ip</code> は、データを送信したユーザの
88                     IP アドレスです (あなたの IP アドレスではなく、
89                     あなたのサイトを使用しているユーザの IP アドレスです)。
90                 </para>
91             </listitem>
93             <listitem>
94                 <para>
95                     <code>user_agent</code> は、データを送信したユーザの
96                     UserAgent 文字列 (ブラウザおよびバージョン) です。
97                 </para>
98             </listitem>
99         </itemizedlist>
101         <para>
102             以下のキーも、API 側で認識されます。
103         </para>
105         <itemizedlist>
106             <listitem>
107                 <para>
108                     <code>blog</code> は、リソースやアプリケーションを指す
109                     完全な URL です。指定しなかった場合は、
110                     コンストラクタに渡した URL を使用します。
111                 </para>
112             </listitem>
114             <listitem>
115                 <para>
116                     <code>referrer</code> は、送信時の
117                     HTTP_REFERER ヘッダの内容です
118                     (スペルに注意しましょう。ヘッダの名前とは異なります)。
119                 </para>
120             </listitem>
122             <listitem>
123                 <para>
124                     <code>permalink</code> は、送信するデータの永続的な場所
125                     (もしあれば) です。
126                 </para>
127             </listitem>
129             <listitem>
130                 <para>
131                     <code>comment_type</code> は、データの形式です。
132                     ここで指定する値は API で定義されており、
133                     'comment'、'trackback'、'pingback' および
134                     空の文字列 ('') などがあります。しかし、
135                     任意の値を指定することができます。
136                 </para>
137             </listitem>
139             <listitem>
140                 <para>
141                     <code>comment_author</code> は、データの送信者の名前です。
142                 </para>
143             </listitem>
145             <listitem>
146                 <para>
147                     <code>comment_author_email</code> は、
148                     データの送信者のメールアドレスです。
149                 </para>
150             </listitem>
152             <listitem>
153                 <para>
154                     <code>comment_author_url</code> は、
155                     データの送信者の URL あるいはホームページです。
156                 </para>
157             </listitem>
159             <listitem>
160                 <para>
161                     <code>comment_content</code> は、
162                     実際に送信されたデータの内容です。
163                 </para>
164             </listitem>
165         </itemizedlist>
167         <para>
168             その他の環境変数の内容を送信し、
169             そのデータがスパムであるかどうかの判断材料とさせることもできます。
170             Akismet は、$_SERVER 配列の中身をすべて送信することを推奨しています。
171         </para>
173         <para>
174             <methodname>isSpam()</methodname> メソッドは true あるいは false を返します。
175             API キーが無効な場合は例外をスローします。
176         </para>
178         <example id="zend.service.akismet.isspam.example-1">
179             <title>isSpam() の使用法</title>
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'      => "スパマーじゃないもん。信じて!"
192 if ($akismet->isSpam($data)) {
193     echo "悪いけど、たぶんあなたはスパマーでしょう。";
194 } else {
195     echo "私たちのサイトへようこそ!";
197 ]]></programlisting>
198         </example>
200         <para>
201             <methodname>isSpam()</methodname> は、Akismet API のメソッド
202             <code>comment-check</code> を実装したものです。
203         </para>
204     </sect2>
206     <sect2 id="zend.service.akismet.submitspam">
207         <title>既知のスパムの送信</title>
209         <para>
210             時には、スパムがフィルタを通過してしまうこともあります。
211             フィルタを通過したデータの中に、もし「これはスパムだろう」
212             というものが見つかったら、それを Akismet
213             に送信しましょう。それにより、フィルタの性能が向上します。
214         </para>
216         <para>
217             <methodname>Zend_Service_Akismet::submitSpam()</methodname> に指定する配列は、
218             <methodname>isSpam()</methodname> に渡すものと同じ形式です。
219             しかし、このメソッドは値を返しません。
220             API キーが無効な場合は例外が発生します。
221         </para>
223         <example id="zend.service.akismet.submitspam.example-1">
224             <title>submitSpam() の使用法</title>
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'      => "スパマーじゃないもん。信じて!"
236 $akismet->submitSpam($data));
237 ]]></programlisting>
238         </example>
240         <para>
241             <methodname>submitSpam()</methodname> は、Akismet API のメソッド
242             <code>submit-spam</code> を実装したものです。
243         </para>
244     </sect2>
246     <sect2 id="zend.service.akismet.submitham">
247         <title>無実のデータ (ハム) の送信</title>
249         <para>
250             時には、Akismet が間違ってスパムと判定してしまうこともあります。
251             そのため、Akismet がスパムと判断したデータのログを定期的にチェックする必要があります。
252             このような現象を発見したら、そのデータを Akismet に「ハム」
253             あるいは無実のデータとして送信しましょう
254             (ハムは善玉、スパムは悪玉です)。
255         </para>
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>
265         <example id="zend.service.akismet.submitham.example-1">
266             <title>submitHam() の使用法</title>
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'      => "スパマーじゃないもん。信じて!"
278 $akismet->submitHam($data));
279 ]]></programlisting>
280         </example>
282         <para>
283             <methodname>submitHam()</methodname> は、Akismet API のメソッド
284             <code>submit-ham</code> を実装したものです。
285         </para>
286     </sect2>
288     <sect2 id="zend.service.akismet.accessors">
289         <title>Zend 固有のアクセス用メソッド</title>
291         <para>
292             Akismet API では四つのメソッドしか定義されていませんが、
293             <classname>Zend_Service_Akismet</classname> では
294             それ以外のアクセス用メソッドも用意しています。
295             これらを使用して、内部のプロパティを変更します。
296         </para>
298         <itemizedlist>
299             <listitem>
300                 <para>
301                     <methodname>getBlogUrl()</methodname> および <methodname>setBlogUrl()</methodname>
302                     は、リクエストで使用する blog URL を取得したり変更したりします。
303                 </para>
304             </listitem>
306             <listitem>
307                 <para>
308                     <methodname>getApiKey()</methodname> および <methodname>setApiKey()</methodname>
309                     は、リクエストで使用する API キーを取得したり変更したりします。
310                 </para>
311             </listitem>
313             <listitem>
314                 <para>
315                     <methodname>getCharset()</methodname> および <methodname>setCharset()</methodname>
316                     は、リクエストで使用する文字セットを取得したり変更したりします。
317                 </para>
318             </listitem>
320             <listitem>
321                 <para>
322                     <methodname>getPort()</methodname> および <methodname>setPort()</methodname>
323                     は、リクエストで使用する <acronym>TCP</acronym> ポートを取得したり変更したりします。
324                 </para>
325             </listitem>
327             <listitem>
328                 <para>
329                     <methodname>getUserAgent()</methodname> および <methodname>setUserAgent()</methodname>
330                     は、リクエストで使用する HTTP ユーザエージェントを
331                     取得したり変更したりします。
332                     注意: これは、サービスに送信するデータの user_agent
333                     ではありません。サービスへのリクエストを作成する際に
334                     HTTP User-Agent ヘッダで指定する内容となります。
335                 </para>
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>
352 <!--
353 vim:se ts=4 sw=4 et: