エントリポイントリファレンス: UDP → HTTP/HTTPS エントリポイント | SORACOM Beam

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

送信可能なデータサイズには制限があります

1 回のデータ送信あたりの最大送信データサイズは、UDP データグラムの最大サイズに準拠します。そのため、ヘッダーを含めて 65536 バイト以上は送信できません。また、MTU (Maximum Transmission Unit。一般的には 1500 バイト) を超えるデータを送信する場合は、パケットが IP 層で分割 / 再結合される影響などで、データが転送先に届かない確率 (パケットロス率) が増加する可能性があります。HTTP エントリポイントや TCP → HTTP/HTTPS エントリポイントの利用も検討してください。

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

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

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

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

項目説明

[設定名]

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

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

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

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

[転送先]

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

項目	説明
[プロトコル]	転送する際のプロトコルを選択します。
[ホスト名]	転送先の FQDN (Fully Qualified Domain Name) を入力します。例: `beamtest.soracom.io`
[ポート番号]	転送先のポート番号を入力します。例: `8080`
[パス]	転送先のパスを入力します。例: `/to/`

[ヘッダ操作] 転送先へのリクエストに追加するヘッダーを設定します。詳しくは、HTTP エントリポイントの [ヘッダ操作] を参照してください。

[レスポンス]

項目	説明
[ステータスコードを省略]	レスポンスに HTTP のステータスコードを含まないようにします。詳しくは、レスポンスのステータスコードを省略するを参照してください。

SORACOM CLI / SORACOM API の場合

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

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

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

SORACOM CLI のコマンド例:

$ soracom groups put-config --group-id {group_id} --namespace SoracomBeam \
--body '[
  {
    "key": "udp://beam.soracom.io:23080",
    "value": {
      "name": "udp2https",
      "enabled": true,
      "destination": "https://beamtest.soracom.io",
      "addSubscriberHeader": true,
      "addSimIdHeader": false,
      "addMsisdnHeader": false,
      "addEquipmentHeader": false,
      "addSignature": true,
      "psk": {
        "$credentialsId": "CredentialsID"
      },
      "customHeaders": {
        "X-GROUP-NAME": {
          "action": "append",
          "headerKey": "X-GROUP-NAME",
          "headerValue": "TEST"
        }
      },
      "skipStatusCode": true
    }
  }
]'

SORACOM CLI や API で設定を更新するときは

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

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

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

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

key value の型 value

name

String

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

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

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

enabled

Boolean

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

true: 有効
false: 無効

destination String エントリポイントで受け付けたリクエストの転送先 (URL) を入力します。例: https://example.com:443/to/

addSubscriberHeader

Boolean

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

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

addSimIdHeader

Boolean

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

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

addMsisdnHeader

Boolean

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

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

addEquipmentHeader

Boolean

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

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

addSignature

Boolean

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

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

psk.$credentialsId String addSignature が true のときに、署名に利用する事前共有鍵の認証情報 IDを指定します。認証情報 ID は、認証情報ストアに事前共有鍵を登録したときに指定しています。詳しくは、署名ヘッダと事前共有鍵を使って送信元を検証するを参照してください。

customHeaders

Object

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

key value の型 value

カスタムヘッダーの名前

Object

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

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

リクエストヘッダーは大文字小文字が区別されません

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

skipStatusCode

Boolean

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

true: レスポンスに HTTP のステータスコードを含みません。
false: レスポンスに HTTP のステータスコードを含みます。

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

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

以下は、デバイスで nc コマンドを利用して、UDP → HTTP/HTTPS エントリポイント (beam.soracom.io:23080) にデータを送信する場合の例です。例の最後の 200 は、転送先の HTTP/HTTPS サーバーが返した HTTP ステータスコードです。

$ echo "test message" | nc -v -u beam.soracom.io 23080

Connection to beam.soracom.io port 23080 [udp/*] succeeded!

200

ヘッダー操作について

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

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

デバイスへのレスポンス

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

${HTTP ステータスコード} ${転送先サーバーから返された HTTP レスポンスのボディ}

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

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