グループコンフィグレーション 詳細

はじめに

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 に属する Subscriber が通信を開始した際に、独自の DNS サーバアドレスを渡す機能です(参考:カスタム DNS を設定する)。

※有効にする事で追加のコストが発生するので、ご注意ください

コンフィグパラメータ

"SoracomAir":{
    "useCustomDns": true | false, // 機能自体のオンオフ、デフォルトはfalse
    "dnsServers": [ "DNSサーバIPアドレス1", "DNSサーバIPアドレス2" ] //  ２つまで
}

リクエスト例

[
  {
    "key": "useCustomDns",
    "value": true
  },
  {
    "key": "dnsServers",
    "value": [
      "8.8.8.8",
      "8.8.4.4"
    ]
  }
]

メタデータサービス

SORACOM Air で通信を行っている端末から、自身の使用している Subscriber に関する情報を認証なしで取得したり、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": { // 現状は証明書を１つだけ登録可能
      "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: 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\"}"
      }
    }
  }
]