グループコンフィグレーション 詳細
はじめに
SORACOM の各種サービス機能は、Group に基づいて設定の管理が行われております。 Group 毎に Configuration のデータが保持され、各サービスはその内容に基づいて動作します。
Configuration の構造
Group の Configuration は、
{
"configuration":{
"NAMESPACE":{
"KEY1": "VALUE1",
"KEY2": [ "VALUE2-1", "VALUE2-2" ],
"KEY3": { "SUBKEY": "SUBVALUE" }
}
}
}
のように、各サービス(=Namespace)配下に、複数の Key & Value が配置されるような構造となっております。また、各Key配下のValueでは、様々な構造を取りえます。 各サービス(Namespace)毎の Configuration 項目の詳細につきましては、後述いたします。
Configuration の更新方法
Configuration を 更新するには、Update Group Configuration Parameters APIコールにて下記のようなフォーマットのデータを PUT する事で更新が行えます(既に同じ Key が存在する場合には上書きされ、新規の Key である場合には追記されます点にご注意ください)。
PUT /groups/{group_id}/configuration/{namespace}
PUTするデータのbody部分
[
{
"key": "KEY1",
"value": "VALUE1"
},
{
"key": "KEY2",
"value": [ "VALUE2-1", "VALUE2-2" ]
},
{
"key": "KEY3",
"value": { "SUBKEY": "SUBVALUE" }
}
]
例えばCLI では、下記のように更新を行う事ができます。
$ soracom group update_configuration --group-id GROUP-ID \
--namespace NAMESPACE \
--params '[{"key":"KEY1","value":"VALUE1"},{"key":"KEY2","value":["VALUE2-1","VALUE2-2"]},{"key":"KEY3","value":{"SUBKEY":"SUBVALUE"}}]'
以下では、各サービス(Namespace)毎の機能別に設定項目をご紹介いたします。
Namespace: SoracomAir
SORACOM Air とは IoT 向けのデータ通信 SIM “IoT SIM” を提供するサービスです。 この Namespace 以下では、主に通信や SIM に関する設定が行えます。
カスタムDNS機能
当該 Group に属する SIM が通信を開始した際に、独自の DNS サーバアドレスを渡す機能です(参考:カスタム DNS を設定する)。
※有効にする事で追加のコストが発生するので、ご注意ください
コンフィグパラメータ
"SoracomAir":{
"useCustomDns": true | false, // 機能自体のオンオフ、デフォルトはfalse
"dnsServers": [ "DNSサーバIPアドレス1", "DNSサーバIPアドレス2" ] // 2つまで
}
リクエスト例
[
{
"key": "useCustomDns",
"value": true
},
{
"key": "dnsServers",
"value": [
"8.8.8.8",
"8.8.4.4"
]
}
]
メタデータサービス
SORACOM Air で通信を行っている端末から、自身の使用している SIM に関する情報を認証なしで取得したり、Group に設定された userdata を取得したりする事ができるサービス(参考:SORACOM Air メタデータサービス機能を使用する)。
コンフィグパラメータ
"SoracomAir": {
"metadata": {
"enabled": true | false, // 機能自体のオンオフ、デフォルトは false
"readonly": true | false, // 書き込みアクセスの禁止、デフォルトは true
"allowOrigin": "string" // CORS によるクロスドメインアクセスを許可する URL の指定
},
"userdata": "string" // 任意のユーザ定義データ
}
リクエスト例
[
{
"key": "metadata",
"value": {
"enabled": true,
"readonly": true,
"allowOrigin": "http://some.example.com"
}
},
{
"key": "userdata",
"value": "foobar"
}
]
VPG (Virtual Private Gateway)
VPG は、SORACOM の Canal, Direct, Door, Gate などのネットワークサービス各種サービスを利用する上で重要な役割を担う機能コンポーネントです。 VPG を使用して、お客様のシステムと接続し、さらに SORACOM Air のグループ機能で VPG を有効化することで、そのグループの SIM カードを使うデバイスからの通信を直接お客様のシステムにルーティングすることが可能となります。 詳細は、Virtual Private Gateway 開発者ガイド をご確認ください。
コンフィグパラメータ
"SoracomAir":{
"useVpg": true | false, // 機能自体のオンオフ、デフォルトはfalse
"vpgId": "string", // VPG IDを指定します
}
リクエスト例
[
{
"key":"useVpg",
"value":true},
{
"key":"vpgId",
"value":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"}
]
Namespace: SoracomBeam
SORACOM Beam は、IoT デバイスにかかる暗号化等の高負荷処理や接続先の設定を、クラウドにオフロードできるサービスです。 この Namespace 以下では、データ転送に関する設定を行う事ができます。
HTTP エントリポイント
特定のパスに HTTP で受けた通信を、HTTP または HTTPS で転送を行う設定です。APIエンドポイントに対して転送するのに向いています。
コンフィグパラメータ
"http://beam.soracom.io:8888/": { // 固定
"name": "string", // 任意の名称
"destination": "https://example.com/path/to/resource", // 通信先URL
"enabled": true | false, // エンドポイントの有効無効
"addSubscriberHeader": true, // Subscriber の情報をヘッダとして付与するか否か
"customHeaders": { // 独自HTTPヘッダ
"X-HEADER-NAME": { // 独自ヘッダの名前
"action": "replace" | "append" | "delete", // 置換、追記、削除が選択可能
"headerKey": "X-HEADER-NAME",
"headerValue": "VALUE" // ヘッダに設定する内容
}
},
"addSignature": true | false, // 検証用シグネチャを付与するか否か
"psk": "string" // 検証用シグネチャを計算する際の事前共有パスフレーズ
}
設定例
[
{
"key": "http://beam.soracom.io:8888/",
"value": {
"name": "test",
"destination": "https://beamtest.soracom.io/",
"enabled": true,
"addSubscriberHeader": true,
"customHeaders": {
"X-GROUP-NAME": {
"action": "replace",
"headerKey": "X-GROUP-NAME",
"headerValue": "TEST"
}
},
"addSignature": true,
"psk": "topsecret"
}
}
]
Webサイト エントリポイント
全てのパスに対して HTTP で受けた通信を、HTTP または HTTPS で転送を行う設定です。Webサイト全体を Beam で転送するのに向いています。
設定上のポートは 18080 となっており、 http://beam.soracom.io:18080 でも通信を行えますが、 http://beam.soracom.io (80番ポート)に対して通信を行ってもよい状態となっております。
コンフィグパラメータ
"http://beam.soracom.io:18080": { // 固定、スラッシュを含まない
"name": "string", // 任意の名称
"destination": "https://example.com", // 通信先のFQDNまでを指定
"enabled": true | false, // エンドポイントの有効無効
"addSubscriberHeader": true, // Subscriber の情報をヘッダとして付与するか否か
"customHeaders": { // 独自HTTPヘッダ
"X-HEADER-NAME": { // 独自ヘッダの名前
"action": "replace" | "append" | "delete", // 置換、追記、削除が選択可能
"headerKey": "X-HEADER-NAME",
"headerValue": "VALUE" // ヘッダに設定する内容
}
},
"addSignature": true | false, // 検証用シグネチャを付与するか否か
"psk": "string" // 検証用シグネチャを計算する際の事前共有パスフレーズ
}
設定例
[
{
"key": "http://beam.soracom.io:18080",
"value": {
"name": "test",
"destination": "https://beamtest.soracom.io",
"enabled": true,
"addSubscriberHeader": true,
"customHeaders": {
"X-GROUP-NAME": {
"action": "replace",
"headerKey": "X-GROUP-NAME",
"headerValue": "TEST"
}
},
"addSignature": true,
"psk": "topsecret"
}
}
]
MQTT エントリポイント
MQTT で受けた通信を、MQTT または MQTTS で転送を行う設定です。
コンフィグパラメータ
"mqtt://beam.soracom.io:1883": { // 固定
"name": "string", // 任意の名称
"destination": "mqtts://mqtt.example.com/topicname", // MQTT接続先
"enabled": true | false, // エンドポイントの有効無効
"addSubscriberHeader": true | false, // topic にIMSI を足すか否か
"username": "USERNAME", // ユーザ名(任意)
"password": "PASSWORD", // パスワード(任意)
"useClientCert": true | false, // TLSクライアント証明書を使用するか否か
"clientCerts": { // 上記を有効にした場合は必須
"default": { // 現状は証明書を1つだけ登録可能
"key": "...", // 秘密鍵(PEM形式)
"cert": "...", // 証明書(PEM形式)
"ca": "...", // CA証明書(PEM形式)
}
},
"useCaCert": true | false, // 独自のCA証明書を使用するか否か
"caCert": "...", // CA証明書(PEM形式)
"usePubnub": true | false, // 転送先がPubNubの場合Trueにする(任意、指定なしの場合 false)
"useAzureIoT": true | false, // 転送先がAzureIoTの場合Trueにする(任意、指定なしの場合 false)
"useGoogleIoT": true | false // 転送先がGoogleIoTの場合Trueにする(任意、指定なしの場合 false)
}
設定例
[
{
"key": "mqtt://beam.soracom.io:1883",
"value": {
"name": "AWS IoT",
"destination": "mqtts://data.iot.ap-northeast-1.amazonaws.com:8883",
"enabled": true,
"addSubscriberHeader": false,
"useClientCert": true,
"clientCerts": {
"default": {
"key": "-----BEGIN RSA PRIVATE KEY-----\n...",
"cert": "-----BEGIN CERTIFICATE-----\n...",
"ca": "-----BEGIN CERTIFICATE-----\n..."
}
}
}
}
]
TCP→TCP/TCPS エントリポイント
任意のTCPソケット通信を、そのまま、または TLS で暗号化して転送を行う設定です。
コンフィグパラメータ
"tcp://beam.soracom.io:8023": { // 固定
"name": "string", // 任意
"destination": "tcps://secure.example.com:1234", // 通信先のホスト名&ポートを指定
"enabled": true | false, // エンドポイントの有効・無効
"addSubscriberHeader": true | false, // 通信開始時に Subscriber の情報を送るか否か
"addSignature": true | false, // 検証用のシグネチャを付与するか否か
"psk": "string" // 検証用シグネチャを計算する際の事前共有パスフレーズ
}
設定例
[
{
"key":"tcp://beam.soracom.io:8023",
"value": {
"name": "beamtest",
"destination": "tcps://beamtest.soracom.io:1234",
"enabled": true,
"addSubscriberHeader": true,
"addSignature": true,
"psk": "topsecret"
}
}
]
TCP→HTTP/HTTPS エントリポイント
TCPソケットで受信したデータを JSON 形式で HTTP または HTTPS に POST をする機能です。 受け取ったデータはバイナリである可能性もあるため、base64 エンコードされて下記のような形式となり、POST されます。
{
"payload": "BASE64エンコードされたデータ"
}
コンフィグパラメータ
"tcp://beam.soracom.io:23080": { // 固定
"name": "string", // 任意
"destination": "tcps://secure.example.com:1234", // 通信先のホスト名&ポートを指定
"enabled": true | false, // エンドポイントの有効・無効
"addSubscriberHeader": true | false, // 通信開始時に Subscriber の情報を送るか否か
"addSignature": true | false, // 検証用のシグネチャを付与するか否か
"psk": "string", // 検証用シグネチャを計算する際の事前共有パスフレーズ
"customHeaders": { // 独自HTTPヘッダ
"X-HEADER-NAME": { // 独自ヘッダの名前
"action": "append" // 追記のみ可能
"headerKey": "X-HEADER-NAME",
"headerValue": "VALUE" // ヘッダに設定する内容
}
}
}
設定例
[
{
"key":"tcp://beam.soracom.io:23080",
"value": {
"name": "telnet2https",
"destination": "https://beamtest.soracom.io/",
"enabled": true,
"addSubscriberHeader": true,
"addSignature": true,
"psk": "topsecret",
"customHeaders": {
"X-GROUP-NAME": {
"action": "append",
"headerKey": "X-GROUP-NAME",
"headerValue": "TEST"
}
}
}
}
]
UDP→HTTP/HTTPS エントリポイント
UDPで受信したデータを JSON 形式で HTTP または HTTPS に POST をする機能です。 受け取ったデータはバイナリである可能性もあるため、base64 エンコードされて下記のような形式となり、POST されます。
{
"payload": "BASE64エンコードされたデータ"
}
コンフィグパラメータ
"udp://beam.soracom.io:23080": { // 固定
"name": "string", // 任意
"destination": "tcps://secure.example.com:1234", // 通信先のホスト名&ポートを指定
"enabled": true | false, // エンドポイントの有効・無効
"addSubscriberHeader": true | false, // 通信開始時に Subscriber の情報を送るか否か
"addSignature": true | false, // 検証用のシグネチャを付与するか否か
"psk": "string", // 検証用シグネチャを計算する際の事前共有パスフレーズ
"customHeaders": { // 独自HTTPヘッダ
"X-HEADER-NAME": { // 独自ヘッダの名前
"action": "append" // 追記のみ可能
"headerKey": "X-HEADER-NAME",
"headerValue": "VALUE" // ヘッダに設定する内容
}
}
}
設定例
[
{
"key":"udp://beam.soracom.io:23080",
"value": {
"name": "udp2https",
"destination": "https://beamtest.soracom.io/",
"enabled": true,
"addSubscriberHeader": true,
"addSignature": true,
"psk": "topsecret",
"customHeaders": {
"X-GROUP-NAME": {
"action": "append",
"headerKey": "X-GROUP-NAME",
"headerValue": "TEST"
}
}
}
}
]
Namespace: SoracomEndorse
SORACOM Endorse は、IoT SIM を使用しているデバイスに対して、SORACOM が認証プロバイダーとしてデバイスの認証サービスを提供します。 この Namespace 以下では、トークンに含めるべきパラメータを設定できます。
コンフィグパラメータ
"SoracomEndorse": {
"enabled": true | false, // 機能自体のオンオフ、デフォルトは false
"parametersToEndorse" { // トークンに含むべきパラメータを選択。選択可能なパラメータはimsi, imei, msisdn, requestParameters
"imsi": true | false,
"imei": true | false,
"msisdn": true | false,
"requestParameters": true
},
"tokenTimeoutSeconds": 600, // (optional) トークンの発行時からの有効な期間の秒数を設定
"allowOrigin": "https://soracom.io", //(optional) CORSヘッダを有効にする場合に指定。設定した文字列がレスポンスのaccess-control-allow-originヘッダに設定される
"authorizedRedirectUrls": ["https://soracom.io", "http://localhost:3000"] //(optional) SORACOM Endorseのレスポンスを使ってクライアントを別のURLにリダイレクトとさせる場合に、リダイレクト先のURLの候補を指定。(このパラメータに含まれないURLへのリダイレクトリクエストは拒否されます)
}
設定例
[
{
"key": "enabled",
"value": true
},
{
"key":"parametersToEndorse",
"value": {
"imsi": true,
"imei": true,
"msisdn": false,
"requestParameters": true
}
},
{
"key": "tokenTimeoutSeconds",
"value": 600
},
{
"key": "allowOrigin",
"value": "https://soracom.io"
},
{
"key": "authorizedRedirectUrls",
"value": ["https://soracom.io", "http://localhost:3000"]
}
]
Namespace: SoracomFunk
SORACOM Funk は、クラウドサービスの Function を直接実行できるサービスです。 この Namespace 以下では、利用するクラウドサービス、送信するデータの形式、認証情報を設定できます。
コンフィグパラメータ
"SoracomFunk": {
"enabled": true | false, // 機能自体のオンオフ、デフォルトは false
"destination": {
"provider": "aws" | "azure" | "google", // AWS, Azure, Google を選択
"service": "lambda" | "function-app" | "cloud-functions", // AWS Lambda, Azure Functions, GCP Cloud Functions を選択
"resourceUrl": "https://example.com/path/to/resource" // クラウドサービスのリソースURLを指定
},
"credentialsId": {
"$credentialsId": "my-credentials", // SORACOMに登録したクレデンシャル名
},
"contentType": "unspecified" | "application/json" | "text" | "binary" // payloads内のユーザデータに対する処理を指定(JSONの場合にはJSONとしてパースする)
}
設定例
[
{
"key": "enabled",
"value": true
},
{
"key": "destination",
"value": {
"provider": "aws",
"service": "lambda",
"resourceUrl": "arn:aws:lambda:ap-northeast-1:XXXXXXXXXXXX:function:funk-sample_hello"
}
},
{
"key": "$credentialsId",
"value": {
"my-credentials"
}
},
{
"key": "contentType",
"value": "application/json"
}
]
Namespace: SoracomFunnel
SORACOM Funnel は、デバイスからのデータを特定のクラウドサービスに直接転送するクラウドリソースアダプターです。 この Namespace 以下では、転送先のクラウドサービス、リソースURL、クレデンシャル情報を設定できます。
コンフィグパラメータ
"SoracomFunnel": {
"enabled": true | false, // 機能自体のオンオフ、デフォルトは false
"destination": {
"provider": "aws" | "azure" | "google", // AWS, Azure, Google を選択
"service": "aws-iot" | "kinesis" | "firehose" | "eventhubs" | "pubsub", // AWS IoT、Kinesis Streams、Kinesis Firehose、Event Hubs、Google Cloud Pub/Sub を選択
"resourceUrl": "https://example.com/path/to/resource" // クラウドサービスのリソースURLを指定
},
"credentialsId": "my-credentials", // SORACOMに登録したクレデンシャル名
"contentType": "" | "json" // payloads内のユーザデータに対する処理を指定(JSONの場合にはJSONとしてパースする)
}
設定例
[
{
"key": "enabled",
"value": true
},
{
"key": "destination",
"value": {
"provider": "aws",
"service": "kinesis",
"resourceUrl": "https://kinesis.ap-northeast-1.amazonaws.com/my-kinesis-stream"
}
},
{
"key": "credentialsId",
"value": "my-credentials"
},
{
"key": "contentType",
"value": "json"
}
]
Namespace: SoracomHarvest
SORACOM Harvest は、IoTデバイスからのデータを収集、蓄積するサービスです。 この Namespace 以下では、Harvest利用のOn/OFFを設定します。
コンフィグパラメータ
"SoracomHarvest": {
"enabled": true | false // 機能自体のオンオフ、デフォルトは false
}
設定例
[
{
"key": "enabled",
"value": true
}
]
Namespace: SoracomHarvestFiles
SORACOM Harvest Filesは、IoTデバイスからのファイルを収集、保存するサービスです。 この Namespace 以下では、Harvest利用のOn/OFFを設定します。
コンフィグパラメータ
"SoracomHarvestFiles": {
"enabled": true | false, // 機能自体のオンオフ、デフォルトは false
"defaultPath" : "/path/file", // 送信されたファイルのデフォルトの保存先
"assumedRoleId" : "role_name" // SIMからのリクエストの権限のロール
}
設定例
[
{
"key":"enabled",
"value":true
},
{
"key":"defaultPath",
"value":"/test/"
},
{
"key":"assumedRoleId",
"value":"role01"
}
]
Namespace: SoracomKrypton
SORACOM Krypton はセキュアプロビジョニングサービスです。 この Namespace 以下では、Krypton利用のOn/OFF、プロビジョニングAPIの設定を行います。
Amazon Cognito
コンフィグパラメータ
"SoracomKrypton": {
"enabled": true | false, // 機能自体のオンオフ、デフォルトは false
"AmazonCognito": {
"region": "us-xxx-xx", // 使用する Cognito のリージョンとなります。
"credentialsId": "aws-iot-xxx", //ソラコムの認証情報ストア名を指定します。
"identityPoolId": "us-west-2:xxxxxxxx-xxxxx-xxxxxxx", //CognitoのIDプールのIDです。
"developerProviderName": "krypton.soracom.io" // Cognitoで設定したdeveloperProviderNameを指定します。
}
}
設定例
[
{
"key": "enabled",
"value": true
},
{
"key": "AmazonCognito",
"value": {
"region": "us-west-2",
"credentialsId": "aws-credential",
"identityPoolId": "us-west-2:xxxxxxxx-xxxxx-xxxxxxx",
"developerProviderName": "krypton.soracom.io"
}
}
]
AWS IoT
コンフィグパラメータ
"SoracomKrypton": {
"enabled": true | false, // 機能自体のオンオフ、デフォルトは false
"AwsIot": {
"region": "us-xxx-xx", // 使用する AWS IoT のリージョンとなります。
"credentialsId": "aws-iot-xxx", //ソラコムに設定した認証情報ストア名を指定します。
"policyName": "us-west-2:xxxxxxxx-xxxxx-xxxxxxx", //新しく作成された証明書に割り当てるポリシー名を入力します。
"thingNamePattern": "myDevice-$imsi", // クライアントが指定していない場合に使用する Thing name を入力します。 `$imsi` と指定するとプレースホルダーとして IMSI に置き換えます。
"host": "xxx.iot.us-west-2.amazonaws.com"
}
}
設定例
[
{
"key": "enabled",
"value": true
},
{
"key": "AwsIot",
"value": {
"region": "us-west-2",
"credentialsId": "aws-credential",
"policyName": "myThingPolicy",
"thingNamePattern": "myDevice-$imsi",
"host": "xxx.iot.us-west-2.amazonaws.com"
}
}
]
Namespace: SoracomOrbit
SORACOM Orbit は IoT デバイスとクラウド間の通信経路上でお客様が作成したデータ処理プログラムを実行できるサービスです。 この Namespace 以下では、実行する WASM モジュールやメタデータ利用の有無などを設定できます。
コンフィグパラメータ
"SoracomOrbit": {
"enabled": true | false, // 機能自体のオンオフ、デフォルトは false
"codeSrn": "srn:soracom:OP0000000000:jp:Soralet:name/version", // 使用する WASM モジュールの SRN (SORACOM Resource Name)
"useLocation": true | false, // plan-KM1 でのみ利用可能な簡易位置測位機能を使用するかの設定。デフォルトは false。plan-KM1 以外の SIM で true にしても位置情報初得できない
"useMetadata": true | false, // リソースのメタデータ(タグなど)を使用するかのオンオフ、デフォルトは false
"contentType": "mime type", // 入力の Content Type
"direction": ["downlink", "uplink"] // 処理するデータの方向。 uplink: デバイスからクラウド方向 / downlink: クラウドからデバイス方向
}
設定例
[
{ "key": "enabled", "value": true },
{ "key": "codeSrn", "value": "srn:soracom:OP0000000000:jp:Soralet:hello/1" },
{ "key": "useLocation", "value": true },
{ "key": "useMetadata", "value": true },
{ "key": "contentType", "value": "application/json" },
{ "key": "enabled", "value": true },
{ "key": "direction", "value": ["downlink", "uplink"] }
]
Namespace: UnifiedEndpoint
Unified Endpointは、一つのエンドポイントで SORACOM Beam、SORACOM Funnel、SORACOM Harvest にデータを送信できます。
コンフィグパラメータ
"UnifiedEndpoint": {
"response": {
"format": "Auto" | "Unified" | "SoracomBeam" | "SoracomFunnel" | "SoracomHarvest" | "Custom", // レスポンスのフォーマットの選択(デフォルトは Auto)
"success": {
"statusCode": "" // format:Custom の場合、成功時のステータスコードを指定
"contentType": "" // format:Custom の場合、成功時のレスポンスの Content-Type ヘッダーの値を指定
"body": "" // format:Custom の場合、成功時のレスポンスBodyを指定
},
"failure": {
"statusCode": "" // format:Custom の場合、失敗時のステータスコードを指定
"contentType": "" // format:Custom の場合、失敗時のレスポンスの Content-Type ヘッダーの値を指定
"body": "" // format:Custom の場合、失敗時のレスポンスBodyを指定
}
}
設定例
[
{
"key": "response",
"value": {
"format": "Custom",
"success": {
"statusCode": "200",
"contentType": "application/json",
"body": "{\"result\":\"ok\"}"
},
"failure": {
"statusCode": "500",
"contentType": "application/json",
"body": "{\"result\":\"ng\"}"
}
}
}
]