04. HTTP
httpオブジェクトは、HTTPクライアント機能を提供する組み込みオブジェクトです。
機能概要:
- HTTPクライアント機能を提供します。
- HTTP v1.1をサポートします。
制限事項:
- 同時に使用可能なHTTPセッションリソースは2本です。
尚、このリソースはhttpオブジェクトとhttpsオブジェクトで共用となります。 - リソースエラーは例外発生要因となります。
http Global Object
| Methods()/Properties | Summary | Version | Note |
|---|---|---|---|
| http.request() | HTTP通信を開始します。 | 01.01.00+ | {ClientRequest}、および{IncomingMessage}のインスタンスが生成されます。 |
Details
http.request(options[,callback][,sockTo])
HTTP通信を開始します。
| Name | Type | M/O | Summary | Note |
|---|---|---|---|---|
| options | Object | mandatory | 通信パラメータの設定用プロパティ host : {string} HTTPサーバのドメイン名またはIPアドレス(※1) デフォルト値は'127.0.0.1'となります。 port : {number} HTTPサーバのポート番号 デフォルト値は80となります。 method : {string} メソッド名 'GET', 'POST', 'PUT', 'HEAD'のいずれかが入ります。 デフォルト値は'GET'となります。 path : {string} リクエストのパス デフォルト値は'/'となります。 headers : {Object} リクエストヘッダ 任意のリクエストヘッダを含むオブジェクトを指定します。尚、このパラメータはオプションです。 | 未設定の要素はデフォルト値で動作しますが、本引数自身は必須であることに注意してください。 ※1: 文字数が64バイトを超えた場合は例外が発生します。 |
| callback(res) | function | optional | レスポンスヘッダの受信完了時にコールバック処理を実行します。以下の引数が付属します。 res : {IncomingMessage} {IncomingMessage}のインスタンス | データを受信する場合は必要となります。 |
| sockTo | number | optional | セッションのタイムアウト値[ms] (最大で 4,294,967,295msまで指定可能です。超過値は最大値となります) デフォルト値は90000となります。 | 指定があった場合、セッションはタイムアウトで破棄され、errorイベントにて通知されます。 |
| return | {ClientRequest} | - | {ClientRequest} : 生成された{ClientRequest} | リソース不足やパラメータ異常の場合は例外となります。 |
{ClientRequest}
本オブジェクトは、http.request()により内部で生成され返却されます。
| Methods()/Properties | Summary | Version | Note |
|---|---|---|---|
| .on() | イベントハンドラを登録します。 | 01.01.00+ | |
| .write() | データの送信を行います。 | 01.01.00+ | |
| .end() | HTTP-Requestを完了します。 | 01.01.00+ | |
| .abort() | HTTP-Request送信/HTTP-Response受信を強制的に中止します。 | 01.01.00+ | |
| .errCode | エラーコード | 01.01.00+ |
Details
.on(event,callback)
イベントハンドラを登録します。
| Name | Type | M/O | Summary | Note |
|---|---|---|---|---|
| event | string | mandatory | イベント名 使用できるイベント名はerrorとなります。 | |
| callback() | function | mandatory | イベント発生時にコールバック処理を実行します。 | |
| return | undefined | - | - |
event : ’error’
HTTP-Requestで、エラーが発生した場合にコールバック処理を実行します。
エラーは、コールバック処理の中またはそれ以降で、エラーコード(.errCode)を参照できます。
.write(data[,callback])
データの送信を行います。
dataはRequest-Bodyとして送信されます。送信完了時にコールバック処理を実行します。
| Name | Type | M/O | Summary | Note |
|---|---|---|---|---|
| data | string, ArrayBuffer | mandatory | 送信データ | コールバック処理と連携することにより分割書き込みが可能です。一度に書き込むデータサイズは4KB以下にしてください。エラーが発生した場合は一度に書き込むデータサイズを減らしてください。 |
| callback() | function | optional | 書き込みデータの送信完了時にコールバック処理を実行します。 | |
| return | undefined | - | - |
.end([data][,callback])
dataが存在する場合はRequest-Bodyとして送信され、HTTP-Requestを完了します。
Requestデータの送信完了時にコールバック処理を実行します。
本メソッドは、HTTP-Requestを完了する時に必須です。
| Name | Type | M/O | Summary | Note |
|---|---|---|---|---|
| data | string, ArrayBuffer | optional | 送信データ | 書き込むデータサイズは4KB以下にしてください。エラーが発生した場合は書き込むデータサイズを減らし、.write()を使用した分割書き込みを実行してください。 |
| callback() | function | optional | 書き込みデータが送信完了時にコールバック処理を実行します。 | |
| return | undefined | - | - |
通常、下記のように使用します。
request.write('Hello World');
request.end();
以下は、分割書き込みのサンプルです。
var WRITE_CHUNK = 1024;
var getBodyStream = function(){
var buff;
//...
//WRITE_CHUNKまでのデータを用意する。
//データがなくなったらば、nullを返却する。
//...
return buff; //{string}/{arrayBuffer}/null
};
var writeBodyStream = function(){
var buff = getBodyStream();
if (buff != null){
print('request stream write!!!');
request.write(buff ,writeBodyStream);
}else{
request.end(function() {
print('request stream end!!!');
});
}
}
writeBodyStream();
.abort()
HTTP-Request送信/HTTP-Response受信を強制的に中止します。
本関数はerrorイベントをコールする契機となります。
| Name | Type | M/O | Summary | Note |
|---|---|---|---|---|
| return | undefined | - | - |
.errCode
エラーコードです。本プロパティは、number型の値を持ちます。
以下が値毎の意味となります。errorイベントのコールバック処理の中またはそれ以降で参照可能です。
| Error code | Summary |
|---|---|
| 0 | エラーなし |
| 1 | .abort()による中止 |
| 2 | パラメータエラー |
| 3 | リソースエラー |
| 4 | コールバック処理エラー |
| 5 | ソケットタイムアウト |
| 6 | スリープ移行に伴う中止 |
| 103 | Request-Body不足によるエラー |
| 104 | Request-Body不正によるエラー |
| 115 | ソケットエラー |
{IncomingMessage}
本オブジェクトは、http.request()により内部で生成され、コールバック処理の引数として返却されます。
本オブジェクトが返却されたタイミングから、受信したレスポンスヘッダは参照可能です。
| Methods()/Properties | Summary | Version | Note |
|---|---|---|---|
| .on() | イベントハンドラを登録します。 | 01.01.00+ | |
| .read() | Response-Bodyを読み出します。 | 01.01.00+ | |
| .readBin() | Response-Bodyをバイナリ形式で読み出します。 | 01.01.00+ | |
| .statusCode | HTTPレスポンスフレームのステータスライン上のステータスコード | 01.01.00+ | |
| .statusMessage | HTTPレスポンスフレームのステータスライン上のステータスメッセージ | 01.01.00+ | |
| .headers | HTTPレスポンスフレームのヘッダ | 01.01.00+ |
Details
.on(event,callback)
イベントハンドラを登録します。
| Name | Type | M/O | Summary | Note |
|---|---|---|---|---|
| event | string | mandatory | イベント名 使用できるイベント名はerror, readable, endとなります。 | |
| callback() | function | mandatory | イベント発生時にコールバック処理を実行します。 | |
| return | undefined | - | - |
event : ’error’
HTTP-Responseの受信が完了しなかった場合にコールバック処理を実行します。
同時に、{ClientRequest}のerrorイベントにも反映します。
event : ’readable’
HTTP-Responseの受信バッファにデータが存在する場合にコールバック処理を実行します。
データ受信を行う場合は本イベントを必ずハンドルする必要があります。
尚、readableイベントが発生せず、endイベントが直接発生する場合があります。
event : ’end’
HTTP-Responseの受信が完了した場合にコールバック処理を実行します。
データ受信を行う場合は本イベントを必ずハンドルする必要があります。
.read()
Response-Bodyを読み出します。
| Name | Type | M/O | Summary | Note |
|---|---|---|---|---|
| return | string, null | - | 読み出したResponse-Bodyデータ | 存在しない場合はnullを返却します。 |
.readBin()
Response-Bodyをバイナリ形式で読み出します。
| Name | Type | M/O | Summary | Note |
|---|---|---|---|---|
| return | ArrayBuffer, null | - | 読み出したResponse-Bodyデータ | 存在しない場合はnullを返却します。 |
文字列をバイナリで読み出すサンプルです。
res.on('end' ,function() {
r_data = res.readBin();
r_data_u8 = new Uint8Array(r_data);
var s = '';
for( n = 0 ; n < r_data_u8.length ; n++){
s += r_data_u8[n].toString();
}
print('body:' + s);
});
.statusCode
本プロパティは、number型の値を持ちます。
HTTPレスポンスフレームのステータスライン上のステータスコードを参照可能です。
.statusMessage
本プロパティは、string型の値を持ちます。
HTTPレスポンスフレームのステータスライン上のステータスメッセージを参照可能です。
.headers
本プロパティは、Object型の値を持ちます。
HTTPレスポンスフレームのヘッダを参照可能です。ヘッダ名がプロパティ名称となります。
例えば、レスポンスヘッダから'Date'ヘッダの値を参照する場合は以下のようにします。
http.request(options, function(res) {
print(res.headers['Date']);
});
オブジェクトの使用例
Sample 1
GETメソッドのサンプルです。分割受信を行っています。
var HEADERS = {};
var options = {method: 'GET', host: '192.168.1.1', port: 80, path: '/test.txt', headers: HEADERS};
var request = http.request(options, function(res) {
print(res.statusCode);
print(this.statusMessage);
res.on('error', function() {
print('response error!');
});
res.on('readable', function() {
print(res.read());
});
res.on('end', function() {
print(res.read());
print('response complete!');
});
});
request.on('error', function() {
print('errCode=' + request.errCode);
});
request.end(function() {
print('request done!!!');
});
Sample 2
POSTメソッドのサンプルです。'Hello World'を送信します。
var BODY = 'Hello World';
var HEADERS = {'Content-Type': 'text/plain', 'Content-Length': BODY.length.toString()};
var options = {method: 'POST', host: '192.168.1.1', port: 80, path: '/post', headers: HEADERS};
var request = http.request(options, function(res) {
print(res.statusCode);
print(this.statusMessage);
res.on('error', function() {
print('response error!');
});
res.on('end', function() {
print('response complete!');
});
});
request.on('error', function() {
print('errCode=' + request.errCode);
});
request.end(BODY, function() {
print('request done!!!');
});