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

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

「HTTP API」の版間の差分

提供: WordPress Codex 日本語版
移動先: 案内検索
(英語版をコピペ。)
 
(和訳完了。)
1行目: 1行目:
 +
<div id="HTTP API">
 
== HTTP API ==
 
== HTTP API ==
 +
</div>
 +
PHP では HTTP リクエストを送る方法は数あります。わかりやすくするために、本文ではこれらの手法をまとめて ''''transports'''' と書きます。HTTP API の目的は、それぞれの transports にシンプルでスタンダードな API を用いることで、出来る限り多くをサポートすることにあります。
  
Within PHP, there are many possible ways to send an HTTP request. For simplicity, these methods will be referred to collectively as ''''transports'''' for this article. The purpose for the HTTP API is to support as many of them as possible with an API that is simple and standard for each of the transports.
+
問題であるのは、ウェブホスティングサーバーは異なった transport をサポートしていたり、そもそもサポートしていないということもあることです。そこでその問題を出来る限り多く解決する策として、transport が1つ2つ無効化されているサーバーであっても、恐らくサポートされているであろうウェブを通しての transports を提供することにあります。
  
The problem is that web hosting servers support different transports and some might support none. The solution then is to support as many as possible to allow for those who have hosts that disable one or two to still access the web through one of the other transports that might still be enabled or supported.
 
  
The other problem was that there wasn't any API for plugins and WordPress core to standardize on. Therefore, there used to be several different implementations in WordPress and many still in Plugins. The problem is even worse for plugins, because the author had to write the implementation themselves and support it afterwards. Given how many workarounds were required for the HTTP API in WordPress, that would be extremely difficult to support. It would also have to be reimplemented in each plugin that wanted to support as many as possible, which many just choose to support one or two if the plugin author was feeling generous.
+
他の問題として、プラグイン向け API がなかったこと、そして WordPress コアとスタンダード化されたものもなかったことです。そのため、 WordPress には色々な異なった実装がなされ、多くはプラグインとして提供されていました。プラグインの場合はもっとひどい状況で、作者が自ら実装を作りこみ、その後のサポートまで全て行う必要がありました。HTTP API を用いるための回避策が数多く必要とされていたため、サポートをすることが非常に難しい状況でした。プラグインについては多くの作者が1つか2つの transports しかサポートしていないものが数多くあり、少しでも多くの transports をサポートするためには再実装する必要がありました。
  
The HTTP API was also an attempt to standardize on a single API that handled everything as simply as possible. The actual implementation is object-oriented, but there are utility functions, which can be used to abstract the API usage.
+
HTTP API は全てを極力シンプルに処理する事が出来る1つの API を標準化させる目的がありました。実際のオブジェクト指向で実装されていますが、API の使用法をまとめるユーティリティ機能があります。
  
The HTTP API was added in [[Version_2.7|WordPress 2.7]] and extend further in [[Version_2.8|WordPress 2.8]]. You may want to maintain backwards compatibility with previous versions, so you should wrap the function calls in function_exists() and provide an alternative, if possible.
+
HTTP API [[Version_2.7|WordPress 2.7]] で導入され、[[Version_2.8|WordPress 2.8]] で拡張されました。後方互換性が必要となる場面があるため、可能であれば <tt>function_exists()</tt> の関数コールをラップし、代替手段を用意する必要があります。
  
In [[Version 2.7|WordPress 2.7]], the basics of header, body and response support was started. In the next version, [[Version 2.8|WordPress 2.8]], compression, cookie support and proxy support were added. Some of the features are passive, meaning that you don't have to set any option or do anything in order to use the feature. If you use an option that is in a later version, it won't give you an error, but may not work correctly.
+
[[Version_2.7|WordPress 2.7]] ではヘッダー、body、レスポンスの基本部分がサポート開始されました。続く [[Version 2.8|WordPress 2.8]] では、圧縮、クッキー、プロキシのサポートが追加されました。これら機能のいくつかはパッシブな、つまり機能を使うためにオプションを設定するなどといった必要がないものです。新しいバージョンでオプション使う場合、エラーを吐くことはありませんが、正しく動作しない可能性があります。
  
While most of the features can be set using the options or using filters, the proxy implementation relies on constants and thus will need to be set manually in the wp-config.php. Of course, there could be and might already be a plugin that will allow you to configure it in the WordPress administration panels.
+
ほとんどの機能はオプションまたはフィルターを使うことでセットできる一方、プロキシの実装は定数に依存します。そのため、手動で <tt>wp-config.php</tt> に設定する必要があります。もちろん、WordPress の管理画面から設定するためのプラグインがあるかもしれません。
  
== Helper Functions ==
+
<div id="Helper Functions">
 +
== ヘルパー関数 ==
 +
</div>
 +
ヘルパー関数は HTTP API クラスを活用してプロセスを可能な限りシンプルにします。クラスやメソッドがコード処理の手助けになります。クラスを用いるためには、それで何をすべきか、それが何ができるかがわかっているという必要があります。
  
The helper functions utilize the HTTP API classes to simplify the process as much as possible. You could use the classes and could use some of the methods to help process the code. The classes assume that you know what you are doing and can use the classes.
+
'''WordPress のコアなコードを修正するときには。ヘルパー関数を使う必要があります。'''API を用いる理由の1つとして、エラー確認の量を減らすとともに、バグが見つかった際に複数箇所を編集する必要がなくなるという効果があります。
  
'''You must use the helper functions if you are modifying the core code of WordPress.''' It is one of the reasons for the helper API, to reduce the amount of error checking and prevent having to edit multiple places when bugs are found.
+
以下の関数が URL を読み出すために用いるものです。これらの関数が失敗した場合、WP_Error クラスを返すことがあります。そのため関数を使用後にチェックする必要があります。
  
The functions below are the ones you will use to retrieve an URL. Please be aware that these functions will return a WordPress WP_Error class on failure. You will have to check for that after using these functions.
+
* [[Function_Reference/wp_remote_get|wp_remote_get()]] - GET HTTP メソッドを用いて URL を取得する関数。
 +
* [[Function_Reference/wp_remote_post|wp_remote_post()]] - POST HTTP メソッドを用いて URL を取得する関数。
 +
* [[Function_Reference/wp_remote_head|wp_remote_head()]] - HEAD HTTP メソッドを用いて URL を取得する関数。
 +
* [[Function_Reference/wp_remote_request|wp_remote_request()]] - デフォルトの GET または指定した特定のカスタム HTTP メソッド (capsであるべき) を用いて URL を取得する関数。
  
* [[Function_Reference/wp_remote_get|wp_remote_get()]] - Retrieves a URL using the GET HTTP method.
+
以下のヘルパー関数はレスポンスの他の部分を読み出し、WP_Error を検証してくれるもので、API の使用法を非常にシンプルにするとともに、レスポンスオブジェクトを処理するためにより好まれるメソッドです。
* [[Function_Reference/wp_remote_post|wp_remote_post()]] - Retrieves a URL using the POST HTTP method.
+
* [[Function_Reference/wp_remote_head|wp_remote_head()]] - Retrieves a URL using the HEAD HTTP method.
+
* [[Function_Reference/wp_remote_request|wp_remote_request()]] - Retrieves a URL using either the default GET or a custom HTTP method (should be caps) that you specify.
+
  
The other helper functions deal with retrieving different parts of the response and do the testing for WP_Error for you, these make usage of the API very simple and are the preferred method for processing response objects.
+
* [[Function_Reference/wp_remote_retrieve_body|wp_remote_retrieve_body()]] - レスポンスから body のみを読み出す関数。
 +
* [[Function_Reference/wp_remote_retrieve_header|wp_remote_retrieve_header()]] - レスポンスから読みだした HTTP ヘッダーの名前を返す関数。
 +
* [[Function_Reference/wp_remote_retrieve_headers|wp_remote_retrieve_headers()]] - すべての HTTP ヘッダーを配列の形で返す関数。
 +
* [[Function_Reference/wp_remote_retrieve_response_code|wp_remote_retrieve_response_code()]] - HTTP レスポンスの数字を返す関数。通常200であるが、エラー時には4xx や 3xx の場合もある。
 +
* [[Function_Reference/wp_remote_retrieve_response_message|wp_remote_retrieve_response_message()]] - HTTP レスポンスコードを元にした、レスポンスメッセージを返す関数。
  
* [[Function_Reference/wp_remote_retrieve_body|wp_remote_retrieve_body()]] - Retrieves just the body from the response.
+
以下に例示するように、API はリダイレクションも処理します。
* [[Function_Reference/wp_remote_retrieve_header|wp_remote_retrieve_header()]] - Gives you a single HTTP header based on name from the response.
+
* [[Function_Reference/wp_remote_retrieve_headers|wp_remote_retrieve_headers()]] - Returns all of the HTTP headers in an array for processing.
+
* [[Function_Reference/wp_remote_retrieve_response_code|wp_remote_retrieve_response_code()]] - Gives you the number for the HTTP response. This should be 200, but could be 4xx or even 3xx on failure.
+
* [[Function_Reference/wp_remote_retrieve_response_message|wp_remote_retrieve_response_message()]] - Returns the response message based on the response code.
+
 
+
As you can see in the example below, the API also handles redirection.
+
  
 
<pre language="php">
 
<pre language="php">
42行目: 45行目:
 
</pre>
 
</pre>
  
== Other Arguments ==
+
<div id="Other Arguments">
 +
== その他の引数 ==
 +
</div>
 +
引数 ''''method'''' は HTTP メソッド、例えば POST, GET, HEAD, PUT 等、必要とする物を表します。サーバーがサポートしているメソッドで最も安全なものは、POST, GET, HEAD です。その他すべてのメソッドは使えない可能性があります。デフォルトの値は 'GET' です。
  
The argument ''''method'''' is the HTTP method, such as POST, GET, HEAD, PUT, etc that you want to use. The safest methods to use for server support are POST, GET, and HEAD, all others, you may meet with various degrees of success. The default for this value is 'GET'.
+
引数 ''''timeout'''' は接続が切れてエラーが返される前にタイムアウトとするための時間を秒単位で指定するものです。デフォルト値は 5 秒ですが、リクエストごとにタイムアウト値を設定するプラグインなどのために、<tt>'http_request_timeout'</tt> という名のフィルターがあります。
  
The argument ''''timeout'''' allows for setting the time in seconds, before the connection is dropped and an error is returned. The default for this value is 5 seconds and it also has a filter named, 'http_request_timeout', in case you want to write a plugin that sets it for every request.
+
引数 ''''redirection'''' はリダイレクトに従う回数を定めたものです。デフォルト値は 5 ですが、フィルターがあります。フィルター名は <tt>'http_request_redirection_count'</tt> で、リダイレクションのデフォルト値だけを渡します。
  
The ''''redirection'''' argument is the amount of times to follow a redirect before giving up. The default is 5 and there is a filter for the value. The filter name is 'http_request_redirection_count' and only passes the redirection default value.
+
引数 ''''user-agent'''' は user-agent をセットするものです。デフォルト値は <tt>"WordPress/2.7; http://www.example.com"</tt> で、<tt>"2.7"</tt> の部分はバージョン番号が、<tt>www.example.com</tt> 部分はブログのURLが入ります。この値を変更するために <tt>'http_headers_useragent'</tt> というフィルターがあります。
  
The ''''user-agent'''' argument allows you to set the user-agent. The default of which is, "WordPress/2.7; http://www.example.com" where 2.7 is the WordPress version number and www.example.com is the blog URL. There is a filter for changing this value as well, which is 'http_headers_useragent'.
+
引数 ''''blocking'''' は non-blocking なリクエストをトリガーとすることを可能にします。デフォルト値は <tt>true</tt> です。<tt>false</tt> に設定すると、一般的には transport が行われている間に PHP が処理を続けることを可能とします。ここでのポイントは blocking を false とすると、リクエストを送るだけで細かいことは気にしなくて済むということです。これは POST リクエストを送るときに使えるもので、その結果が成功したか否かを気にせずに済み、ページの処理時間が遅くなることもありません。(全ての transports が non-blocking リクエストをサポートしているわけではありません。そのため、ブロックされることもあります。その場合にタイムアウトの時間を非常に短くして代替とすることはおすすめしません。これは短いタイムアウト設定の結果、 transports にリクエストが全く送られないことがありうるためです。)
  
The ''''blocking'''' argument allows you to trigger a non-blocking request. The default is true; setting it to false will generally allow PHP to continue execution while the transport is working. The key is that when you set blocking to false, then it will just send the request and won't bother you with the details. This is useful for sending a POST request, where you aren't concerned with whether it succeeded or not, or if you don't want to slow down the processing time of the page. (Note that not all the transports support non-blocking requests, and so you may still be blocked anyway. The alternative of setting an ultra-low timeout is not recommended, since low timeouts may cause the request to not be sent at all with some transports.)
+
引数  ''''compress'''' は [[Version 2.8|WordPress 2.8]] から導入され、リクエストの body を圧縮して送るものです。
  
The argument ''''compress'''', available with [[Version 2.8]], allows you to send the request body as compressed.
+
引数  ''''decompress'''' はデフォルトでは、入ってくる圧縮されたコンテンツを解凍するものです。これを <tt>true</tt> にしておくと、ヘッダーが圧縮されたデータを受け入れられるとサーバーに伝え、レスポンスの中で解凍されます。これを <tt>false</tt> にすると、ヘッダーが圧縮されたデータは受け入れられないとサーバーに対して伝えます。そこでコンテンツが圧縮されている場合、実装が誤っているかヘッダーにそのように書かれているため、コンテンツを解凍しなければなりません。これも [[Version 2.8|WordPress 2.8]] の引数です。
  
The ''''decompress'''' argument by default will decompress any compressed content that comes in. If you do leave this as true, then the headers will be set to tell the server that compressed data is accepted and it will be decompressed in the response. If you sent it to false, then the header will be sent that tells servers that compressed content is not accepted. If the content is still compressed, because of incorrect implementation or you sent the headers for it, then you will need to decompress the content. This is also a 2.8 argument.
+
引数  ''''sslverify'''' は [[Version 2.8|WordPress 2.8]] から導入され、SSL 証明が有効か否か (自己署名されたものではなく、リクエストされたサイトに対するもの) をチェックし、無効であった場合はリクエストを拒否します。HTTPS をリクエストするときに、そのサイトが自己署名されたものか、充分に信頼出来るサイトである場合は、<tt>false</tt> にセットします。
  
The ''''sslverify'''' argument was added in [[Version 2.8]] and will check to see if the SSL certificate is valid (not self-signed, actually for the site in the request) and will deny the response if it isn't. If you are requesting HTTPS and and know that the site is self-signed or is invalided and are reasonably sure that it can be trusted, then set to false.
+
<div id="External References">
 
+
== 外部リファレンス ==
== External References ==
+
</div>
 
* [http://planetozh.com/blog/2009/08/how-to-make-http-requests-with-wordpress/ How to make HTTP requests with WordPress] by Ozh
 
* [http://planetozh.com/blog/2009/08/how-to-make-http-requests-with-wordpress/ How to make HTTP requests with WordPress] by Ozh
 
* [http://lud.icro.us/wordpress-http-api-basicauth/ Basic Authentication with the WordPress HTTP API] by johnbillion
 
* [http://lud.icro.us/wordpress-http-api-basicauth/ Basic Authentication with the WordPress HTTP API] by johnbillion
 +
 +
{{原文|HTTP API|133313}}<!-- 00:50, 20 July 2013 Jdgrimes 版 -->
  
 
[[Category:Advanced Topics]]
 
[[Category:Advanced Topics]]

2013年8月18日 (日) 21:55時点における版

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

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

* wp_remote_retrieve_body() - レスポンスから body のみを読み出す関数。
* wp_remote_retrieve_header() - レスポンスから読みだした HTTP ヘッダーの名前を返す関数。
* wp_remote_retrieve_headers() - すべての HTTP ヘッダーを配列の形で返す関数。
* wp_remote_retrieve_response_code() - HTTP レスポンスの数字を返す関数。通常200であるが、エラー時には4xx や 3xx の場合もある。
* wp_remote_retrieve_response_message() - 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最新版との差分