Documents

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

はじめに

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 “Air 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 (VPG) 機能詳細をご確認ください。

コンフィグパラメータ

"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 は、Air 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: SoracomFunnel

SORACOM Funnel は、デバイスからのデータを特定のクラウドサービスに直接転送するクラウドリソースアダプターです。この Namespace 以下では、転送先のクラウドサービス、リソースURL、クレデンシャル情報を設定できます。

コンフィグパラメータ

"SoracomFunnel": {
  "enabled": true | fales, // 機能自体のオンオフ、デフォルトは 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 | fales // 機能自体のオンオフ、デフォルトは false
}

設定例

[
  {
    "key": "enabled",
    "value": true
  }
]

Namespace: SoracomKrypton

SORACOM Krypton はセキュアプロビジョニングサービスです。この Namespace 以下では、Krypton利用のOn/OFF、プロビジョニングAPIの設定を行います。

Amazon Cognito

コンフィグパラメータ

"SoracomKrypton": {
  "enabled": true | fales, // 機能自体のオンオフ、デフォルトは 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 | fales, // 機能自体のオンオフ、デフォルトは 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\"}"
      }
    }
  }
]

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

Configuration の構造

Configuration の更新方法

PUT /groups/{group_id}/configuration/{namespace}

カスタムDNS機能

コンフィグパラメータ

リクエスト例

メタデータサービス

コンフィグパラメータ

リクエスト例

VPG (Virtual Private Gateway)

コンフィグパラメータ

リクエスト例

HTTP エントリポイント

コンフィグパラメータ

設定例

Webサイト エントリポイント

コンフィグパラメータ

設定例

MQTT エントリポイント

コンフィグパラメータ

設定例

TCP→TCP/TCPS エントリポイント

コンフィグパラメータ

設定例

TCP→HTTP/HTTPS エントリポイント

コンフィグパラメータ

設定例

UDP→HTTP/HTTPS エントリポイント

コンフィグパラメータ

設定例

コンフィグパラメータ

設定例

コンフィグパラメータ

設定例

コンフィグパラメータ

設定例

Amazon Cognito

コンフィグパラメータ

設定例

AWS IoT

コンフィグパラメータ

設定例

コンフィグパラメータ

設定例

Getting Started

SORACOM Air for セルラー

SORACOM Air for LoRaWAN

SORACOM Air for Sigfox

SORACOM Beam

SORACOM Canal/Direct/Door

SORACOM Endorse

SORACOM Funnel

SORACOM Gate

SORACOM Harvest

SORACOM Inventory

SORACOM Junction

SORACOM Krypton

SORACOM Lagoon

Gadgets

Device

サービス機能詳細

Developer Tools

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

Webサイトエントリポイント