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( { time : Real } ) : HTTPRequestClass サーバーのレスポンスを待ちます |
4D.HTTPRequest.new()
履歴
| リリース | 内容 |
|---|---|
| 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 | 使用するクライアント証明書フォルダーを指定します。 | 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 |
| serverAuthentication | authentication オブジェクト | サーバー認証のためのオブジェクト | undefined |
| returnResponseBody | Boolean | false の場合、レスポンス本文は response オブジェクト に返されません。 false かつ onData が未定義の場合にエラーを返します。 | true |
| timeout | Real | タイムアウト (秒単位) 未定義 = タイムアウトなし | 未定義 |
| 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" |
HTTP Parse message
履歴
| リリース | 内容 |
|---|---|
| 20 R4 | 追加 |
HTTP Parse message( data : Text ) : Object
HTTP Parse message( data : Blob ) : Object
| 引数 | 型 | 説明 | |
|---|---|---|---|
| data | Text, Blob | -> | 解析するデータ |
| 戻り値 | Object | <- | オブジェクト (各プロパティは、マルチパートの各データです) |
説明
HTTP Parse message コマンドは、multipart/form-data のテキストまたは Blob (HTTP "response" メッセージ) をパースし、コンテンツをオブジェクトに抽出します。 戻り値のオブジェクトの各プロパティは、マルチパートの各データに対応します。
HTTP 自体はステートレスな通信プロトコルです。 このフレームワークの中で、クライアントは、メソッド・ターゲット・ヘッダー・コンテンツなどの詳細を指定した "request" メッセージをサーバーに送ることによって通信を開始します。 サーバーは、同じ詳細を含む "response" メッセージで応答します。 HTTP Parse message コマンドは、"request" または "response" メッセージを解析し、オブジェクトの形式に整えます。
例題
次の例では、HTTPリクエストを格納するテキストファイルのデータを解析します。
ファイルの中身は次のとおりです:
POST /batch/gmail/v1/ HTTP/1.1
Accept-Encoding: gzip, deflate
Authorization: Bearer xxxxxx
Connection: Close
Content-Length: 442
Content-Type: multipart/mixed; boundary=batch_19438756D576A14ABA87C112F56B9396; charset=UTF-8
Date: Wed, 29 Nov 2023 13:51:35 GMT
Host: gmail.googleapis.com
User-Agent: 4D/20.4.0
--batch_19438756D576A14ABA87C112F56B9396
Content-Type: application/http
Content-ID: <item1>
GET https://gmail.googleapis.com/gmail/v1/users/me/messages/18c1b58689824c92?format=raw HTTP/1.1
--batch_19438756D576A14ABA87C112F56B9396
Content-Type: application/http
Content-ID: <item2>
GET https://gmail.googleapis.com/gmail/v1/users/me/messages/18c1b58642b28e2b?format=raw HTTP/1.1
--batch_19438756D576A14ABA87C112F56B9396--
ファイルを解析します:
var $message : Text:=File("/RESOURCES/HTTPrequest.txt").getText()
var $parsedMessage : Object:=HTTP Parse message($message)
//$parsedMessage= {
//headers:{"User-Agent":"4D/20.4.0",...},
//parts:[{"contentType":"application/http","contentID":"item1",...}],
//requestLine:"POST /batch/gmail/v1/ HTTP/1.1"
//}
.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( { time : Real } ) : HTTPRequestClass
| 引数 | 型 | 説明 | |
|---|---|---|---|
| time | Real | -> | レスポンスを待機する最長時間 (秒) |
| 戻り値 | 4D.HTTPRequest | <- | HTTPRequest オブジェクト |
説明
この関数はスレッドセーフです。
wait() 関数は、サーバーのレスポンスを待ちます。
time 引数が渡されると、関数は最長で、定義された秒数だけ待機します。
サーバーのレスポンスがすでに到着している場合、関数は即座に返されます。
During a .wait() execution, callback functions are executed, whether from other HTTPRequest or SystemWorker instances, or other CALL WORKER calls. コールバックから terminate() を呼び出すことで、.wait() を終了することができます。