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!!!');
});

---

Updated: 2022-01-17