Soracom

Users

ドキュメント
Home ドキュメント SORACOM Beam エントリポイントリファレンス

HTTP エントリポイント

HTTP エントリポイント (http://beam.soracom.io:8888/) に、デバイスから送信された HTTP リクエストを、HTTP もしくは HTTPS で指定の URL に転送します。1 つの URL に対してリクエストを転送するユースケースに向いています。

HTTP エントリポイントには、転送先として 1 つの URL (プロトコル、ホスト名、ポート番号、パス) を設定します。たとえば、転送元の [パス]/from/ を指定し、転送先としてプロトコル HTTPS、ホスト名 example.com、ポート番号 443、パス /to/ を指定した場合、デバイスからの送信先に応じて、Beam からの転送先が以下のように決定されます。

デバイスからの送信先Beam からの転送先
http://beam.soracom.io:8888/from/https://example.com:443/to/
http://beam.soracom.io:8888/path1/(転送されない)
http://beam.soracom.io:8888/path1/to1/(転送されない)
http://beam.soracom.io:8888/(任意のパス)(転送されない)

同じホストの複数のパスを転送する場合は、Web サイトエントリポイント を利用すると便利です。

HTTP エントリポイントではクエリパラメータは転送されません

デバイスでクエリパラメータを付与して HTTP エントリポイントにアクセスしても、Beam でクエリパラメータは削除されます。そのため、デバイスで付与したクエリパラメータは、転送されません。なお、Web サイトエントリポイント ではクエリパラメータも転送されます。

デバイスから HTTP エントリポイントにデータを送信するときは、HTTPS プロトコルを利用できません。

1 つの SIM グループに対して複数の HTTP エントリポイントを追加できます

HTTP エントリポイントは、[エントリポイント][パス] (SORACOM CLI / API の場合は、最上位のキー。例: http://beam.soracom.io:8888/path/) で識別されます。

HTTP エントリポイントと Web サイトエントリポイント

HTTP エントリポイントと Web サイトエントリポイントの違いは以下のとおりです。

HTTP エントリポイントWeb サイトエントリポイント
向いているユースケース1 つの URL に対してリクエストを転送するユースケース。デバイスの状況に応じて転送先のパスを変更するユースケース。
転送元[パス] を設定できる-
転送先[プロトコル][ホスト名][ポート番号][パス] を設定できる[プロトコル][ホスト名][ポート番号] を設定できる
クエリパラメータ転送できない転送できる
エントリポイントで転送できる URL の数1 件複数

HTTP エントリポイントを設定する

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

項目説明
[設定名]

HTTP エントリポイントは、1 つのグループに複数設定できます。設定を区別するために名前を入力します。

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

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

[有効]この設定の有効 / 無効を切り替えます。
[エントリポイント]

デバイスからの HTTP リクエストを受け付けるエントリポイントを設定します。

項目説明
[パス]転送元のパスを入力します。たとえば、/from/ を入力した場合は、デバイスから http://beam.soracom.io:8888/from/ に送信したリクエストが、[転送先] に転送されます。この設定が、HTTP エントリポイントを識別するキーとして扱われます。
1 つの SIM グループに対して [パス] が同一の HTTP エントリポイントは複数追加できません

登録済みの HTTP エントリポイントの [パス] と同一の HTTP エントリポイントを追加すると、登録済みの HTTP エントリポイントの設定が上書きされます。

[転送先]

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

項目説明
[プロトコル]転送する際のプロトコルを選択します。
[ホスト名]転送先の FQDN (Fully Qualified Domain Name) を入力します。例: beamtest.soracom.io
[ポート番号]転送先のポート番号を入力します。例: 8080
[パス]転送先のパスを入力します。例: /to/
[ヘッダ操作]転送先へのリクエストに追加するヘッダーを設定します。詳しくは、[ヘッダ操作] を参照してください。
multi credentials per group 機能

Beam では multi credentials per group 機能を使用できます。 [事前共有鍵] で選択する認証情報の [認証情報 ID] の任意の場所に #{imsi} もしくは #{imei} のプレースホルダーを入れることで、接続デバイスに応じた 認証情報を使い分けることができます。

詳しくは、multi credentials per group 機能を利用して AWS IoT に接続する を参照してください。

[ヘッダ操作]

転送先へのリクエストに追加するヘッダーを設定します。

項目説明
[IMSI ヘッダ]スイッチをオンにすると、x-soracom-imsi: ${IMSI} ヘッダーが追加されます。${IMSI} には、IoT SIM の IMSI が挿入されます。
[SIM ID ヘッダ]スイッチをオンにすると、x-soracom-sim-id: ${SIM_ID} ヘッダーが追加されます。${SIM_ID} には、IoT SIM の SIM ID が挿入されます。
[MSISDN ヘッダ]スイッチをオンにすると、x-soracom-msisdn: ${MSISDN} ヘッダーが追加されます。${MSISDN} には、IoT SIM の MSISDN が挿入されます。
[IMEI ヘッダ] (*1)スイッチをオンにすると、x-soracom-imei: ${IMEI} ヘッダーが追加されます。${IMEI} には、デバイスの IMEI が挿入されます。
[署名 ヘッダ 付与]

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

  • [事前共有鍵]: [署名 ヘッダ 付与] がオンのときに、署名に利用する事前共有鍵を、認証情報ストア に登録した事前共有鍵から選択します

[IMSI ヘッダ][SIM ID ヘッダ][MSISDN ヘッダ][IMEI ヘッダ] のいずれか 1 つがオンのときに設定できます。

[カスタムヘッダ]

転送先へのリクエストヘッダーを追加、置換、削除できます。[+追加] をクリックして、[アクション][ヘッダ名] および [値] を設定してください。[アクション] では、以下のいずれかを選択します。

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

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

[AUTHORIZATION ヘッダ] (*2)

デバイスから送信されたデータを Beam で転送する際、Authorization ヘッダーを追加できます。

タイプ説明
Bearer JWTRFC 6750 で定義されている Bearer スキームを利用するための Authorization: Bearer {token} ヘッダーを追加します。なお、{token} には、Google Service Account (JSON) または 秘密鍵 (PEM) を利用して発行された JSON Web Token (JWT) が挿入されます。
AWS Signature V4AWS 署名バージョン 4 を追加します。AWS 署名バージョン 4 は、AWS 認証情報 または AWS IAM ロール認証情報 を利用して生成されます。
BearerRFC 6750 で定義されている Bearer スキームを利用するための Authorization: Bearer {token} ヘッダーを追加します。なお、{token} には、API トークン認証情報 または 事前共有鍵 が挿入されます。
BasicRFC 7617 で定義されている Basic 認証を利用するための Authorization: Basic {credentials} ヘッダーを追加します。なお、{credentials} には、ユーザ名・パスワード認証情報 で設定したユーザー名とパスワードから生成された Base64 文字列が挿入されます。

SORACOM CLI / SORACOM API の場合

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

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

keyvalue の型value
http://beam.soracom.io:8888/{path} (*1)ObjectHTTP エントリポイントの Object を参照してください。
  • (*1) {path} には、転送元のパスを入力します。たとえば、{path}from/ を入力した場合は、デバイスから http://beam.soracom.io:8888/from/ に送信したリクエストが、destination で指定した URL に転送されます。

SORACOM CLI のコマンド例:

$ soracom groups put-config --group-id {group_id} --namespace SoracomBeam \
--body '[
  {
    "key": "http://beam.soracom.io:8888/{path}",
    "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"
        }
      },
      "addAuthorizationHeader": {
        "enabled": false
      }
    }
  }
]'
転送元の設定が同じ HTTP エントリポイントは複数登録できません

http://beam.soracom.io:8888/{path} が、HTTP エントリポイントの一意のキーとして扱われます。複数の HTTP エントリポイントを作成する設定にしても、この値がほかの HTTP エントリポイントと同じ値になると、いずれか 1 つの HTTP エントリポイントだけが登録されます。

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

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

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

HTTP エントリポイントの Object

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

keyvalue の型value
nameString

Beam には同じ種類のエントリポイントを複数設定できます。設定を識別するために名前を入力します。

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

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: ヘッダーを追加しません。
psk.$credentialsIdStringaddSignaturetrue のときに、署名に利用する事前共有鍵の認証情報 IDを指定します。認証情報 ID は、認証情報ストア に事前共有鍵を登録したときに指定しています。詳しくは、署名ヘッダと事前共有鍵を使って送信元を検証する を参照してください。
customHeadersObject

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

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

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

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

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

addAuthorizationHeaderObject

転送先へのリクエストに Authorization ヘッダーを追加できます。

keyvalue の型value
enabledBoolean

転送先へのリクエストに Authorization ヘッダーを追加するかを設定します。

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

Authorization ヘッダーのタイプを指定します。

  • bearer_jwt: RFC 6750 で定義されている Bearer スキームを利用するための Authorization: Bearer {token} ヘッダーを追加します。なお、{token} には、Google Service Account (JSON) または 秘密鍵 (PEM) を利用して発行された JSON Web Token (JWT) が挿入されます。
  • aws_sig_v4: AWS 署名バージョン 4 を追加します。AWS 署名バージョン 4 は、AWS 認証情報 または AWS IAM ロール認証情報 を利用して生成されます。
  • bearer: RFC 6750 で定義されている Bearer スキームを利用するための Authorization: Bearer {token} ヘッダーを追加します。なお、{token} には、API トークン認証情報 または 事前共有鍵 が挿入されます。
  • basic: RFC 7617 で定義されている Basic 認証を利用するための Authorization: Basic {token} ヘッダーを追加します。なお、{token} には、ユーザ名・パスワード認証情報 で設定したユーザー名とパスワードから生成された Base64 文字列が挿入されます。
configObjecttype に応じて設定内容が異なります。詳しくは、addAuthorizationHeader.config の Object を参照してください。
addAuthorizationHeader.config の Object

HTTP エントリポイントの Object のうち、addAuthorizationHeader.config の設定内容は、addAuthorizationHeader.type の設定によって異なります。

  • addAuthorizationHeader.typebearer_jwt の場合:

    keyvalue の型value
    jwtClaimsObject

    JSON Web Token の生成に使う情報を指定します。

    例:

    {
      "iss": "soracom-beam@long-stack-371107.iam.gserviceaccount.com",
      "sub": "soracom-beam@long-stack-371107.iam.gserviceaccount.com",
      "aud": "https://pubsub.googleapis.com/google.pubsub.v1.Publisher"
    }
    

    iat および exp は、デバイスが Beam にアクセスしたときに、自動的に生成されます。

    credentials.$credentialsId *String認証情報ストアに登録した Google Service Account (JSON) または 秘密鍵 (PEM) の認証情報 ID を指定します。
    algorithm *String

    署名アルゴリズムを指定します。

    • RS256
    • ES256
    • RS512
    • ES512
  • addAuthorizationHeader.typeaws_sig_v4 の場合:

    keyvalue の型value
    service *String

    lambda または sagemaker を指定します。

    HTTP エントリポイントでは、geos3 は指定できません。

    region *StringAWS のリージョンを指定します。例: ap-northeast-1
    credentials.$credentialsId *String認証情報ストアに登録した AWS IAM ロール認証情報 の認証情報 ID を指定します。
  • addAuthorizationHeader.typebearer の場合:

    keyvalue の型value
    credentials.$credentialsId *String認証情報ストアに登録した API トークン認証情報 または 事前共有鍵 の認証情報 ID を指定します。
  • addAuthorizationHeader.typebasic の場合:

    keyvalue の型value
    credentials.$credentialsId *String認証情報ストアに登録した ユーザ名・パスワード認証情報 の認証情報 ID を指定します。

HTTP エントリポイントにリクエストする

ポート番号に注意してください

HTTP エントリポイントと Web サイトエントリポイントは、ポート番号が異なります。

エントリポイントポート番号
HTTP エントリポイント8888
Web サイトエントリポイント18080 または 80
Web サイトエントリポイント (WebSocket 対応版)10080

HTTP エントリポイントに、デバイスからデータを送信します。HTTP エントリポイントは、グループ設定の [SORACOM Beam 設定] → HTTP エントリポイントの [エントリポイント] に表示されています。

以下は、デバイスから HTTP エントリポイント (http://beam.soracom.io:8888/) にデータを送信する場合の例です。

$ 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
ヘッダー操作について

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

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

Beam は、転送先から Beam に返された HTTP レスポンスを、そのままデバイスに転送します。