Soracom

Users

ドキュメント
Home ドキュメント 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 time)",
  "imsi": "送信元のSIMのIMSI",
  "imei": "送信元デバイスのIMEI"
}
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 v1TCP で送信されたバイナリデータが、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 で送信することで、大きめのバイナリデータを Funnel で転送できます。

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

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

  1. 「メッセージ長フィールド」に指定する値を決定します。

    送信するバイナリデータは 6 バイトのため、「メッセージ長フィールド」は以下のとおりです。

    0x00 0x06
    
  2. 「メッセージ長フィールド」と「メッセージボディ」を結合します。

    0x00 0x06 0x01 0x02 0x03 0x04 0x05 0x06
    
  3. このデータの「チェックサム」(CRC-16 CCITT) を計算します。

    簡易的に計算する場合は、https://crccalc.com/ のようなサイトでチェックサムを計算できます。

    0x4917
    
  4. ここまでのバイト列を連結して、Funnel のエントリポイントに送信します。

    $ echo "00060102030405064917" | xxd -r -p | nc -4 -u funnel.soracom.io 23080 -w 1
    
    200
    
  5. 送信先のクラウドサービスでデータを確認します。

    {
        :
      "payloads": "AAYBAgMEBQZJFw==",
        :
    }
    
  6. AAYBAgMEBQZJFw== を Base64 でデコードして、ファイルに保存します。

    $ echo 'AAYBAgMEBQZJFw==' | base64 --decode > recieved.bin
    

この手順で保存された recieved.bin には、「メッセージ長フィールド」(先頭 2 バイト) と「チェックサム」(末尾 2 バイト) が含まれます。

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