• 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。(詳細

このWikiはいつでも誰でも編集できます

HTTP API

提供: WordPress Codex 日本語版
移動先: 案内検索

PHP では HTTP リクエストを送る方法は数あります。わかりやすくするために、本文ではこれらの手法をまとめて 'transports' と書きます。HTTP API の目的は、それぞれの transports にシンプルでスタンダードな API を用いることで、出来る限り多くをサポートすることにあります。

問題であるのは、ウェブホスティングサーバーは異なった transport をサポートしていたり、そもそもサポートしていないということもあることです。そこでその問題を出来る限り多く解決する策として、transport が1つ2つ無効化されているサーバーであっても、恐らくサポートされているであろうウェブを通しての transports を提供することにあります。


他の問題として、プラグイン向け API がなかったこと、そして WordPress コアとスタンダード化されたものもなかったことです。そのため、 WordPress には色々な異なった実装がなされ、多くはプラグインとして提供されていました。プラグインの場合はもっとひどい状況で、作者が自ら実装を作りこみ、その後のサポートまで全て行う必要がありました。HTTP API を用いるための回避策が数多く必要とされていたため、サポートをすることが非常に難しい状況でした。プラグインについては多くの作者が1つか2つの transports しかサポートしていないものが数多くあり、少しでも多くの transports をサポートするためには再実装する必要がありました。

HTTP API は全てを極力シンプルに処理する事が出来る1つの API を標準化させる目的がありました。実際のオブジェクト指向で実装されていますが、API の使用法をまとめるユーティリティ機能があります。

HTTP API は WordPress 2.7 で導入され、WordPress 2.8 で拡張されました。後方互換性が必要となる場面があるため、可能であれば function_exists() の関数コールをラップし、代替手段を用意する必要があります。

WordPress 2.7 ではヘッダー、body、レスポンスの基本部分がサポート開始されました。続く WordPress 2.8 では、圧縮、クッキー、プロキシのサポートが追加されました。これら機能のいくつかはパッシブな、つまり機能を使うためにオプションを設定するなどといった必要がないものです。新しいバージョンでオプション使う場合、エラーを吐くことはありませんが、正しく動作しない可能性があります。

ほとんどの機能はオプションまたはフィルターを使うことでセットできる一方、プロキシの実装は定数に依存します。そのため、手動で wp-config.php に設定する必要があります。もちろん、WordPress の管理画面から設定するためのプラグインがあるかもしれません。

ヘルパー関数

ヘルパー関数は HTTP API クラスを活用してプロセスを可能な限りシンプルにします。クラスやメソッドがコード処理の手助けになります。クラスを用いるためには、それで何をすべきか、それが何ができるかがわかっているという必要があります。

WordPress のコアなコードを修正するときには。ヘルパー関数を使う必要があります。API を用いる理由の1つとして、エラー確認の量を減らすとともに、バグが見つかった際に複数箇所を編集する必要がなくなるという効果があります。

以下の関数が URL を読み出すために用いるものです。これらの関数が失敗した場合、WP_Error クラスを返すことがあります。そのため関数を使用後にチェックする必要があります。

* wp_remote_get() /en - GET HTTP メソッドを用いて URL を取得する関数。
* wp_remote_post() /en  - POST HTTP メソッドを用いて URL を取得する関数。
* wp_remote_head() /en  - HEAD HTTP メソッドを用いて URL を取得する関数。
* wp_remote_request() /en  - デフォルトの GET または指定した特定のカスタム HTTP メソッド (capsであるべき) を用いて URL を取得する関数。

以下のヘルパー関数はレスポンスの他の部分を読み出し、WP_Error を検証してくれるもので、API の使用法を非常にシンプルにするとともに、レスポンスオブジェクトを処理するためにより好まれるメソッドです。

* wp_remote_retrieve_body() /en - レスポンスから body のみを読み出す関数。
* wp_remote_retrieve_header() /en  - レスポンスから読みだした HTTP ヘッダーの名前を返す関数。
* wp_remote_retrieve_headers() /en  - すべての HTTP ヘッダーを配列の形で返す関数。
* wp_remote_retrieve_response_code() /en  - HTTP レスポンスの数字を返す関数。通常200であるが、エラー時には4xx や 3xx の場合もある。
* wp_remote_retrieve_response_message() /en  - HTTP レスポンスコードを元にした、レスポンスメッセージを返す関数。

以下に例示するように、API はリダイレクションも処理します。

$theBody = wp_remote_retrieve_body( wp_remote_get('http://www.wordpress.org') );

その他の引数

引数 'method' は HTTP メソッド、例えば POST, GET, HEAD, PUT 等、必要とする物を表します。サーバーがサポートしているメソッドで最も安全なものは、POST, GET, HEAD です。その他すべてのメソッドは使えない可能性があります。デフォルトの値は 'GET' です。

引数 'timeout' は接続が切れてエラーが返される前にタイムアウトとするための時間を秒単位で指定するものです。デフォルト値は 5 秒ですが、リクエストごとにタイムアウト値を設定するプラグインなどのために、'http_request_timeout' という名のフィルターがあります。

引数 'redirection' はリダイレクトに従う回数を定めたものです。デフォルト値は 5 ですが、フィルターがあります。フィルター名は 'http_request_redirection_count' で、リダイレクションのデフォルト値だけを渡します。

引数 'user-agent' は user-agent をセットするものです。デフォルト値は "WordPress/2.7; http://www.example.com" で、"2.7" の部分はバージョン番号が、www.example.com 部分はブログのURLが入ります。この値を変更するために 'http_headers_useragent' というフィルターがあります。

引数 'blocking' は non-blocking なリクエストをトリガーとすることを可能にします。デフォルト値は true です。false に設定すると、一般的には transport が行われている間に PHP が処理を続けることを可能とします。ここでのポイントは blocking を false とすると、リクエストを送るだけで細かいことは気にしなくて済むということです。これは POST リクエストを送るときに使えるもので、その結果が成功したか否かを気にせずに済み、ページの処理時間が遅くなることもありません。(全ての transports が non-blocking リクエストをサポートしているわけではありません。そのため、ブロックされることもあります。その場合にタイムアウトの時間を非常に短くして代替とすることはおすすめしません。これは短いタイムアウト設定の結果、 transports にリクエストが全く送られないことがありうるためです。)

引数 'compress'WordPress 2.8 から導入され、リクエストの body を圧縮して送るものです。

引数 'decompress' はデフォルトでは、入ってくる圧縮されたコンテンツを解凍するものです。これを true にしておくと、ヘッダーが圧縮されたデータを受け入れられるとサーバーに伝え、レスポンスの中で解凍されます。これを false にすると、ヘッダーが圧縮されたデータは受け入れられないとサーバーに対して伝えます。そこでコンテンツが圧縮されている場合、実装が誤っているかヘッダーにそのように書かれているため、コンテンツを解凍しなければなりません。これも WordPress 2.8 の引数です。

引数 'sslverify'WordPress 2.8 から導入され、SSL 証明が有効か否か (自己署名されたものではなく、リクエストされたサイトに対するもの) をチェックし、無効であった場合はリクエストを拒否します。HTTPS をリクエストするときに、そのサイトが自己署名されたものか、充分に信頼出来るサイトである場合は、false にセットします。

外部リファレンス

最新英語版: WordPress Codex » HTTP API最新版との差分