カケラの樹 Logo reCAPTCHA API Documentation日本語訳

by yune_kotomi (www.hatena.ne.jp)

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

  • 1. reCAPTCHAとは

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

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

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

    • 3.1. キーの適応範囲

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

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

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

  • 4. reCAPTHAのプロトコル: サーバ群について

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

    • 4.1. APIサーバ

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

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

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

      /verify
      reCAPTCHAリクエストの内容を確認します
  • 5. チャレンジデータの取得

    ユーザは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コードも指定してください。これは二つのフィールドを手動で埋め込む必要があります。

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

    • 5.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>
  • 6. 回答を確認する

    ■ 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に含めることにより、ユーザはこのエラーコードを得ることが出来ます。

    • 6.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

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

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

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

  • 8. その他のリソース

コメント・トラックバック

はてなブックマーク ブックマーク数 livedoor Clip クリップ数

お知らせ

Sponsored link

トラックバック: http://kakera.yumenosora.net/document/show/137
「カケラの樹」は、ブラウザだけで使えるアウトラインエディタです。
ご利用はOpenIDがあればすぐに始められます。
カケラの樹について エディタの試用 新規ユーザー登録・ログイン
presented by 雨上がりの青空を探して。
Valid XHTML 1.1 Ruby on Rails Get Firefox