05. HTTPS

httpsオブジェクトは、セキュアなHTTPクライアント機能を提供する組み込みオブジェクトです。

機能概要:

  • HTTPクライアント機能を提供します。
  • HTTP v1.1をサポートします。
  • TLSをサポートします。
  • サーバー認証とクライアント認証をサポートします。

制限事項:

  • 同時に使用可能なHTTPセッションリソースは2本です。
    尚、このリソースはhttpオブジェクトとhttpsオブジェクトで共用となります。
  • リソースエラーは例外発生要因となります。


https Global Object

Methods()/PropertiesSummaryVersionNote
https.request()HTTPS通信を開始します。01.00.00+{ClientRequest}、および{IncomingMessage}のインスタンスが生成されます。


Details

https.request(options[,callback][,sockTo])

HTTPS通信を開始します。

NameTypeM/OSummary                                            Note
optionsObjectmandatory通信パラメータの設定用プロパティ
host : {string}
HTTPSサーバのドメイン名またはIPアドレス(※1)
デフォルト値は'127.0.0.1'となります。
port : {number}
HTTPSサーバのポート番号
デフォルト値は443となります。
method : {string}
メソッド名
'GET', 'POST', 'PUT', 'HEAD' のいずれかが入ります。
デフォルト値は'GET'となります。
path : {string}
リクエストのパス
デフォルト値は'/'となります。
headers : {Object}
リクエストヘッダ
任意のリクエストヘッダを含むオブジェクトを指定します。尚、このパラメータはオプションです。
ca : {string}
CA証明書(※2)
cert : {string}
クライアント証明書(※3)
デフォルト値はありません。
key : {string}
クライアント秘密鍵(※3)
デフォルト値はありません。		未設定の要素はデフォルト値で動作します。(但し以下※2,3)
また、本引数自身は必須であることに注意してください。

※1: 文字数が127バイトを超えた場合は例外が発生します。
※2: 本パラメータは必須です。
※3: 指定しない場合、クライアント認証は無効となります。
callback(res)functionoptionalレスポンスヘッダの受信完了時にコールバック処理を実行します。以下の引数が付属します。
res : {IncomingMessage}
{IncomingMessage}のインスタンス		データを受信する場合は必要となります。
sockTonumberoptionalセッションのタイムアウト値[ms]
(最大で 4,294,967,295msまで指定可能です。超過値は最大値となります)
デフォルト値は90000となります。		指定があった場合、セッションはタイムアウトで破棄され、errorイベントにて通知されます。
return{ClientRequest}-{ClientRequest} : 生成された{ClientRequest}リソース不足やパラメータ異常の場合は例外となります。


{ClientRequest}

本オブジェクトは、https.request()により内部で生成され返却されます。

Methods()/PropertiesSummaryVersionNote
.on()イベントハンドラを登録します。01.00.00+
.write()データの送信を行います。01.00.00+
.end()HTTP-Requestを完了します。01.00.00+
.abort()HTTP-Request送信/HTTP-Response受信を強制的に中止します。01.00.00+
.errCodeエラーコード01.00.00+


Details

.on(event,callback)

イベントハンドラを登録します。

NameTypeM/OSummaryNote
eventstringmandatoryイベント名
使用できるイベント名はerrorとなります。
callback()functionmandatoryイベント発生時にコールバック処理を実行します。
returnundefined--

event : ’error’

HTTP-Requestで、エラーが発生した場合にコールバック処理を実行します。
エラーは、コールバック処理の中またはそれ以降で、エラーコード(.errCode)を参照できます。

.write(data[,callback])

データの送信を行います。
dataはRequest-Bodyとして送信されます。送信完了時にコールバック処理を実行します。

NameTypeM/OSummary                        Note
datastring, ArrayBuffermandatory送信データコールバック処理と連携することにより分割書き込みが可能です。一度に書き込むデータサイズは4KB以下にしてください。エラーが発生した場合は一度に書き込むデータサイズを減らしてください。
callback()functionoptional書き込みデータの送信完了時にコールバック処理を実行します。
returnundefined--

.end([data][,callback])

dataが存在する場合はRequest-Bodyとして送信され、HTTP-Requestを完了します。
Requestデータの送信完了時にコールバック処理を実行します。
本メソッドは、HTTP-Requestを完了する時に必須です。

NameTypeM/OSummary                        Note
datastring, ArrayBufferoptional送信データ書き込むデータサイズは4KB以下にしてください。エラーが発生した場合は書き込むデータサイズを減らし、.write()を使用した分割書き込みを実行してください。
callback()functionoptional書き込みデータが送信完了時にコールバック処理を実行します。
returnundefined--

通常、下記のように使用します。

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イベントをコールする契機となります。

NameTypeM/OSummaryNote
returnundefined--

.errCode

エラーコードです。本プロパティは、number型の値を持ちます。
以下が値毎の意味となります。errorイベントのコールバック処理の中またはそれ以降で参照可能です。

Error codeSummary
0エラーなし
1.abort()による中止
2パラメータエラー
3リソースエラー
4コールバック処理エラー
5ソケットタイムアウト
6スリープ移行に伴う中止
103Request-Body不足によるエラー
104Request-Body不正によるエラー
115ソケットエラー


{IncomingMessage}

本オブジェクトは、https.request()により内部で生成され、コールバック処理の引数として返却されます。
本オブジェクトが返却されたタイミングから、受信したレスポンスヘッダは参照可能です。

Methods()/PropertiesSummaryVersionNote
.on()イベントハンドラを登録します。01.00.00+
.read()Response-Bodyを読み出します。01.00.00+
.readBin()Response-Bodyをバイナリ形式で読み出します。01.00.00+
.statusCodeHTTPレスポンスフレームのステータスライン上のステータスコード01.00.00+
.statusMessageHTTPレスポンスフレームのステータスライン上のステータスメッセージ01.00.00+
.headersHTTPレスポンスフレームのヘッダ01.00.00+


Details

.on(event,callback)

イベントハンドラを登録します。

NameTypeM/OSummaryNote
eventstringmandatoryイベント名
使用できるイベント名はerror, readable, endとなります。
callback()functionmandatoryイベント発生時にコールバック処理を実行します。
returnundefined--

event : ’error’

HTTP-Responseの受信が完了しなかった場合にコールバック処理を実行します。
同時に、{ClientRequest}のerrorイベントにも反映します。

event : ’readable’

HTTP-Responseの受信バッファにデータが存在する場合にコールバック処理を実行します。
データ受信を行う場合は本イベントを必ずハンドルする必要があります。
尚、readableイベントが発生せず、endイベントが直接発生する場合があります。

event : ’end’

HTTP-Responseの受信が完了した場合にコールバック処理を実行します。
データ受信を行う場合は本イベントを必ずハンドルする必要があります。

.read()

Response-Bodyを読み出します。

NameTypeM/OSummaryNote
returnstring, null-読み出したResponse-Bodyデータ存在しない場合はnullを返却します。

.readBin()

Response-Bodyをバイナリ形式で読み出します。

NameTypeM/OSummaryNote
returnArrayBuffer, 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'ヘッダの値を参照する場合は以下のようにします。

https.request(options, function(res) {
 print(res.headers.Date);
});


オブジェクトの使用例

Sample 1

GETメソッドのサンプルです。分割受信を行っています。

var HEADERS = {};
var options = {method: 'GET', host: '192.168.1.1', port: 443, path: '/test.txt', headers: HEADERS};
options.ca = '-----BEGIN CERTIFICATE-----\n' +
'SIGD0jCCArqgAwIBAgIBATANBgkqhkiG9w0BAQUFADB6MQswCQYDVQQGEwJKUDEO\n' +
'MAwGA1UECAwFSXdhdGUxFTATBgNVBAoMDE1vYmljb21tIEx0ZDEcMBoGA1UEAwwT\n' +
//........
'HvMvDtFO71gaEtIkpejHGLgGhQK1dQ==\n' +
'-----END CERTIFICATE-----\n';

var request = https.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: 443, path: '/post', headers: HEADERS};
options.ca = '-----BEGIN CERTIFICATE-----\n' +
'SIGD0jCCArqgAwIBAgIBATANBgkqhkiG9w0BAQUFADB6MQswCQYDVQQGEwJKUDEO\n' +
'MAwGA1UECAwFSXdhdGUxFTATBgNVBAoMDE1vYmljb21tIEx0ZDEcMBoGA1UEAwwT\n' +
//........
'HvMvDtFO71gaEtIkpejHGLgGhQK1dQ==\n' +
'-----END CERTIFICATE-----\n';

var request = https.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: 2020-08-28
← 前次 →