05. HTTPS

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

機能概要:

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

制限事項:

  • 同時に使用可能なHTTPセッションリソースは2本です。
    尚、このリソースはhttpオブジェクトとhttpsオブジェクトで共用となります。
  • リソースエラーは例外発生要因となります。
  • 暗号化通信には、証明機関(CA)によって署名された証明書が必要となります。自己署名証明書は許可されていません。


https Global Object

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


Details

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

HTTPS通信を開始します。

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

options

未設定の要素はデフォルト値で動作します。

NameTypeM/OSummaryNote
hoststringoptionalHTTPSサーバのドメイン名またはIPアドレス
デフォルト値は'127.0.0.1'となります。		文字数が127バイトを超えた場合、例外が発生します。
portnumberoptionalHTTPSサーバのポート番号
デフォルト値は443となります。
methodstringoptionalメソッド名
'GET', 'POST', 'PUT', 'HEAD' のいずれかが入ります。
デフォルト値は'GET'となります。
pathstringoptionalリクエストのパス
デフォルト値は'/'となります。
headersObjectoptionalリクエストヘッダ
任意のリクエストヘッダを含むオブジェクトを指定します。
このパラメータはオプションです。デフォルト値はありません。
castringmandatoryCA証明書
PEM形式の文字列を指定します。改行コードには\nを使用します。		本パラメータは必須です。
証明書が不正の場合、ソケットエラーが発生します。こちらを活用して証明書を検証してください。
certstringoptionalクライアント証明書
PEM形式の文字列を指定します。改行コードには\nを使用します。
指定しない場合、クライアント認証は無効となります。
keystringoptionalクライアント秘密鍵
PEM形式の文字列を指定します。改行コードには\nを使用します。
指定しない場合、クライアント認証は無効となります。


{ClientRequest}

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

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


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()イベントハンドラを登録します。
.read()Response-Bodyを読み出します。
.readBin()Response-Bodyをバイナリ形式で読み出します。
.statusCodeHTTPレスポンスフレームのステータスライン上のステータスコード
.statusMessageHTTPレスポンスフレームのステータスライン上のステータスメッセージ
.headersHTTPレスポンスフレームのヘッダ


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: 2024-01-17
← 前次 →