ステップ 1: IoT Connect Gateway を設定する
ここでは、パソコンのブラウザ上で「Swagger」を利用してAPIコマンドを利用する場合を例としてご説 明します。Arcstar Universal OneモバイルSIMを利用しての通信となります。
1. Swagger にアクセスする
○ Swagger URL: https://api.icgw.ntt.com/api/index.html
2. 認証 Token を作成する
○ [POST] /api/v1/users/credentials を開く
○ [Try it out] を押す
○ Request body欄に以下を追加
{ "userName": "お客様のユーザ名", "password": "お客様のパスワード"
}
○ [Execute] を押すとtokenが作成される
※curlで送信したいユーザは、 [Execute] 押下後curl欄に表示されるコマンドをご使用くだ さい。
3. 作成した Token を使用し、 Authorize を実施する
○ [Authorize] を押す
○ Value欄に「Bearer（半角スペース）」を入力して2で作成したtokenを貼り付け、
[Authorize] を押す
以降、Swagger上でAPIを送信するとtoken情報が付与される
プロトコル変換設定（ HTTP/Things IoT の場合）
上記のAuthorizeを実施したあと、下記手順をSwagger上で実施して設定を行います。
（設定を実施する際にはToken情報が付加されている必要があります。）
1. SIM に Things Cloud の System ID を登録する
○ [PUT] /api/v1/sims/{imsi} を開き、[Try it out] を押す
○ [imsi] に使用しているSIMのimsiを入力する
○ Request body欄に以下を追加し、 [Execute] を押す
*は必須項目
項目 説明
systemId * Things CloudのSystem ID
Request例：
{ "systemId": "400"
}
更新が成功する場合、レスポンスコード200 OKが返されます。
System IDの確認方法は、Things Cloudのポータルにログインし、左のメニューから [デバ
イス] > [すべてのデバイス] を選択し、デバイスの [システムID] 列から取得できます：
2. 新規グループを作成し、 SIM をグループへ追加する
○ [POST] /api/v1/groups を開き、 [Try it out] を押す
○ Request body欄に以下を追加し、 [Execute] を押す
*は必須項目
項目 説明
name * 任意のグループ名
sims * 本グループに追加するSIMのIMSI番号
Request例：
{ "name": "グループ１",
"sims": [ "44010123456789"]
}
Response例：
{ "id": "5fd19167c653f932439cc9ca", "name": "グループ１",
"userId": "5fd19166c653f932439cc9c9", "sims": ["44010123456789"],
"protocolConversion": []
}
→ 作成したグループの ”id” を取得
3. Things IoT の認証情報を作成する
○ [POST] /api/v1/authentications/{type} を開き、 [Try it out] を押す
○ [type] に以下を入力
項目 説明
type things-iot-credentials
○ Request body欄に以下を追加し、 [Execute] を押す
*は必須項目
項目 説明
name 任意の認証情報名
description 任意の設定概要
userName * Things CloudのユーザーID
password * Things Cloudのパスワード
tenantId * Things CloudのテナントID
tenantIDはこちらから確認可能です。
Request例：
{ "name": "Things IoT Auth", "description": "testing",
"userName": "tc000.je1.thingscloud.ntt.com", "password": "password",
"tenantId": "t11111111"
}
Response例：
{ "description": "testing",
"userName": "tc000.je1.thingscloud.ntt.com", "password": "password",
"tenantId": "t11111111",
"id": "7a1dc7ad-f395-498a-9d84-a3916449d4a9", "name": "Things IoT Auth",
"type": "things-iot-credentials"
}
→ 作成した認証情報の “id” を取得
4. グループに対してプロトコル変換設定を追加する
○ [POST] /api/v1/groups/{groupId}/event/{serviceType} を開き、 [Try it out] を押す
○ groupId、serviceTypeに以下を入力
項目 説明
groupId 「1. 新規グループを作成し、SIMをグループへ追加す
る」で取得したGroup ID
pconvType http serviceType things-iot
○ Examplesプルダウンで「Things IoT」を選択し、
Request body欄に以下を追加し [Execute] を押す
*は必須項目
項目 説明
name * 任意のプロトコル変換設定名
enabled trueまたはfalse（デフォルト：true）
プロトコル変換設定を有効化する場合はtrueを設定する entrypoint
path * 本GWの送信先パスとして任意に設定可能。
● グループ内で一意の値（送信先パスを変更すれば 一つのグループで複数のHTTP設定を設定可 能）。
● 任意の値を設定しない場合も「/」のみ入力する必 要あり。
● *（ワイルドカード）を使用することにより任意の 文字列を指定することも可能。（*の使用は１つの み可）
destination
serviceType * things-iot
authenticationId * 「2. Things IoTの認証情報を作成する」で取得した
Authentication ID
host * 転送先（Things Cloud）のホスト名
path 転送先（Things Cloud）のパス
● 現在IoT Connect Gatewayでサポートしているの はThings Cloud APIのうち以下３つのAPIのpath になります。
○ /inventory/managedObjects/<<systemID>>
（※1）
○ /event/events
○ /measurement/measurements
● 本項目をnullとした場合、entrypoint pathで指定 したpathにマッチした（デバイスの）値を destination pathとして使用します。（※2） headers
appendImsi trueまたはfalse（デフォルト：true）
「c8y_Mobile」フラグメントに接続した端末のIMSI情報
を追加する場合はtrueを設定する（※3） appendImei trueまたはfalse（デフォルト：false）
「c8y_Mobile」フラグメントに接続した端末のIMEI情報
を追加する場合はtrueを設定する（※3） appendMsisdn trueまたはfalse（デフォルト：true）
「c8y_Mobile」フラグメントに接続した端末のMSISDN
を追加する場合はtrueを設定する（※3） enabled
(customHeaders) Trueまたはfalse（デフォルト：false）
任意のカスタムヘッダを編集（追加、置換、削除）する場 合はtrueを設定する
action 次のいずれか：
add: カスタムヘッダを追加
replace: カスタムヘッダを置換
remove: カスタムヘッダを削除
headerName カスタムヘッダ名
小文字のみ使用可能
headerValue カスタムヘッダの値
actionがremoveの時は設定不可
■ （※1）「/inventory/managedObjects/$tc_systemid」と設定すると「1.SIMに Things CloudのSystem IDを登録する」でSIM情報に設定したSystemIDを
<$tc_systemid>の部分に付与してThings Cloudに送信します。
■ （※2）例えば、entrypoint pathでは「/inventory/managedObjects/*」が登録され、
デバイスが「https://{GWのドメイン}/inventory/managedObjects/xxx」に送信した場 合、destination pathは自動的に「/inventory/managedObjects/xxx」に設定されま す。
■ （※3）「c8y_Mobile」フラグメントについてはThings Cloud HPを参照
■ （※3）ヘッダの設定が有効化されているが、データが存在しない場合、データの値
をNAとする。
Request例：
{ "enabled": true,
"name": "Things IoT HTTP", "entrypoint": {
"path": "/things-iot"
},
"destination": {
"host": "tc000.je1.thingscloud.ntt.com", "path": "/measurement/measurements", "serviceType": "things-iot",
"authenticationId": "ece20936-6928-4baa-9110- e458f9717657"
},
"headers":{
"appendImsi": true, "appendImei": false, "appendMsisdn": true, "customHeaders": [ {
"enabled": true, "action": "add",
"headerName": "accept", "headerValue":
"application/vnd.com.nsn.cumulocity.measurement+json"
}, {
"enabled": true, "action": "add",
"headerName": "content-type", "headerValue":
"application/vnd.com.nsn.cumulocity.measurement+json"
} ] } }
Response例：
{ "entrypoint": {
"path": "/things-iot"
},
"destination": {
"host": "tc000.je1.thingscloud.ntt.com", "path": "/measurement/measurements", "serviceType": "things-iot",
"authenticationId": "ece20936-6928-4baa-9110- e458f9717657"
},
"headers":{
"appendImsi": true, "appendImei": false, "appendMsisdn": true, "customHeaders": [
{
"enabled": true, "action": "add",
"headerName": "accept", "headerValue":
"application/vnd.com.nsn.cumulocity.measurement+json"
}, {
"enabled": true, "action": "add",
"headerName": "content-type", "headerValue":
"application/vnd.com.nsn.cumulocity.measurement+json"
} ] },
"id": "b1b8e993-023c-459f-ac27-9086634a7716", "type": "http",
"name": "Things IoT HTTP", "enabled": true
}
ステップ 2: IoT Connect Gateway を使用して Things IoT にデータを送信する
現在IoT Connect GatewayでサポートしているのはThings Cloud APIのうち以下３つのAPIになります。
接続方法の詳細はThings CloudHPを参照ください。
PUT <<url>>/inventory/managedObjects/<<deviceId>>
POST <<url>>/event/events
POST <<url>>/measurement/measurements
※各APIで必要なヘッダ情報は「4.グループに対してプロトコル変換設定を追加する」のカスタムヘッダ を使用して登録可能です。
1. Things Cloud でデバイスを登録
Things Cloudに送信するには、デバイスを登録しなければなりません。すでに登録した場合はステ
ップ２に進んでください。
1. デバイスを登録するには、Things CloudのREST APIを利用します。以下のCURLコマン ドでデバイスを登録してください：
# curl -v -u <Things CloudのUsername>:<Things Cloudのパスワード
> \
-H 'Accept:
application/vnd.com.nsn.cumulocity.managedobject+json;
charset=UTF-8; ver=0.9' \ -H 'Content-type:
application/vnd.com.nsn.cumulocity.managedobject+json;
charset=UTF-8; ver=0.9' \ -X POST \
-d '{"c8y_IsDevice":{},"name":"<デバイスの名前>"}' \ http://<Things Cloudのtenant-
ID>.je1.thingscloud.ntt.com/inventory/managedObjects
例：
# curl -v -u tc000.je1.thingscloud.ntt.com:password \ -H 'Accept:
application/vnd.com.nsn.cumulocity.managedobject+json;
charset=UTF-8; ver=0.9' \ -H 'Content-type:
application/vnd.com.nsn.cumulocity.managedobject+json;
charset=UTF-8; ver=0.9' \ -X POST \
-d '{"c8y_IsDevice":{},"name":"http-device-001"}' \
http://t11111111.je1.thingscloud.ntt.com/inventory/managedObjec ts
2. 成功するとThings Cloudは以下のレスポンスを返します。
{ "additionParents": { "self":
"https://t11111111.je1.thingscloud.ntt.com/inventory/managedObj ects/556236/additionParents",
"references": []
},
"owner": "tc000.je1.thingscloud.ntt.com", "childDevices": {
"self":
"https://t11111111.je1.thingscloud.ntt.com/inventory/managedObj ects/556236/childDevices",
"references": []
},
"childAssets": { "self":
"https://t11111111.je1.thingscloud.ntt.com/inventory/managedObj ects/556236/childAssets",
"references": []
},
"creationTime": "2021-08-19T12:11:43.261+09:00", "lastUpdated": "2021-08-19T12:11:43.261+09:00", "childAdditions": {
"self":
"https://t11111111.je1.thingscloud.ntt.com/inventory/managedObj ects/556236/childAdditions",
"references": []
},
"name": "mqtt-explorer-4f0ca284", "assetParents": {
"self":
"https://t11111111.je1.thingscloud.ntt.com/inventory/managedObj
ects/556236/assetParents", "references": []
},
"deviceParents": { "self":
"https://t11111111.je1.thingscloud.ntt.comm/inventory/managedOb jects/556236/deviceParents",
"references": []
}, "self":
"https://t11111111.je1.thingscloud.ntt.com/inventory/managedObj ects/556236",
"id": "556236", "c8y_IsDevice": {}
}
レスポンスのIDパラメータは、作成されたデバイスのSystem IDです。
デバイス登録の詳しい情報は、こちらを参考してください：
https://developer.ntt.com/iot/docs/device-sdk/rest/
2. デバイスからデータを送信する
○ curlコマンドを用いて、デバイスからHTTPリクエストを送信
○ 送信先：http:// an1.icgw.ntt.com/{path}
送信例：
curl -X POST -i http://an1.icgw.ntt.com/things-iot -d
'{ "c8y_TemperatureMeasurement": { "T": { "value": 33, "unit":
"C" } }, "time": "2021-06-28T15:05:00.000+09:00", "source":
{ "id": "$tc_systemid" }, "type":
"c8y_TemperatureMeasurement" }'
※リクエスト内に”$tc_systemid"と指定すると「1.SIMにThings CloudのSystem IDを登 録する」でSIM情報に設定したSystemIDを<$tc_systemid>の部分に付与してThings
Cloudに送信します。
※同様に以下の値もリクエストに含めるとSIM情報で設定した情報に変換してThings
Cloudに送信します。
● $imsi
● $imei
● $msisdn
以下のようなレスポンスが返ってくる HTTP/1.1 200 OK
Content-Type: application/json Date: Mon, 28 Jun 2021 08:17:25 GMT Connection: keep-alive
Keep-Alive: timeout=5 Transfer-Encoding: chunked
{"statusCode":201,"body":{"result":"ok","detail":{"self":"https
://t11111111.je1.thingscloud.ntt.com/measurement/measurements/2 258","time":"2021-06-
28T15:05:00.000+09:00","id":"2258","source":{"self":"https://t1 1111111.je1.thingscloud.ntt.com/inventory/managedObjects/999","
id":"999"},"type":"c8y_TemperatureMeasurement","c8y_Temperature Measurement":{"T":{"unit":"C","value":33}}}}}
3. データを確認する
○ Things Cloudのポータルにログインし、左のメニューから [デバイス] > [すべてのデバイス] を選択
○ 送信したデバイスを選択
○ 送信したデータをご確認いただけます。（下記イメージはメジャーメントにPOSTした場 合）
○ 「4.グループに対してプロトコル変換設定を追加する」でIMSI、IMEI、MSISDNを付加し た場合、こちらに表示されます。
