HTTP エントリポイント
デバイスから HTTP リクエストを受け付け、HTTP もしくは HTTPS で転送先へリクエストを転送します。転送先としてパス (プロトコル、ホスト名、ポート番号、パス) を設定できます。任意の API エンドポイントに対して、リクエストを転送するユースケースに向いています。
Beam に送信する際は HTTPS プロトコルは利用できません
デバイスから Beam にデータを送信するときは、HTTPS プロトコルを利用できません。
1 つの SIM グループに対して、複数の HTTP エントリポイントを登録できます。ただし、 → (SORACOM CLI / API の場合は、最上位のキー。例: http://beam.soracom.io:8888/) が同一の HTTP エントリポイントは登録できません。
設定項目
設定できる項目は以下のとおりです。
| 項目 | 説明 | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Beam には同じ種類のエントリポイントを複数設定できます。設定を識別するために名前を入力します。 同じ名前の設定を追加できます は、エントリポイントの一意のキーとして扱われません。ほかのエントリポイントと同じ名前を設定できます。 | |||||||||||||||||
| この設定の有効 / 無効を切り替えます。 | |||||||||||||||||
デバイスからの HTTP リクエストを受け付けるエントリポイントを設定します。
| |||||||||||||||||
エントリポイントで受け付けたリクエストの転送先を設定します。
| |||||||||||||||||
転送先へのリクエストに追加するヘッダーを指定します。スイッチをオンにしたときに追加されるヘッダーは以下のとおりです。
リクエストヘッダーは大文字小文字が区別されません では、大文字小文字を区別して登録できますが、一般に、リクエストヘッダーは大文字小文字が区別されません。大文字小文字を同一視した結果、同じ値になるヘッダーを複数登録した場合の動作は保証されません。 |
multi credentials per group 機能
Beam では multi credentials per group 機能を使用できます。
で選択する認証情報の の任意の場所に #{imsi} もしくは #{imei} のプレースホルダーを入れることで、接続デバイスに応じた 認証情報を使い分けることができます。
詳しくは、multi credentials per group 機能を利用して AWS IoT に接続する を参照してください。
SORACOM CLI / SORACOM API の場合
グループ設定に Beam のエントリポイントを追加します。Beam のエントリポイントを追加するコマンドについては、SORACOM Beam を有効化する の SORACOM CLI / SORACOM API の場合 を参照してください。
ここでは、HTTP エントリポイントを追加する場合のリクエストボディに指定する key と value のペアを説明します。なお、この key と value のペアは、配列の要素として指定します。
key | value の型 | value |
|---|---|---|
http://beam.soracom.io:8888/{path} (*1) | Object | HTTP エントリポイントの Object を参照してください。 |
- (*1)
{path}には、転送元のパスを入力します。たとえば、{path}にfrom/を入力した場合は、デバイスからhttp://beam.soracom.io:8888/from/に送信したリクエストが、destinationで指定した転送先に転送されます。
転送元の設定が同じ HTTP エントリポイントは複数登録できません
http://beam.soracom.io:8888/{path} が、HTTP エントリポイントの一意のキーとして扱われます。複数の HTTP エントリポイントを作成する設定にしても、この値がほかの HTTP エントリポイントと同じ値になると、いずれか 1 つの HTTP エントリポイントだけが登録されます。HTTP エントリポイントの Object
以下の key と value を指定します。なお、この key と value のペアは、通常の JSON Object として指定します。
key | value の型 | value | ||||||
|---|---|---|---|---|---|---|---|---|
name | String | Beam には同じ種類のエントリポイントを複数設定できます。設定を識別するために名前を入力します。 同じ名前の設定を追加できます は、エントリポイントの一意のキーとして扱われません。ほかのエントリポイントと同じ名前を設定できます。 | ||||||
enabled | Boolean | この設定の有効 / 無効を設定します。
| ||||||
destination | String | エントリポイントで受け付けたリクエストの転送先 (URL) を入力します。例: https://beamtest.soracom.io/ | ||||||
addSubscriberHeader | Boolean | 転送先へのリクエストに
| ||||||
addSimIdHeader | Boolean | 転送先へのリクエストに
| ||||||
addMsisdnHeader | Boolean | 転送先へのリクエストに
| ||||||
addEquipmentHeader | Boolean | 転送先へのリクエストに
| ||||||
addSignature | Boolean | 転送先へのリクエストに
| ||||||
psk.$credentialsId | String | addSignature が true のときに、署名に利用する事前共有鍵の認証情報 IDを指定します。認証情報 ID は、認証情報ストア に事前共有鍵を登録したときに指定しています。詳しくは、署名ヘッダと事前共有鍵を使って送信元を検証する を参照してください。 | ||||||
customHeaders | Object | 転送先へのリクエストヘッダーを追加、置換、削除できます。
リクエストヘッダーは大文字小文字が区別されません では、大文字小文字を区別して登録できますが、一般に、リクエストヘッダーは大文字小文字が区別されません。大文字小文字を同一視した結果、同じ値になるヘッダーを複数登録した場合の動作は保証されません。 |
SORACOM CLI のコマンド例:
$ soracom groups put-config --group-id {group_id} --namespace SoracomBeam \
--body '[
{
"key": "http://beam.soracom.io:8888/",
"value": {
"name": "test",
"enabled": true,
"destination": "https://beamtest.soracom.io/",
"addSubscriberHeader": true,
"addSimIdHeader": true,
"addMsisdnHeader": true,
"addEquipmentHeader": true,
"addSignature": true,
"psk": {
"$credentialsId": "CredentialsID"
},
"customHeaders": {
"X-GROUP-NAME": {
"action": "replace",
"headerKey": "X-GROUP-NAME",
"headerValue": "TEST"
}
}
}
}
]'
SORACOM CLI や API で設定を更新するときは
HTTP エントリポイントの設定を部分的に更新するときは、更新しない設定も含めて、すべての設定を漏れなく指定してください。更新する設定だけを指定すると、省略した設定は初期値に戻ります。
想定していない値を指定した場合の動作は、定義されていません。SORACOM CLI / SORACOM API で設定を変更したあとで、SORACOM ユーザーコンソールで意図通りに設定されていることを確認してください。
HTTP エントリポイントにリクエストする
リクエスト
エントリポイントに、デバイスからデータを送信します。エントリポイントは、グループ設定の → (HTTP エントリポイント) → に表示されています。
以下は、デバイスから Beam にデータを送信する場合の例です。
$ curl -v -X POST http://beam.soracom.io:8888/ \
-H "Content-Type:application/json" \
-d '{
"key": "value"
}'
Note: Unnecessary use of -X or --request, POST is already inferred.
* Trying 100.127.127.100...
* Connected to beam.soracom.io (100.127.127.100) port 8888 (#0)
> POST / HTTP/1.1
> Host: beam.soracom.io:8888
> User-Agent: curl/7.49.0
> Accept: */*
> Content-Type:application/json
> Content-Length: 15
>
* upload completely sent off: 15 out of 15 bytes
< HTTP/1.1 200 OK
< Content-Type: application/json
< Date: Wed, 21 Dec 2016 02:25:01 GMT
< Connection: close
< Transfer-Encoding: chunked
<
* Closing connection 0
デバイスからの HTTP リクエストを転送先の URL に転送する際、Beam によって以下のヘッダー操作が行われます。
Connection: closeが追加されます。- に指定したカスタムヘッダーが、追加、置換、削除されます。設定内容は、グループ設定の → → に表示されます。
レスポンス
Beam は、転送先から Beam に返された HTTP レスポンスを、そのままデバイスに転送します。