リファレンス: SORACOM Funnel から送信されるデータ | SORACOM Funnel

クラウドサービスには、以下のようなフォーマットのデータが送信されます。

{
  "credentialId": "ソラコムの認証情報のID",
  "operatorid": "ソラコムのアカウントID",
  "destination": {
    "provider": "(aws|azure|google)",
    "service": "(aws-iot|kinesis|firehose|eventhubs|pubsub)",
    "resourceUrl": "送信先クラウドサービスのURL",
    "payloadsOnly": false,
    "sendPayloadsAsBinary": (true|false)
  },
  "sourceProtocol": "(tcp|udp|http|sigfox|lora|unspecified)",
  "payloads": "送信されたデータ本体",
  "timestamp": "Funnel でデータを処理した日時 (UNIX 時間)",
  "imsi": "送信元のSIMのIMSI",
  "imei": "送信元デバイスのIMEI"
}

Funnel が対応する TLS バージョンは 1.2 です

Funnel が対応する TLS バージョンは 1.2 です。クラウドサービスでは、TLS 1.2 に対応するように設定してください。たとえば、AWS IoT Core に送信する場合は、AWS IoT Core の [セキュリティポリシーを選択] では、TLS 1.2 に対応するセキュリティポリシーを選択してください。たとえば、「IoTSecurityPolicy_TLS13_1_2_2022_10」は TLS 1.2 に対応しています。

payloads 以外の値が送信されないように設定できます

[ペイロードのみ転送する] を ON に設定すると、payloads に設定されるデータだけが送信されます。payloads 以外の値 (credentialId など) は送信されません。

[送信データ形式] が「JSON」で、[ペイロードのみ転送する] が OFF の場合:

{
  "credentialsId": "AWS-IAM-role-credentials",
  "operatorId": "OPxxxxxxxxxx",
  "destination": {
    "provider": "aws",
    "service": "aws-iot",
    "resourceUrl": "xxxxx-ats.iot.ap-northeast-1.amazonaws.com/myTopic/#{imsi}",
    "payloadsOnly": false,
    "sendPayloadsAsBinary": false
  },
  "sourceProtocol": "http",
  "payloads": {
    "deviceid": "iot123",
    "temp": 54.98,
    "humidity": 32.43,
    "coords": {
      "latitude": 47.615694,
      "longitude": -122.3359976
    }
  },
  "timestamp": 1653891795421,
  "imsi": "2950xxxxxxxxxxx",
  "imei": "8676xxxxxxxxxxx"
}

[送信データ形式] が「JSON」で、[ペイロードのみ転送する] が ON の場合:

{
  "deviceid": "iot123",
  "temp": 54.98,
  "humidity": 32.43,
  "coords": {
    "latitude": 47.615694,
    "longitude": -122.3359976
  }
}

payloads に設定されるデータ

payloads に設定されるデータは、[送信データ形式] の設定によって異なります。

デバイスでのコマンド例:

curl -v funnel.soracom.io \
-H "Content-Type: application/json" \
-d '{
  "deviceid": "iot123",
  "temp": 54.98,
  "humidity": 32.43,
  "coords": {
    "latitude": 47.615694,
    "longitude": -122.3359976
  }
}'

上記のコマンドを実行して Funnel にデータを送信した場合に、payloads に設定されるデータは、以下のとおりです。

[送信データ形式] の設定	説明
(指定しない)	エントリポイントの種類によって、データの処理が異なります。 UDP: バイナリデータとして処理されます。(1) TCP: バイナリデータとして処理されます。(1) HTTP: HTTP ヘッダーの `Content-Type` に従って処理されます。 SMS: テキストデータとして処理されます。 USSD: テキストデータとして処理されます。 Air for LoRaWAN、Air for Sigfox、Inventory: バイナリデータとして処理されます。(*1)
JSON	エントリポイントの種類に関わらず、JSON 形式のデータとして処理されます。 `{ : "payloads": { "deviceid": "iot123", "temp": 54.98, "humidity": 32.43, "coords": { "latitude": 47.615694, "longitude": -122.3359976 } }, : }` デバイスが、JSON 形式以外のデータを送信した場合は、`400 Bad Request` が返されます。
テキスト	エントリポイントの種類に関わらず、テキストデータとして処理されます。 `{ : "payloads": "{\n \"deviceid\": \"iot123\",\n \"temp\": 54.98,\n \"humidity\": 32.43,\n \"coords\": {\n \"latitude\": 47.615694,\n \"longitude\": -122.3359976\n }\n}", : }`
バイナリ	エントリポイントの種類に関わらず、バイナリデータとして処理されます。(*1) `{ : "payloads": "ewogICJkZXZpY2VpZCI6ICJpb3QxMjMiLAogICJ0ZW1wIjogNTQuOTgsCiAgImh1bWlkaXR5IjogMzIuNDMsCiAgImNvb3JkcyI6IHsKICAgICJsYXRpdHVkZSI6IDQ3LjYxNTY5NCwKICAgICJsb25naXR1ZGUiOiAtMTIyLjMzNTk5NzYKICB9Cn0=", : }`
SORACOM Binary Format v1	TCP で送信されたバイナリデータが、SORACOM Binary Format v1 に準拠するものとして処理されます。詳しくは、SORACOM Binary Format v1 を参照してください。

(*1) 仮に JSON 形式のデータと同じフォーマットで Funnel に送信した場合でも、バイナリデータとして処理されます。

バイナリデータは JSON 形式に変換されて転送されます

バイナリデータとして処理される場合は、以下の JSON 形式に変換されたうえで転送されます。payloads の値 (eyJs...) は、デバイスから送信した JSON 形式のデータを Base64 形式でエンコードしたものです。これを、payload 変換と呼びます。
```
{
    :
  "payloads": "eyJsYXQiOm51bGwsImxvbiI6bnVsbCwiYmF0IjozLCJycyI6MywidGVtcCI6MTkuOSwiaHVtaSI6NDcuNiwieCI6bnVsbCwieSI6bnVsbCwieiI6bnVsbCwidHlwZSI6MX0=",
    :
}
```
payload 変換されたデータから元のデータを取り出すには、payloads の値 (eYJs...) を Base64 形式でデコードしてください。
バイナリパーサーや Orbit で処理された場合は、処理後のデータが JSON 形式のデータとして Funnel のエントリポイントに出力されるため、payload 変換は行われません。

SORACOM Binary Format v1

SORACOM Binary Format v1 を選択した場合は、以下のフォーマットに従ったバイナリデータを TCP で送信することで、最大 65535 バイトのバイナリデータを Funnel で転送できます。

項目	バイト数	説明
メッセージ長フィールド	2 バイト	メッセージボディのバイト数を指定します。0x0001 の場合は 1 バイト、0xffff の場合は 65535 バイトを表します。
メッセージボディ	メッセージ長フィールドに指定したバイト数	送信対象のバイナリデータを指定します。
チェックサム	2 バイト	メッセージ長フィールドとメッセージボディを結合したもののチェックサムです。CRC-16 CCITT に従って計算してください。

バイナリデータ「0x01 0x02 0x03 0x04 0x05 0x06」を SORACOM Binary Format v1 に準拠して送信するには、メッセージ長フィールドとチェックサムを以下のように算出します。

「メッセージ長フィールド」に指定する値を決定します。
送信するバイナリデータは 6 バイトのため、「メッセージ長フィールド」は以下のとおりです。
```
0x00 0x06
```
「メッセージ長フィールド」と「メッセージボディ」を結合します。
```
0x00 0x06 0x01 0x02 0x03 0x04 0x05 0x06
```
このデータの「チェックサム」(CRC-16 CCITT) を計算します。
簡易的に計算する場合は、https://crccalc.com/ のようなサイトでチェックサムを計算できます。
```
0x4917
```
ここまでのバイト列を連結して、Funnel のエントリポイントに送信します。
```
$ echo "00060102030405064917" | xxd -r -p | nc -4 -u funnel.soracom.io 23080 -w 1
```
```
200
```
送信先のクラウドサービスでデータを確認します。
```
{
    :
  "payloads": "AAYBAgMEBQZJFw==",
    :
}
```
AAYBAgMEBQZJFw== を Base64 でデコードして、ファイルに保存します。
```
$ echo 'AAYBAgMEBQZJFw==' | base64 --decode > recieved.bin
```

この手順で保存された recieved.bin には、「メッセージ長フィールド」(先頭 2 バイト) と「チェックサム」(末尾 2 バイト) が含まれます。
Funnel は、最初の TCP セグメントを受け取った時点でタイマーを起動し、次の TCP セグメントを待ち受けます。タイマーは約 10 秒に設定されており、この時間内に期待される次のパケットが届かない場合、クライアントにタイムアウトを表すメッセージを返し、それまで Funnel でバッファしていたメッセージの断片を破棄します。なお、このタイマーは各 TCP セグメントの到着ごとにリセットされます。

SORACOM Binary Format v1 の制限について

バイナリパーサーとは併用できません。バイナリパーサーを利用する場合は、JSON 形式のデータとして処理されます。
Unified Endpoint とは併用できません。Unified Endpoint に SORACOM Binary Format v1 に準拠したデータを送信しても、Funnel では SORACOM Binary Format v1 に準拠したデータとして処理されません。

Soracom

Users

SORACOM Funnel から送信されるデータ