Soracom

Users

ドキュメント

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

デバイスから HTTP リクエストを受け付け、HTTP もしくは HTTPS で転送先へリクエストを転送します。転送先としてホスト (プロトコル、ホスト名、ポート番号) を設定して、すべてのパスに転送できます。デバイスの状況に応じて、転送先のパスを変更するユースケースに向いています。

Web サイトエントリポイントは、Unified Endpoint を経由して利用できません

パスをあらかじめ登録する必要がありません

HTTP エントリポイントとは異なり、パスをあらかじめ登録する必要がありません。たとえば [ホスト]example.com を指定すると、http://beam.soracom.io:18080/path/to/target に送信されたデータは https://example.com/path/to/target に転送されます。

Web サイトエントリポイントを設定する

Web サイトエントリポイントで設定できる項目は以下のとおりです。

項目説明
[設定名]

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

同じ名前の設定を追加できます
[設定名] は、エントリポイントの一意のキーとして扱われません。ほかのエントリポイントと同じ名前を設定できます。
[有効]この設定の有効 / 無効を切り替えます。
[転送先]

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

項目説明
[プロトコル]転送する際のプロトコルを選択します。
[ホスト名]転送先の FQDN (Fully Qualified Domain Name) を入力します。例: beamtest.soracom.io
[ポート番号]転送先のポート番号を入力します。例: 1234
パスをあらかじめ登録する必要がありません

HTTP エントリポイントとは異なり、パスをあらかじめ登録する必要がありません。たとえば [ホスト]example.com を指定すると、http://beam.soracom.io:18080/path/to/target に送信されたデータは https://example.com/path/to/target に転送されます。

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

SORACOM CLI / SORACOM API の場合

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

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

keyvalue の型value
http://beam.soracom.io:18080ObjectWeb サイトエントリポイントの Object を参照してください。

SORACOM CLI のコマンド例:

$ soracom groups put-config --group-id {group_id} --namespace SoracomBeam \
--body '[
  {
    "key": "http://beam.soracom.io:18080",
    "value": {
      "name": "test",
      "destination": "https://beamtest.soracom.io",
      "enabled": true,
      "addSubscriberHeader": true,
      "customHeaders": {
        "X-GROUP-NAME": {
          "action": "replace",
          "headerKey": "X-GROUP-NAME",
          "headerValue": "TEST"
        }
      },
      "addSignature": true,
      "psk": "topsecret"
    }
  }
]'
SORACOM CLI や API で設定を更新するときは

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

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

Web サイトエントリポイントの Object

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

keyvalue の型value
nameString

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

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

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

  • true: 有効
  • false: 無効
destinationStringエントリポイントで受け付けたリクエストの転送先 (URL) を入力します。例: https://beamtest.soracom.io/
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.$credentialsIdString認証情報ストアに登録した Google Service Account (JSON) または 秘密鍵 (PEM) の認証情報 ID を指定します。
    algorithmString

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

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

    keyvalue の型value
    serviceStringlambda または s3 を指定します。
    regionStringAWS Lambda 関数または Amazon S3 バケットのリージョンを指定します。例: ap-northeast-1
    unsignedPayloadBooleanAmazon S3 にファイルサイズが 1 MiB を超えるファイルをアップロードする可能性がある場合は、true を指定します。
    credentials.$credentialsIdString認証情報ストアに登録した AWS IAM ロール認証情報 の認証情報 ID を指定します。
  • addAuthorizationHeader.typebearer または basic の場合:

    keyvalue の型value
    credentials.$credentialsIdString

Web サイトエントリポイント URL

http://beam.soracom.io:18080

設定上のポートは 18080 となっており、 http://beam.soracom.io:18080 でも通信を行えますが、 http://beam.soracom.io (80 番ポート) に対して通信を行ってもよい状態となっております。

Web サイトエントリポイントにリクエストする

Web サイトエントリポイントの挙動は HTTP エントリポイントと同じです。詳しくは、HTTP エントリポイントにリクエストする を参照してください。

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

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

エントリポイントポート番号
HTTP エントリポイント8888
Web サイトエントリポイント18080 または 80