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 waits waits for a response from the server or until the specified timeout is reached |
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( { timeout : Real } ) : 4D.HTTPRequest
| 引数 | 型 | 説明 | |
|---|---|---|---|
| timeout | Real | -> | Maximum wait time in seconds |
| 戻り値 | 4D.HTTPRequest | <- | HTTPRequest オブジェクト |
説明
この関数はスレッドセーフです。
The wait() function waits waits for a response from the server or until the specified timeout is reached.
If a timeout is provided, the function waits for the specified duration in this parameter. Decimals are accepted.
サーバーのレスポンスがすでに到着している場合、関数は即座に返されます。
During the .wait() execution, callback functions from workers are executed, whether they originate from other HTTPRequest or SystemWorker instances, or other CALL WORKER calls. You can exit from a .wait() by calling terminate() from a callback.