Soracom

Users

ドキュメント
フィードバック
Home ドキュメント SORACOM Beam エントリポイントリファレンス

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

TCP → HTTP/HTTPS エントリポイント (beam.soracom.io:23080) に、デバイスから TCP で送信されたデータを、任意のタイミングで HTTP リクエストまたは HTTPS リクエストに変換して指定の URL に転送 (POST) します。なお、TCP → HTTP/HTTPS エントリポイントに送信されたデータは、たとえ JSON 形式のデータと同じフォーマットでも、バイナリデータとして処理されます。

デバイスのアプリケーションが TCP で送信したデータは HTTP/HTTPS リクエストで転送されるときに分割 / 結合されることがあります

TCP (RFC 9293 Transmission Control Protocol (TCP)) は、デバイスのアプリケーションが送信したデータを、ネットワークの仕様や通信状況にあわせて適切に TCP セグメントという単位で分割して送信します。そして TCP → HTTP/HTTPS エントリポイントでは、TCP で受信したデータ (TCP セグメント) を、任意のタイミングで HTTP/HTTPS リクエストに変換して転送先サーバーに転送します。

その結果、デバイスのアプリケーションが TCP で送信したデータは、アプリケーションが送信した単位 (TCP コネクション単位や TCP セグメント単位) で転送されることは保証されません。たとえば、以下のようなことが発生します。

  • デバイスのアプリケーションが送信したデータが、TCP の仕様に従って複数の TCP セグメントに分割されることがあります。その場合、転送先サーバーに複数の HTTP リクエストまたは HTTPS リクエストとして転送されることがあります。
  • デバイスから 1 つの TCP コネクションで送信した複数のデータが TCP → HTTP/HTTPS エントリポイントで結合 (*1) され、1 つの HTTP リクエストまたは HTTPS リクエストとして転送されることがあります。

転送先では、デバイスのアプリケーションが送信したデータが分割 / 結合 (*1) されて転送されることも考慮してください。分割 / 結合されることに問題がある場合は、SORACOM Binary Format v1 や、HTTP エントリポイント の利用も検討してください。どちらもデバイスのアプリケーションでの対応が必要です。

  • (*1) TCP コネクションを確立してから切断するまでに、アプリケーションが複数のデータを送信した場合に、データが結合されることがあります。TCP コネクションの単位を超えて結合されることはありません。
バイナリデータは JSON 形式に変換されて転送されます

  • バイナリデータとして処理される場合は、以下の JSON 形式に変換されたうえで転送されます。payload の値 (eyJs...) は、デバイスから送信した JSON 形式のデータを Base64 形式でエンコードしたものです。これを、payload 変換と呼びます。

    {
  "payload": "eyJsYXQiOm51bGwsImxvbiI6bnVsbCwiYmF0IjozLCJycyI6MywidGVtcCI6MTkuOSwiaHVtaSI6NDcuNiwieCI6bnVsbCwieSI6bnVsbCwieiI6bnVsbCwidHlwZSI6MX0="
}

    payload 変換されたデータから元のデータを取り出すには、payload の値 (eYJs...) を Base64 形式でデコードしてください。

  • バイナリパーサー や Orbit で処理された場合は、処理後のデータが JSON 形式のデータとして UDP → HTTP/HTTPS エントリポイントに出力されるため、payload 変換は行われません。

TCP → HTTP/HTTPS エントリポイントを設定する

設定画面を表示する操作については、SORACOM Beam のエントリポイントを設定する を参照してください。TCP → HTTP/HTTPS エントリポイントで設定できる項目は以下のとおりです。

項目説明
[設定名]

任意の名前を入力します。

同じ名前の設定を追加できます

[設定名] は、エントリポイントの一意のキーとして扱われません。ほかのエントリポイントと同じ名前を設定できます。

[有効]この設定の有効 / 無効を切り替えます。
[転送先]

このエントリポイントで受け付けたリクエストの転送先を設定します。

項目説明
[プロトコル]転送する際のプロトコルを選択します。
[ホスト名]転送先の FQDN (Fully Qualified Domain Name) を入力します。例: beamtest.soracom.io
[ポート番号]転送先のポート番号を入力します。例: 8080
[パス]転送先のパスを入力します。例: /to/
[エントリポイント設定][SORACOM Binary Format v1 形式のデータを受け取る] をオンにすると、TCP で送信されたバイナリデータが、SORACOM Binary Format v1 に準拠するものとして処理され、転送先に転送されます。SORACOM Binary Format v1 形式について詳しくは、SORACOM Binary Format v1 (Public beta) を参照してください。
[ヘッダ操作]転送先へのリクエストに追加するヘッダーを設定します。詳しくは、HTTP エントリポイントの [ヘッダ操作] を参照してください。
[レスポンス]
項目説明
[ステータスコードを省略]レスポンスに HTTP のステータスコードを含まないようにします。詳しくは、レスポンスのステータスコードを省略する を参照してください。
[データ終端バイト列]レスポンスの末尾に、終端を識別するためのバイト列を付与します。デフォルトでは改行コード 0a が付与されます。詳しくは、レスポンスのデータ終端バイト列を設定する を参照してください。

SORACOM CLI / SORACOM API の場合

グループ設定に Beam のエントリポイントを追加するコマンドについては、SORACOM Beam のエントリポイントを設定する の SORACOM CLI / SORACOM API の場合 を参照してください。

ここでは、TCP → HTTP/HTTPS エントリポイントを追加する場合のリクエストボディに指定する key と value のペアを説明します。

keyvalue の型value
tcp://beam.soracom.io:23080ObjectTCP → HTTP/HTTPS エントリポイントの Object を参照してください。

SORACOM CLI のコマンド例:

$ soracom groups put-config --group-id {group_id} --namespace SoracomBeam \
--body '[
  {
    "key": "tcp://beam.soracom.io:23080",
    "value": {
      "name": "tcp2https",
      "enabled": true,
      "destination": "https://beamtest.soracom.io",
      "addSubscriberHeader": true,
      "addSimIdHeader": false,
      "addMsisdnHeader": false,
      "addEquipmentHeader": false,
      "addSignature": true,
      "customHeaders": {
        "X-GROUP-NAME": {
          "action": "append",
          "headerKey": "X-GROUP-NAME",
          "headerValue": "TEST"
        }
      },
      "skipStatusCode": true,
      "eodBytes": "",
      "psk": {
        "$credentialsId": "CredentialsID"
      }
    }
  }
]'
SORACOM CLI や API で設定を更新するときは

Beam のエントリポイントの設定を部分的に更新するときは、更新しない設定も含めて、すべての設定を漏れなく指定してください。更新する設定だけを指定すると、省略した設定は初期値に戻ります。

想定していない値を指定した場合の動作は、定義されていません。SORACOM CLI / SORACOM API で設定を変更したあとで、SORACOM ユーザーコンソールで意図通りに設定されていることを確認してください。

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

以下の key と value を指定します。なお、この key と value のペアは、通常の JSON Object として指定します。

keyvalue の型value
nameString

任意の名前を入力します。

同じ名前の設定を追加できます

name は、エントリポイントの一意のキーとして扱われません。ほかのエントリポイントと同じ名前を設定できます。

enabledBoolean

このエントリポイントの有効 / 無効を設定します。

  • true: 有効
  • false: 無効
destinationStringエントリポイントで受け付けたリクエストの転送先 (URL) を入力します。例: https://example.com:443/to/
addSubscriberHeaderBoolean

転送先へのリクエストに x-soracom-imsi: ${IMSI} ヘッダーを追加するかを設定します。${IMSI} には、IoT SIM の IMSI が挿入されます。

  • true: ヘッダーを追加します。
  • false: ヘッダーを追加しません。
addSimIdHeaderBoolean

転送先へのリクエストに x-soracom-sim-id: ${SIM_ID} ヘッダーを追加するかを設定します。${SIM_ID} には、IoT SIM の SIM ID が挿入されます。

  • true: ヘッダーを追加します。
  • false: ヘッダーを追加しません。
addMsisdnHeaderBoolean

転送先へのリクエストに x-soracom-msisdn: ${MSISDN} ヘッダーを追加するかを設定します。${MSISDN} には、IoT SIM の MSISDN が挿入されます。

  • true: ヘッダーを追加します。
  • false: ヘッダーを追加しません。
addEquipmentHeaderBoolean

転送先へのリクエストに x-soracom-imei: ${IMEI} ヘッダーを追加するかを設定します。${IMEI} には、デバイスの IMEI が挿入されます。

  • true: ヘッダーを追加します。
  • false: ヘッダーを追加しません。
addSignatureBoolean

転送先へのリクエストに x-soracom-signature: ${signature} ヘッダーを追加するかを設定します。${signature} には、Beam からのリクエストであることを検証するための署名が挿入されます。詳しくは、署名ヘッダと事前共有鍵を使って送信元を検証する を参照してください。

  • true: ヘッダーを追加します。
  • false: ヘッダーを追加しません。
customHeadersObject

転送先へのリクエストヘッダーを追加、置換、削除できます。

keyvalue の型value
カスタムヘッダーの名前Object

カスタムヘッダーの情報を指定します。

  • action: 以下のいずれかの値を指定します。
    • append: 転送先への HTTP リクエストに、カスタムヘッダーおよび値を追加して転送します。指定したヘッダーが存在する場合は、値は変更されません。
    • replace: 転送先への HTTP リクエストにカスタムヘッダーが存在していた場合に、その値を置換して転送します。なお、指定したヘッダーが存在しない場合は、ヘッダーと値が追加されます。
    • delete: 転送先への HTTP リクエストにカスタムヘッダーが存在していた場合に、そのカスタムヘッダーを削除して転送します。
  • headerKey: カスタムヘッダーの名前を指定します。
  • headerValue: action に append または replace を指定した場合に、カスタムヘッダーの値を指定します。
リクエストヘッダーは大文字小文字が区別されません

[カスタムヘッダ] では、大文字小文字を区別して登録できますが、一般に、リクエストヘッダーは大文字小文字が区別されません。大文字小文字を同一視した結果、同じ値になるヘッダーを複数登録した場合の動作は保証されません。

skipStatusCodeBoolean

レスポンスに HTTP のステータスコードを含むかを設定します。詳しくは、レスポンスのステータスコードを省略する を参照してください。

  • true: レスポンスに HTTP のステータスコードを含みません。
  • false: レスポンスに HTTP のステータスコードを含みます。
eodBytesStringレスポンスの末尾に、終端を識別するためのバイト列を付与します。デフォルトでは改行コード 0a が付与されます。詳しくは、レスポンスのデータ終端バイト列を設定する を参照してください。
psk.$credentialsIdStringaddSignature が true のときに、署名に利用する事前共有鍵の認証情報 IDを指定します。認証情報 ID は、認証情報ストア に事前共有鍵を登録したときに指定しています。詳しくは、署名ヘッダと事前共有鍵を使って送信元を検証する を参照してください。

TCP → HTTP/HTTPS エントリポイントにリクエストする

TCP → HTTP/HTTPS エントリポイントに、デバイスからデータを送信します。

以下は、デバイスで nc コマンドを利用して、TCP → HTTP/HTTPS エントリポイント (beam.soracom.io:23080) にデータを送信する場合の例です。

$ nc -v beam.soracom.io 23080
Connection to beam.soracom.io (100.127.127.100) 23080 port [tcp/*] succeeded!
Test data # 送信するデータを入力して、Enter キーを押します。
ヘッダー操作について

デバイスが送信したデータが転送先の URL に転送される際、Beam によって以下のヘッダー操作が行われます。

  • user_agent: SORACOM Beam が追加されます。
  • [ヘッダ操作] の設定に従って、ヘッダーが追加、置換、削除されます。詳しくは、HTTP エントリポイントの [ヘッダ操作] を参照してください。
デバイスへのレスポンス

TCP には HTTP のようなリクエスト&レスポンスの概念はありません。転送先の HTTP/HTTPS サーバーが返した HTTP ステータスコードと HTTP レスポンスのボディは、以下の形式で TCP パケットのペイロードに含めてレスポンスされます。

${HTTP ステータスコード} ${転送先サーバーから返された HTTP レスポンスのボディ}${[データ終端バイト列] に指定したバイト列}

なお、${HTTP ステータスコード} (半角スペースを含む) と、${[データ終端バイト列] に指定したバイト列} は省略できます。詳しくは、以下のページを参照してください。

レスポンスの具体例は以下のとおりです。

  • 転送先サーバーから、HTTP ステータスコードが 200 で、ボディがない HTTP レスポンスが返された場合の表示例:

    200

  • 転送先サーバーから、HTTP ステータスコードが 400 で、ボディ (Message from server) がある HTTP レスポンスが返された場合の表示例:

    400 Message from server\n

  • 転送先サーバーから、HTTP ステータスコードが 400 で、ボディ (Message from server) がある HTTP レスポンスが返され、[データ終端バイト列] が空欄だった場合の表示例:

    400 Message from server
© 2015-2024 SORACOM
最終更新日: 2024-10-25
エントリポイントリファレンス : TCP → TCP/TCPS エントリポイント
エントリポイントリファレンス : UDP → HTTP/HTTPS エントリポイント
会社概要 プレスルーム お問い合わせ プライバシー 商標 特定商取引法 契約約款
Facebook Twitter Speaker Deck YouTube Blog