Azure IoT v2

このライブラリは、Azure IoT Hubと通信する機能を提供する組み込みクラスです。

Library usage requirements
Type Integrations
Name Azure_IoT_V2
Version 2.1.0
Code size used 4.1KB
Resources used HTTPS x 1, MQTT x 1, Timers x 1

関連資料

制限事項

  • このライブラリはShared Access Signature (SAS) トークンによるデバイス認証のみサポートします。
    x.509 証明書を使用したデバイス認証はサポートしていません。


Abstracts

Methods()/PropertiesSummaryNote
new AZURE_IOT()AZURE_IOTインスタンスを生成します。

{AZURE_IOT} Instance

Methods()/PropertiesSummaryNote
.generateSasToken()SASトークンを生成します。
.httpPost()HTTPS経由でAzure IoT Hubにデータを送信します。
.abortHttpRequest()現在進行中のHTTPリクエストを中止します。
.mqttConnect()Azure IoT HubにMQTT接続します。
.errors無効なキー名(文字列)を含む配列
コンストラクタまたは.setConfig()で無効なパラメータが検出された場合に生成されます。
.CONST.VERSIONバージョン(文字列)v2.1.0+


Details

new AZURE_IOT([config])

AZURE_IOTインスタンスを生成します。

NameTypeM/ODescriptionNote
configObjectoptionalコンフィグレーション
詳細はconfigを参照してください。
return{AZURE_IOT}-{AZURE_IOT} : 生成された{AZURE_IOT}無効なパラメータが検出された場合、.errorsが生成されます。

config

NameTypeM/ODescriptionNote
hoststringmandatoryAzure IoT Hubエンドポイント
既定では、Azure IoT HubのDNS名は{IoT Hub 名}.azure-devices.netのようになります。
deviceIdstringmandatoryデバイスID
Azure IoT HubのIDレジストリにデバイス登録した際に作成されます。
primaryKeystringmandatoryサービスプライマリキー
IDレジストリの対称デバイスキーもしくは共有アクセスキーを指定します。
castringmandatoryAzure IoT HubのルートCA証明書
PEM形式の文字列を指定します。改行コードには\nを使用します。
tokenTimeoutnumberoptionalSASトークンのタイムアウト値[秒]
生成するSASトークンが有効となる期間を指定します。
デフォルト値は3600となります。
httpTimeoutnumberoptionalHTTPリクエストのタイムアウト値[秒]
0の場合、タイムアウト機能無効となります。
デフォルト値は0となります。		v2.1.0+
timeoutnumber-本パラメータは無視されます。未使用

AZURE_IOTインスタンス生成時に、コンフィグレーション(config)を設定します。
無効なパラメータが検出された場合、無効なキーの名前を含む配列が.errorsプロパティとして生成されます。パラメータが正常であった場合、.errorsプロパティは削除されます。

var iot = new AZURE_IOT({
    host: <value>,
    deviceId: <value>,
    primaryKey: <value>,
    ca: <value>,
    tokenTimeout: <value>
});
if('errors' in iot) {
    //TODO: Handle errors
}

.setConfig(config)

AZURE_IOTインスタンス生成後に、コンフィグレーション(config)を設定します。
無効なパラメータが検出された場合、無効なキーの名前を含む配列が.errorsプロパティとして生成されます。パラメータが正常であった場合、.errorsプロパティは削除されます。

var iot = new AZURE_IOT();
iot.setConfig({
    host: <value>,
    deviceId: <value>,
    primaryKey: <value>,
    ca: <value>,
    tokenTimeout: <value>
});
if('errors' in iot) {
    //TODO: Handle errors
}

Setter Methods

AZURE_IOTインスタンス生成後に、下記セッターメソッドを使用して個別にコンフィグレーション(config)を設定可能です。
成功した場合、自身のインスタンスが返却されます。無効なパラメータが検出された場合は、falseが返却されます。

Setter MethodDescriptionNote
.setHost(value)hostを設定します。
.setDeviceId(value)deviceIdを設定します。
.setPrimaryKey(value)primaryKeyを設定します。
.setRootCA(value)caを設定します。
.setTokenTimeout(value)tokenTimeoutを設定します。
.setHttpTimeout(value)httpTimeoutを設定します。v2.1.0+
.setTimeout(value)timeoutを設定します。未使用

.generateSasToken([[[[resourceUri],signingKey],policyName],expiresInSecs])

SASトークンを生成します。

NameTypeM/ODescriptionNote
resourceUristringoptionalエンドポイントのURIプレフィックスを指定します。
デフォルト値は${config.host}/devices/${config.deviceId}となります。
signingKeystringoptionalSASトークンの署名キーを指定します。
デフォルト値はconfig.primaryKeyとなります。
policyNamestringoptional共有アクセスポリシー名を指定します。
指定された場合のみ、SASトークンに承認規則名が追加されます。
デフォルト値はundefinedとなります。
expiresInSecsnumberoptionalトークンのタイムアウト値[秒]を指定します。
本メソッドが呼び出された時間にタイムアウト値を加算した時間がトークンの有効期限となります。
デフォルト値はconfig.tokenTimeoutとなります。
returnstring-HTTPSリクエストやMQTT接続の確立に使用される認証トークン

.httpPost(token,length,getBody,callback[[,endpoint],sockTo])

HTTPS経由でAzure IoT Hubにデータを送信します。

NameTypeM/ODescriptionNote
tokenstringmandatory.generateSasToken()メソッドで生成した認証トークンを指定します。
lengthnumbermandatory送信データ(body)サイズを指定します。
getBodyfunctionmandatory送信データ(body)引き取り時にコールバック処理を実行します。
データがなくなるまで、4KB以下のstringもしくはArrayBufferチャンクでデータを渡し、最後にnullを渡します。
callback(err, resp)functionmandatory処理完了時にコールバック処理を実行します。
コールバック関数の引数で処理結果を通知します。
err: {HttpReqError}, null
resp: {HttpResponse}, null
HTTPリクエストでエラーが発生した場合はerr、HTTPレスポンスが受信できた場合はrespが設定されます。
endpointstringoptionalルーティングエンドポイントを指定します。
デフォルト値は/devices/${config.deviceId}/messages/events?api-version=2018-06-30となります。
sockTonumberoptionalHTTPセッションのタイムアウト値[ms]を指定します。
本パラメータはhttps.request()メソッドのsockTo設定値となります。詳しくはHTTPSオブジェクト仕様を参照してください。		v2.1.0+
returnundefined-

{HttpReqError}

NameTypeDescriptionNote
.errCodenumberHTTPSリクエストのエラーコード
詳しくはHTTPSオブジェクトのエラーコード表を参照してください。

{HttpResponse}

NameTypeDescriptionNote
.statusCodenumberHTTPレスポンスのステータスコード
.statusMessagestringHTTPレスポンスのステータスメッセージ
.bodystring, nullHTTPレスポンスデータ (Response-Body)

.abortHttpRequest()

現在進行中のHTTPリクエストを中止します。

NameTypeM/ODescriptionNote
returnundefined-

.mqttConnect(token[,options])

Azure IoT HubにMQTT接続します。

本メソッドはmqtt.connect()メソッドのラッパー関数です。
Azure IoT HubにMQTT接続するためのMQTTクライアントインスタンス{Client}を生成します。
生成された{Client}インスタンスの使用方法については、MQTTオブジェクト仕様を参照してください。

NameTypeM/ODescriptionNote
tokenstringmandatory.generateSasToken()メソッドで生成した認証トークンを指定します。
optionsobjectoptional本パラメータはmqtt.connect()メソッドのoptions設定値となります。詳しくはMQTTオブジェクト仕様を参照してください。
尚、一部パラメータは本メソッドによって上書きされます。
return{Client}, undefined-Azure IoT Hub用MQTTクライアントインスタンス

本メソッドによって上書きされるmqtt.connect()関連の設定値

  • mqtt.set(’ssl.ca’, certificate)
    • certificate: config.ca
  • mqtt.connect(url[, options])
    • url: mqtts://${config.host}:8883
    • options.clientId: config.deviceId
    • options.username: ${config.host}/${config.deviceId}/?api-version=2018-06-30
    • options.password: token


Usage Examples

すべてのサンプルコードにおいて、以下の共通コードを使用します。

ルートCA証明書がAzure IoT Hubエンドポイントに対して適切であることを事前に確認してください。
CA証明書の取得方法については、こちらを参考にしてください。

log.setLevel(0,2); //-1:NONE 0:ERROR 1:WARNING 2:DEBUG 3:TRACE, 0:DISABLE 1:LOG 2:CONSOLE 3:BOTH
log.printLevel(2); //0:DISABLE 1:LOG 2:CONSOLE 3:BOTH

var rootCa = '-----BEGIN CERTIFICATE-----\n...<CA>...\n-----END CERTIFICATE-----';

//TODO: Configuration
var config = {
    host: <value>,
    deviceId: <value>,
    primaryKey: <value>,
    ca: rootCa,
    tokenTimeout: <value>
};
var iot = new AZURE_IOT(config);
if('errors' in iot) {
    //TODO: Handle errors
    throw new Error("Invalid configuration");
}

Sample 1

HTTPS経由でAzure IoT Hubにデータを送信します。

var token = iot.generateSasToken();
var body = "sample text to send to Azure IoT Hub";

var busy;
var getBody = function() {
    var temp = body;
    body = null;
    return temp;
};
var callback = function(err, resp) {
    if(err) {
        print("Error!", err.errCode);
    } else {
        print("Response:", resp.body);
        print("Status:", resp.statusCode, resp.statusMessage);
    }
    busy = false;
};

busy = true;
iot.httpPost(token, body.length, getBody, callback);
while(busy);
print("Done");

Sample 2

HTTPS経由でAzure IoT Hubにデータを分割送信します。

var token = iot.generateSasToken();
var body = "sample text to send to Azure IoT Hub[...]";

var busy;
var chunkSize = 8; //4KB or less
var index = 0;
var getBody = function() {
    var chunk = body.substring(index, index + chunkSize);
    if(chunk) {
        index = index + chunkSize;
        return chunk;
    }
    return null;
};
var callback = function(err, resp) {
    if(err) {
        print("Error!", err.errCode);
    } else {
        print("Response:", resp.body);
        print("Status:", resp.statusCode, resp.statusMessage);
    }
    busy = false;
};

busy = true;
iot.httpPost(token, body.length, getBody, callback);
while(busy);
print("Done");

Sample 3

Azure IoT HubにMQTT接続します。
MQTT接続が切断された際、トークンを更新して、MQTT再接続を行います。

var mqttConnect = function(onConnected, onDisconnected) {
    var token = iot.generateSasToken(); //Update token
    print(token);
    var cli = iot.mqttConnect(token);
    if(!cli) return undefined;
    cli.on('error', function(err) {
        //TODO: Handle errors
        print("Error!", err.code, `(${cli.get('errnoConnect')})`);
        if(err.code == 1 && onDisconnected) { //Connection failed
            onDisconnected();
            return;
        }
    });
    cli.on('message', function(topic, message) {
        //TODO: Handle messages
        print("Message:", `[${topic}]`, message);
    });
    cli.on('close', function() {
        print("DISCONNECTED");
        if(onDisconnected) {
            onDisconnected();
        }
    });
    cli.on('connect', function() {
        print("CONNECTED");
        if(onConnected) {
            onConnected();
        }
    });
    return cli;
};

var onMqttConnect = function() {
    client.subscribe(`devices/${config.deviceId}/messages/devicebound/#`, { qos: 1 }, function(err) {
        if(err.code != 0) {
            //TODO: Handle errors
            print("Subscribe failed:", err.code);
        }
    });
};
var onMqttDisconnect = function() {
    if(client) client.end();
    client = undefined;
    setTimeout(function() {
        print("Reconnecting...");
        client = mqttConnect(onMqttConnect, onMqttDisconnect);
        if(!client) {
            onMqttDisconnect();
        }
    }, 10000);
};

var client = mqttConnect(onMqttConnect, onMqttDisconnect);
if(!client) {
    throw new Error("Failed to create mqtt instance");
}

var publishInterval = 5 * 1000;
var publishEvent = false;
var publishCnt = 0;
setInterval(function() {
    publishEvent = true;
}, publishInterval);

while(1) {
    if(client && client.canPublish() && publishEvent) {
        publishEvent = false;
        publishCnt++;
        var message = JSON.stringify({ "message": "publish" + publishCnt });
        client.publish(`devices/${config.deviceId}/messages/events/?api-version=2018-06-30`, message, { qos: 1 }, function(err) {
            if(err.code == 0) {
                print("Publish OK");
            } else {
                //TODO: Handle errors
                print("Publish failed:", err.code);
            }
        });
    }
}


上記に記載されている会社名、製品名は、各社の登録商標または商標です。
Updated: 2024-03-26
← 前次 →