reCAPTCHA API Documentation日本語訳
  1. 1. 新ドキュメント(翻訳中)
    1. 1.1. reCAPTCHA
    2. 1.2. 開発者向けガイド
  2. 2. reCAPTCHAとは
  3. 3. reCAPTCHA APIの仕組み
  4. 4. reCAPTCHAキーを取得する
    1. 4.1. キーの適応範囲
  5. 5. reCAPTHAのプロトコル: サーバ群について
    1. 5.1. APIサーバ
    2. 5.2. 確認サーバ
  6. 6. チャレンジデータの取得
    1. 6.1. 見かけのカスタマイズ
  7. 7. 回答を確認する
    1. 7.1. エラーコード一覧
  8. 8. ヒントとガイドライン
  9. 9. その他のリソース

翻訳元ドキュメントが改訂されているので、再翻訳中です。

しばらくお待ちください。

原文: http://recaptcha.net/apidocs/captcha/

    1. http://code.google.com/intl/ja/apis/recaptcha/


      ■ 入門

      • reCAPTCHAのAPIキーをサインアップ
      • reCAPTCHAの開発者ガイドを読む
      • reCAPTCHAのユーザーグループに参加する

      ■ 書籍デジタル化を手助けする、無償bot対策サービス

      簡単に追加できる強力なセキュリティ。視覚障害者への配慮も。


      ■ reCAPTCHAとは何ですか？

      reCAPTCHAは無償のCAPTCHAサービスです。スパムや悪意のあるユーザ登録、コンピュータが人間を騙って行われる攻撃などからあなたのサイトを保護します。 CAPTCHAはコンピュータと人間を判別する、自動化されたチューリングテストです。reCAPTCHAはウィジェットとして提供され、あなたのブログ、フォーラム、登録フォームなどに簡単に追加できます。

      更に、reCAPTCHAは同時に古い本や新聞をデジタル化する活動の手助けにもなります。reCAPTCHAがどのように動作するかを知り、私たちのフォーラムに参加してください 。

    2. http://code.google.com/intl/ja/apis/recaptcha/intro.html


      reCAPTCHAの開発者向けドキュメントにようこそ！reCAPTCHAはあなたのウェブページをスパムやその他の自動化された攻撃から守るために埋め込めるCAPTCHAです。この文書では、あなたのページにreCAPTCHAを追加する方法を説明します。


      ■ 対象読者

      このドキュメントは、HTMLフォームやサーバー側での処理に精通した人々を対象に書かれています。reCAPTCHAを組み込むには、いくつかのコードを編集する必要があります。

      私たちは、このドキュメントが分かりやすいものであろうと期待しています。この API に関するご意見を提供くださる方や、情報交換を行いたい方は、reCAPTCHA開発者グループに参加してください。


      ■ 概要

      APIキー

      reCAPTCHAを使用するには、APIキーを取得する必要があります。あなたが"グローバルキー"オプションを選択しない限り、キーは、ドメインとサブドメインに固有のものです。（デフォルトでは、すべてのキーは"localhost"（"127.0.0.1"）で動作するので、ローカルマシン上で開発、テストすることができます。）


      組み込み

      一度APIキーを取得すれば、以下の2ステップ(とオプションの3番目のステップ)であなたのサイトにreCAPTCHAを追加できます。

      1. クライアント側： reCAPTCHAのウィジェットを表示する （必須）
      2. サーバ側： ユーザの回答の確認 （必須）
      3. カスタマイズ （オプション）

      ほとんどのWebフォームは、フォーム自体と、そこに入力された内容を処理するスクリプトといった2種類のファイルで構成されています。これら2つのファイルは、それぞれ上記の手順1と2に対応します。したがって、ほとんどのケースでは、2つの異なるファイルを変更する必要があります。

      あなたのサイトにreCAPTCHAを追加するには、（a）"プラグイン"を使用するか、（b）reCAPTCHAのサーバと通信するコードを記述する、という二つの方法があります。

      我々は、一般的なアプリケーションやプログラミング環境用のプラグインを持っていますので、あなたの使い方にあったものがあればそれを使用することをおすすめします。あなたが以下の開発環境またはアプリケーションのいずれかを使用している場合、リンクをクリックしてプラグイン情報や手順を見てください。

      そうでなければ、プラグインなしでreCAPTCHAを表示する方法や プラグインなしで、ユーザの回答を確認する方法を確認してください 。


      ■ プログラミング環境：

      • PHP
      • ASP.NET
      • 古いASP （Mark Shortによる寄稿）
      • Java / JSP
      • Perl
      • Python
      • Ruby （McClain Looneyによる寄稿）
      • Jason L PerryによるRuby用ライブラリ
      • Ruby/Rack （Arthur Chiuによる寄稿）
      • JSP Mailhideタグ （Tamas Magyarによる寄稿）
      • ColdFusion （Robin Hilliardによる寄稿）
      • WebDNA （Dan Strongによる寄稿）

      ■ アプリケーション：

      • WordPress
      • MediaWiki
      • phpBB
      • FormMail
      • Movable Type ( Josh Carterによる寄稿)
      • Drupal （Rob Loachによる寄稿）
      • Symfony (contributed by Arthur Koziel)
      • TYPO3 (Markus Blaschkeによるメンテナンス, Jens Mittagによる寄稿。 プラグインの使用例も参照してください)
      • NucleusCMS (contributed by Matt)
      • vBulletin (contributed by Magnus)
      • Joomla (contributed by Mark Fabrizio)
      • Joomla Community Builder (contributed by Ayan Debnath)
      • JSP Mailhide (contributed by Tamas Magyar)
      • bbPress (contributed by Rhys Wynne)
      • ExpressionEngine (contributed by Jaspaul Aggarwal)
      • FlatPress (contributed by Ross Fruen)
      • PHPKIT (contributed by Norman Huth)

  2. reCAPTCHAは無償で利用可能なCAPTCHA実装です。これは人間とコンピュータを判別し、次のような用途が考えられます。

    1. ユーザがreCAPTCHAのJavaScriptが組み込まれたWebページをロードします。
    2. ユーザのブラウザがreCAPTCHAのチャレンジデータを要求し、reCAPTCHAはチャレンジデータとトークンを送り返します。
    3. ユーザがWebページのフォームを埋め、答えをトークンと共にアプリケーションサーバに送信します。
    4. reCAPTCHAがユーザの回答をチェックし、応答をあなた(のアプリケーションサーバ)に送り返します。
    5. 結果がtrueなら通常はユーザにサービスを提供するか、情報を提示します。(例)フォーラムへのコメント許可、Wikiへの登録許可、Eメールアドレスの提示など　結果がfalseならばユーザにもう一度試行させると良いでしょう。

  4. reCAPTCHAを使うには公開/非公開APIキーペアが必要です。これらのキーペアはreCAPTCHAへのアタックを防ぎ、あなたのサイトからの回答を集めるために使われます。キー取得はreCAPTCHA管理ポータルから行えます。

    1. あなたのreCAPTCHAトークンは登録されたドメインとそのサブドメインでのみ有効です。複数のサイトでキーが必要な場合*1、次の三つのテクニックが使えます。

      • 片方のサーバが"localhost"か"127.0.0.1"の場合、reCAPTCHAは同一ドメインルールを適用しません。本番環境で同じキーを使って構いません。
      • 広い適応範囲でキーを生成します。たとえば、あなたのアプリケーションがa.example.comでテストサーバがtest.corp.example.comだったとすれば、example.comを指定してキーを生成してください。
      • それぞれのドメインに対してキーを生成します。

      *1: 開発サーバと本番環境サーバの二通りを持っているとか、単純に複数のサイトをホスティングしている場合など

  5. reCAPTCHAのリクエストが行われる間、"api"と"verify"の二つのサーバが関わることになります。これらのサーバについては次の通りです。

    1. クライアントサイドAPIを提供します。ユーザはどちらかのサーバとやりとりを行うことになります。あなたのサイトがSSLを使っているならば、api-secureの方を使ってください。そうでないならば、api.recaptcha.netを使ってください。(SSLではないサーバの方がパフォーマンスはよい)

      /challenge
      JavaScriptのreCAPTCHAチャレンジデータが得られます
      /noscript
      JavaScriptをサポートしないブラウザのためのHTML形式チャレンジデータが得られます

    2. アプリケーションサーバはこのサーバとやりとりを行います。

      /verify
      reCAPTCHAリクエストの内容を確認します

  6. ユーザはAPIサーバにリクエストを行い、チャレンジデータを取得します。

    ■ URL

    ■ パラメータ

    k(必須)
    Your public API key, from the reCAPTCHA sign-up page
    error(オプション)
    以前のreCAPTHAコールにおけるエラーコード

    ■ 応答

    'recaptcha_challenge_field' と 'recaptcha_response_field' の二つのフィールドを持つreCAPTCHAウィジェットを挿入するJavaScriptが返されます。


    このHTMLはreCAPTCHAウィジェットを表示する例です。

    <script type="text/javascript" src="http://api.recaptcha.net/challenge?k=<your_public_key>">
</script>

<noscript>
   <iframe src="http://api.recaptcha.net/noscript?k=<your_public_key>" height="300" width="500" frameborder="0"></iframe>
    
   
   
</noscript>

    このコードはformタグの間に挿入される必要があります。ユーザのブラウザがJavaScriptをサポートしないときのために、noscriptコードも指定してください。これは二つのフィールドを手動で埋め込む必要があります。

    注: この例のように公開/非公開キーペアをハードコードするのではなく、もっと安全な、隠れた場所に保存しておく方がよいでしょう

    1. JavaScriptでreCAPTCHAウィジェットの見かけをカスタマイズできます。これらの設定をする場合、RecaptchaOptionsオブジェクトを宣言するscriptタグを挿入してください。フィールドは次のように指定できます。

      キー 設定できる値 デフォルト値 意味
      theme red/white/blackglass red テーマを指定します
      tabindex 整数値 0 reCAPTCHAのテキストボックスにtabindexを指定します。フォーム中の他の要素がtabindexを使用している場合、この値を設定してユーザが使いやすくすべきです。

      例: このscriptタグは白のテーマを適用し、tabindexに2を指定します。

      <script>
var RecaptchaOptions = {
   theme : 'white',
   tabindex : 2
};
</script>

  7. ■ URL

    ■ パラメータ(POSTで送信)

    privatekey (必須)
    あなたのプライベートキー
    remoteip (必須)
    CAPTCHAを解いたユーザのIPアドレス
    challenge (必須)
    フォーム中の"recaptcha_challenge_field"に記入された内容
    response (必須)
    フォーム中の"recaptcha_response_field"に記入された内容

    ■ 応答

    確認サーバからの応答はLF区切りの文字列で返ります。将来的に行が追加される可能性がありますので、現状では追加行を無視する実装にすべきです。

    1行目
    "true"か"false"。trueならばCAPTCHAの認証は成功です。
    2行目
    もし1行目がfalseならば、この文字列はエラーコードです。reCAPTCHAはこのエラーをユーザに示すことが出来ます(api.recaptcha.net/challengeへの"error"パラメータとして指定してください)。このコード名は将来的に変更される可能性がありますので、依存しないように実装してください。

    応答例

    false
incorrect-captcha-sol

    '&error=incorrect-captcha-sol'とチャレンジデータを要求するURLに含めることにより、ユーザはこのエラーコードを得ることが出来ます。

    1. ■ unknown

      不明なエラー

      ■ invalid-site-public-key

      公開キーが不正です

      解決方法

      • 公開キーと非公開キーを取り違えていませんか？
      • キーを正しくコピーしていますか？キーにはハイフンやアンダースコアが含まれますが、スペースは含まれません。また、キーはきっかり40文字です。

      ■ invalid-site-private-key

      非公開キーが不正です

      解決方法

      • 公開キーと非公開キーを取り違えていませんか？
      • キーを正しくコピーしていますか？キーにはハイフンやアンダースコアが含まれますが、スペースは含まれません。また、キーはきっかり40文字です。

      ■ invalid-request-cookie

      確認サーバへのリクエストの中で、challengeパラメータが不正です

      ■ incorrect-captcha-sol

      CAPTCHAの答えが間違っています

      ■ verify-params-incorrect

      /verifyに与えるパラメータが間違っています。必須パラメータを全て与えているか確認してください。

      ■ verify-params-incorrect

      同一ドメインルールに違反しています。「キーの適応範囲」の項を参照してください。

    • ユーザがCAPTCHAを解くのに失敗した場合、間違いを出来るだけ直しやすくしましょう
      • 入力された内容は再表示しましょう
      • チャレンジデータ取得の際にerrorパラメータを指定し、ユーザがエラーを確認できるようにしましょう
    • フォーム中の"recaptcha_challenge_field"か"recaptcha_response_field"が指定されていない場合、api-verify.recaptcha.netへのリクエストはしないようにしてください。これはspam行為を防ぐ簡単な手段です。
    • あなたが何らかのアプリケーションへのプラグインを書いているなら、http://recaptcha.net/api/getkeyへリンクしてユーザがキーを生成できるようにしてください。このURLは"domain"と"app"と言う二つのパラメータを持っており、ドメイン欄とアプリケーション名の欄をあらかじめ埋めた上で表示することが出来ます。(これにより我々はそのプラグインの人気を確認することが出来ます)

    お疲れ様でした！reCAPTCHAをアプリケーション中で使う例を見るなら、リソースのページをご覧下さい。