バージョン: 21

HTTPRequest

HTTPRequest クラスを使って、HTTPRequest オブジェクト を扱うことができます。このオブジェクトは、HTTPサーバーへのリクエストの設定と送信、および HTTPサーバーのレスポンスを処理するのに使用します。

HTTPRequest クラスは、4D クラスストアにて提供されています。 HTTPリクエストを作成・送信するには、HTTPRequest オブジェクト を返す 4D.HTTPRequest.new() 関数を使用します。

履歴

リリース	内容
19 R6	クラスを追加

例題

リクエスト設定用の MyHttpRequestOptions クラスを作成します:

Class constructor($method : Text; $headers : Object; $body : Text)
This.method:=$method
This.headers:=$headers
This.body:=$body

Function onResponse($request : 4D.HTTPRequest; $event : Object)
// リクエストを非同期的に処理する場合、onResponse メソッドをここに書きます

Function onError($request : 4D.HTTPRequest; $event : Object)
// リクエストを非同期的に処理する場合、onError メソッドをここに書きます

このクラスを使って、次のようにリクエストを作成できます:

var $headers : Object
$headers:=New object()
$headers["field1"]:="value1"

var myHttpRequestOptions : cs.MyHttpRequestOptions
myHttpRequestOptions := cs.MyHttpRequestOptions.new("GET"; $headers; "")

var $request : 4D.HTTPRequest
$request:=4D.HTTPRequest.new("www.google.com"; myHttpRequestOptions)
$request.wait() // リクエストを同期的に処理する場合
// $request.response からリクエストの結果を取得したり、$request.error からエラーの詳細を確認したりできます

HTTPRequest オブジェクト

HTTPRequest オブジェクトは共有できないオブジェクトです。

HTTPRequest オブジェクトは次のプロパティや関数を提供します:


agent : 4D.HTTPAgent `options` で渡された `agent` オブジェクト、もしくは省略された場合はグローバルなエージェントオブジェクト
dataType : Text new() を呼び出す際に `options` オブジェクトに渡された `dataType` を格納します (省略時は "auto"
encoding : Text new() を呼び出す際に `options` オブジェクトに渡された `encoding` を格納します (省略時は "UTF-8")
errors : Collection 少なくとも 1つのエラーが発生した場合、全エラーのコレクションを格納します
headers : Object new() を呼び出す際に `options` オブジェクトに渡された `headers` を格納します
method : Text new() を呼び出す際に `options` オブジェクトに渡された `method` を格納します
protocol : Text new() を呼び出す際に `options` オブジェクトに渡された `protocol` を格納します
response : Object 少なくともステータスコードを受け取った場合には、リクエストへのレスポンスを格納します (それ以外の場合は未定義)
returnResponseBody : Boolean new() を呼び出す際に `options` オブジェクトに渡された `returnResponseBody` を格納します
.terminate() HTTPリクエストを中止します
terminated : Boolean リクエストが終了された場合 (`onTerminate` への呼び出し後) は true を格納します (それ以外は false)
timeout : Real new() を呼び出す際に `options` オブジェクトに渡された `timeout` を格納します
url : Text HTTPリクエストの URL を格納します
.wait( { timeout : Real } ) : 4D.HTTPRequest サーバーからのレスポンスが来るか、`timeout` 引数で指定した秒数に達するまで待ちます

4D.HTTPRequest.new()

履歴

リリース	内容
21	storeCertificateName プロパティのサポート
20	TLS検証がデフォルトに
19 R7	automaticRedirections および decodeData プロパティをサポート。

4D.HTTPRequest.new( url : Text { ; options : Object } ) : 4D.HTTPRequest

引数	型		説明
url	Text	->	リクエストの送信先URL
options	Object	->	リクエスト設定プロパティ
戻り値	4D.HTTPRequest	<-	新規 HTTPRequest オブジェクト

説明

4D.HTTPRequest.new() 関数は、options 引数で指定した設定に基づいて HTTPリクエストを作成し、url 引数で定義される HTTPサーバーに送信して、4D.HTTPRequest オブジェクトを返します。

返される HTTPRequest オブジェクトは、HTTPサーバーのレスポンスの処理と、メソッドを呼び出すのに使用されます。

url には、リクエスト送信先の URL を渡します。シンタックスは以下の通りです:

{http://}[{user}:[{password}]@]host[:{port}][/{path}][?{queryString}]
{https://}[{user}:[{password}]@]host[:{port}][/{path}][?{queryString}]

スキーム部分 (http:// または https://) を省略した場合には、https リクエストが送信されます。

たとえば、次の文字列を受け渡すことができます:

    http://www.myserver.com
    www.myserver.com/path
    http://www.myserver.com/path?name="jones"
    https://www.myserver.com/login
    http://123.45.67.89:8083
    http://john:smith@123.45.67.89:8083
    http://[2001:0db8:0000:0000:0000:ff00:0042:8329]
    http://[2001:0db8:0000:0000:0000:ff00:0042:8329]:8080/index.html (**)

`options` 引数

options に渡すオブジェクトは、次のプロパティを持つことができます:

プロパティ	型	説明	デフォルト
agent	4D.HTTPAgent	HTTPRequest で使用する HTTPAgent。エージェントオプションはリクエストオプションと統合されます (リクエストオプションが優先されます)。特定のエージェントが定義されていない場合、デフォルト値を持つグローバルエージェントが使用されます。	グローバルエージェントオブジェクト
automaticRedirections	Boolean	true の場合、リダイレクトは自動的に実行されます (最大 5回までのリダイレクトが処理され、もしあれば 6回目のリダイレクトレスポンスが返されます)	true
body	Variant	リクエストの本文 (`post` または `put` リクエストの場合に必須)。テキスト、BLOB、またはオブジェクトを指定できます。ヘッダー内で設定されていない限り、content-type は当プロパティの型によって決定されます。	undefined
certificatesFolder	Folder	アクティブクライアント証明書フォルダを設定します。 "storeCertificateName" によって上書き可能です(下記参照)。	undefined
dataType	Text	レスポンス本文のデータ型。値: "text", "blob", "object", または "auto"。 "auto" の場合、本文の型は MIMEタイプから推定されます (JSON ならオブジェクト、テキスト・javascript・xml・httpメッセージ・URLエンコードされたフォームなどはテキスト、それ以外は BLOB)。	"auto"
decodeData	Boolean	true の場合、`onData` コールバックが受け取るデータは非圧縮です	false
encoding	Text	`body` のあるリクエストの場合にのみ使用 (`post` または `put` メソッド)。本文がテキストの場合のエンコーディング。ヘッダーにて content-type が指定されている場合は無視されます。	"UTF-8"
headers	Object	リクエストのヘッダー。シンタックス: `headers.key=value` (同じ key に対して value を複数指定する場合、value にコレクションを使用できます)	空のオブジェクト
method	Text	"POST"、"GET"、またはその他のメソッド	"GET"
minTLSVersion	Text	TLS の最小バージョンを指定します: "`TLSv1_0`", "`TLSv1_1`", "`TLSv1_2`", "`TLSv1_3`"	"`TLSv1_2`"
onData	Function	本文のデータ受信時のコールバック。コールバックは 2つのオブジェクトを引数として受け取ります (後述参照)	undefined
onError	Function	エラー発生時のコールバック。コールバックは 2つのオブジェクトを引数として受け取ります (後述参照)	undefined
onHeaders	Function	ヘッダー受信時のコールバック。コールバックは 2つのオブジェクトを引数として受け取ります (後述参照)	undefined
onResponse	Function	レスポンス受信時のコールバック。コールバックは 2つのオブジェクトを引数として受け取ります (後述参照)	undefined
onTerminate	Function	リクエスト終了時のコールバック。コールバックは 2つのオブジェクトを引数として受け取ります (後述参照)	undefined
protocol	Text	"auto" または "HTTP1"。 "auto" は現在の実装における HTTP1 を意味します。	"auto"
proxyAuthentication	authentication オブジェクト	プロキシ認証のためのオブジェクト	undefined
returnResponseBody	Boolean	false の場合、レスポンス本文は`response` オブジェクトに返されません。 false かつ `onData` が未定義の場合にエラーを返します。	true
serverAuthentication	authentication オブジェクト	サーバー認証のためのオブジェクト	undefined
storeCertificateName	Text	(Windows only) Name of a certificate stored in the Certificate Store to use instead of one saved in the certificates folder. If the certificate is not found, an error is returned. より詳細な情報に関しては、こちらの blog 記事を参照してください。	undefined
timeout	Real	タイムアウト (秒単位) タイムアウト (秒単位) 未定義 = タイムアウトなし	undefined
validateTLSCertificate	Boolean	false の場合、4D は TLS証明書の検証をおこなわず、無効 (期限切れ、自己署名など) であってもエラーを返しません。重要: 現在の実装では、認証局そのものは検証されません。	true

コールバック関数

すべてのコールバック関数は、2つのオブジェクト引数を受け取ります:

引数	型
$param1	`HTTPRequest` オブジェクト
$param2	`Event` オブジェクト

以下は、コールバック呼び出しの流れです:

onHeaders は常に 1回呼び出されます。
onData は 0回または複数回呼び出されます (リクエストに本文がない場合は呼び出されません)。
エラーが発生しなかった場合、onResponse は常に 1回呼び出されます。
エラーが発生した場合、 onError が 1回実行されます (そしてリクエストを終了します)。
onTerminate は常に 1回実行されます。

info

wait() を使用しない場合 (非同期呼び出し) にコールバック関数が呼び出されるためには、そのプロセスは CALL WORKER で作成されたワーカーである必要があります (New process は使えません)。

event オブジェクト

event オブジェクトは、コールバック関数が呼ばれたときに返されます。このオブジェクトには次のプロパティが含まれます:

プロパティ	型	説明
.data	blob	取得データ。 `onData` コールバック以外の場合は常に undefined です。
.type	text	イベントの種類。取り得る値: "response", "error", "headers", "data", または "terminate

authentication オブジェクト

authentication オブジェクトは options.serverAuthentication または options.proxyAuthentication プロパティに使用します。このオブジェクトには以下のプロパティを含めることができます:

プロパティ	型	説明	デフォルト
name	Text	認証に使用する名前	undefined
password	Text	認証に使用するパスワード	undefined
method	Text	認証方法: "basic", "digest", "auto"	"auto"

.agent

agent : 4D.HTTPAgent

説明

.agent プロパティは、options で渡された agent オブジェクト、もしくは省略された場合はグローバルなエージェントオブジェクトを格納します。

.dataType

dataType : Text

説明

.dataType プロパティは、new() を呼び出す際に options オブジェクトに渡された dataType を格納します (省略時は "auto")。

.encoding

encoding : Text

説明

.encoding プロパティは、new() を呼び出す際に options オブジェクトに渡された encoding を格納します (省略時は "UTF-8")。

.errors

errors : Collection

説明

.errorsプロパティは、少なくとも 1つのエラーが発生した場合、全エラーのコレクションを格納します。

.errors プロパティの内容は次の通りです:

プロパティ		型	説明
errors		Collection	エラー発生時の 4Dエラースタック
	[].errCode	Number	4Dエラーコード
	[].message	Text	4Dエラーの詳細
	[].componentSignature	Text	エラーを返した内部コンポーネントの署名

.headers

headers : Object

説明

.headers プロパティは、 new() を呼び出す際に options オブジェクトに渡された headers を格納します。 (省略された場合は空のオブジェクト)

.method

method : Text

説明

.method プロパティは、new() を呼び出す際に options オブジェクトに渡された method を格納します。 (省略された場合は "GET")

.protocol

protocol : Text

説明

.protocol プロパティは、 new() を呼び出す際に options オブジェクトに渡された protocol を格納します。 (省略時、または "auto" の場合は、使用されたプロトコルのバージョン)

.response

履歴

リリース	内容
19 R8	`.headers` は小文字の名前を返します。 `.rawHeaders` プロパティの追加

response : Object

説明

.response プロパティは、少なくともステータスコードを受け取った場合には、リクエストへのレスポンスを格納します (それ以外の場合は未定義)。

response オブジェクトは共有できないオブジェクトです。このオブジェクトは次のプロパティを提供します: このオブジェクトは次のプロパティを提供します:

プロパティ	型	説明
.body	Variant	レスポンスのボディ。レスポンスのボディ。メッセージのデータ型は `dataType` プロパティによって定義されています。ボディがまだ受信されていない場合は未定義です。ボディがまだ受信されていない場合は未定義です。
.headers	Object	レスポンスのヘッダー。ヘッダー名は小文字で返されます。 `<headername>.key` = value (同じ key が複数指定されている場合、value はコレクションでありえます) ヘッダーがまだ受信されていない場合は未定義です。ヘッダーがまだ受信されていない場合は未定義です。
.status	Number	レスポンスのステータスコード
.statusText	Text	ステータスコードを説明するメッセージ
.rawHeaders	Object	レスポンスのヘッダー。ヘッダー名はそのまま (大文字小文字を変えずに) 返されます。レスポンスのヘッダー。ヘッダー名は小文字で返されます。 `<headername>.key` = value (同じ key が複数指定されている場合、value はコレクションでありえます) ヘッダーがまだ受信されていない場合は未定義です。ヘッダーがまだ受信されていない場合は未定義です。ヘッダーがまだ受信されていない場合は未定義です。

.returnResponseBody

returnResponseBody : Boolean

説明

.returnResponseBody プロパティは、 new() を呼び出す際に options オブジェクトに渡された returnResponseBody を格納します。 (省略された場合は true)。

.terminate()

.terminate()

引数	型		説明
			引数を必要としません

説明

この関数はスレッドセーフです。

.terminate() 関数は、HTTPリクエストを中止します。また、onTerminate イベントをトリガーします。

.terminated

terminated : Boolean

説明

.terminated プロパティは、リクエストが終了された場合 (onTerminate への呼び出し後) は true を格納します (それ以外は false)。

.timeout

timeout : Real

説明

.timeout プロパティは、 new() を呼び出す際に options オブジェクトに渡された timeout を格納します。 (省略された場合は未定義)。

.url

url : Text

説明

.url プロパティは、HTTPリクエストの URL を格納します。

.wait()

.wait( { timeout : Real } ) : 4D.HTTPRequest

引数	型		説明
timeout	Real	->	最大待機時間(秒)
戻り値	4D.HTTPRequest	<-	HTTPRequest オブジェクト

説明

この関数はスレッドセーフです。

wait() 関数はサーバーからのレスポンスが来るか、timeout 引数で指定した秒数に達するまで待ちます。

timeout 引数でタイムアウトまでの時間が指定された場合、関数はこの引数で指定された時間待機します。小数点以下も指定可能です。

サーバーのレスポンスがすでに到着している場合、関数は即座に返されます。

注

.wait() の実行中、それが HTTPRequest あるいは SystemWorker インスタンス、あるいは他の CALL WORKER 呼び出しから発生したかにかかわらず、ワーカーからのコールバックは実行されます。コールバックから terminate() を呼び出すことで、.wait() を終了することができます。

例題​

HTTPRequest オブジェクト​

4D.HTTPRequest.new()​

説明​

options 引数​

コールバック関数​

event オブジェクト​

authentication オブジェクト​

.agent​

説明​

.dataType​

説明​

.encoding​

説明​

.errors​

説明​

.headers​

説明​

.method​

説明​

.protocol​

説明​

.response​

説明​

.returnResponseBody​

説明​

.terminate()​

説明​

.terminated​

説明​

.timeout​

説明​

.url​

説明​

.wait()​

説明​

例題