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.HTTPAgentoptions で渡された 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 | Support of storeCertificateName property |
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 | Sets the active client certificates folder. Can be overriden by "storeCertificateName" (see below). | 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 the OS certificate store (e.g. "LocalMachine") from where to use certificates instead of those in the certificates folder. If the certificate store is not found, an error is returned. For more information, see this blog post. | 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回実行されます。
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()
を終了することができます。