Soracom

Users

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

MQTT エントリポイント

MQTT エントリポイント URL (beam.soracom.io:1883) で MQTT で受けた通信を、MQTT または MQTTS で転送を行う設定です。

MQTT の Publish、Subscribe を、転送先となる MQTT ブローカーに転送します。MQTT ブローカーからのメッセージの Publish もデバイスに対して転送します。

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

リクエストの最大メッセージサイズは、Beam の MQTT エントリポイントでは制限されていません。

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

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

項目説明
[設定名]

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

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

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

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

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

項目説明
[種別]

転送先のサービスを選択します。

[プロトコル]転送する際の送信プロトコル (MQTT または MQTTS) を選択します。[種別] で「Standard」を選択した場合のみ選択できます。
[ホスト名]転送先の FQDN (Fully Qualified Domain Name) を入力します。例: asia-east1-mqtt.clearblade.com[種別] で「PubNub IoT Platform」を選択した場合は入力できません。
[ポート番号]転送先のポート番号を入力します。例: 8883[種別] で「Standard」または「Google Cloud IoT Core」を選択した場合のみ入力できます。
[認証情報]MQTT ブローカーに送信するクライアント証明書を設定します。[種別] で選択したサービスによって、認証情報は異なります。詳しくは、[認証情報] を参照してください。
[オプション]転送先へのリクエストに追加するヘッダーを設定します。詳しくは、[オプション] を参照してください。

[認証情報]

転送先へのリクエストで利用する認証情報を設定します。

項目説明
[ユーザ名] (*1)転送先 MQTT ブローカーへ送信するユーザー名を入力します。(*2)
[パスワード] (*1)転送先 MQTT ブローカーへ送信するパスワードを入力します。(*2)
[パススルー] (*1)

スイッチをオンにすると、デバイスから送信されるユーザー名 / パスワードを転送先 MQTT ブローカーにそのまま送信します。

スイッチをオフにすると、[ユーザ名] に指定したユーザー名、[パスワード] に指定したパスワードを転送先 MQTT ブローカーに送信します。

[証明書] (*1)スイッチをオンにすると、[認証情報] で選択したクライアント証明書 (X.509 証明書) を転送先 MQTT ブローカーに送信します。
[認証情報]

転送先 MQTT ブローカーに送信する認証情報を選択します。[種別] で選択したサービスによって、必要な認証情報は異なります。

  • (*1) [種別] で「Standard」を選択した場合のみ設定できます。
  • (*2) ユーザー名、パスワードに #{imsi}#{imei} が含まれている場合、接続した端末の IMSI、IMEI が自動的に置換されます。

[オプション]

項目説明
[IMSI 付与]スイッチをオンにすると、トピックに {トピック名}/{IMSI} という形式で IMSI が付与されます。[IMSI 付与] は、Publish に対応します。
[トピック名にセッション情報を利用する]

トピック名に存在するプレースホルダー ({{imsi}} / {{simId}} / {{imei}}) を各セッション情報で置換します。当プレースホルダーは Publish、Subscribe の両方に対応します。

  • {{imsi}} : IMSI で置き換えます。
  • {{simId}} : SIM ID で置き換えます。
  • {{imei}} : 通信モジュールの IMEI で置き換えます。

IMEI は接続するキャリアやプランによっては取得できない場合があり、その場合は {{imei}}unknown-imei で置き換えます。

[プラットフォームバージョン]「201912」と「201509 (サポート終了予定)」が選択できます。プラットフォームバージョンについては、プラットフォームバージョン 201509201912 の違い を参照してください。

[種別] で選択した転送先によっては、項目が表示されない場合があります。

SORACOM CLI / SORACOM API の場合

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

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

keyvalue の型value
mqtt://beam.soracom.io:1883ObjectMQTT エントリポイントの Object を参照してください。

SORACOM CLI のコマンド例:

$ soracom groups put-config --group-id {group_id} --namespace SoracomBeam \
--body '[
  {
    "key": "mqtt://beam.soracom.io:1883",
    "value": {
      "name": "test",
      "enabled": true,
      "destination": "mqtts://mqtt.example.com/topicname",
      "username": "USERNAME",
      "password": "PASSWORD",
      "useClientCredentials": false,
      "useClientCert": true,
      "clientCerts": {
        "default": {
          "$credentialsId": "x509"
        }
      },
      "addSubscriberHeader": true,
      "replaceTopic": true,
      "version": "201912"
    }
  }
]'
SORACOM CLI や API で設定を更新するときは

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

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

MQTT エントリポイントの Object

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

keyvalue の型value
nameString

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

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

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

enabledBoolean

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

  • true: 有効
  • false: 無効
destinationStringエントリポイントで受け付けたリクエストの転送先 (URL) を入力します。例: mqtts://mqtt.example.com/topicname
username (*1)String転送先 MQTT ブローカーへ送信するユーザー名を入力します。(*2)
password (*1)String転送先 MQTT ブローカーへ送信するパスワードを入力します。(*2)
useClientCredentials (*1)String

デバイスから送信されるユーザー名 / パスワードを転送先 MQTT ブローカーにそのまま送信するかを設定します。

  • true: デバイスから送信されるユーザー名 / パスワードを転送先 MQTT ブローカーにそのまま送信する。
  • false: username に指定したユーザー名、password に指定したパスワードを転送先 MQTT ブローカーに送信する。
useClientCert (*1)Boolean

認証情報として、クライアント証明書 (X.509 証明書) を転送先 MQTT ブローカーに送信するかを設定します。

  • true: クライアント証明書を転送先 MQTT ブローカーに送信する。
  • false: クライアント証明書を転送先 MQTT ブローカーに送信しない。
clientCerts.default.$credentialsId (*1)StringuseClientCerttrue のときに、転送先 MQTT ブローカーに送信するクライアント証明書 (X.509 証明書) の認証情報 IDを指定します。認証情報 ID は、認証情報ストア に X.509 証明書を登録したときに指定しています。
usePubnumBoolean

転送先のサービスとして「PubNub IoT Platform」を選択するかを設定します。

  • true: PubNub IoT Platform を選択する
  • false: PubNub IoT Platform 以外を選択する
pubnubCredential.$credentialsId (*3)StringusePubnumtrue のときに、PubNub IoT Platform の MQTT ブローカーに送信するクライアント証明書 (PubNub 認証情報) の認証情報 IDを指定します。
useGoogleIoTBoolean

転送先のサービスとして「Google Cloud IoT Core」を選択するかを設定します。

  • true: Google Cloud IoT Core を選択する
  • false: Google Cloud IoT Core 以外を選択する
googleIoTCredential.$credentialsId (*4)StringuseGoogleIoTtrue のときに、Google Cloud IoT Core 互換サービスの MQTT ブローカーに送信するクライアント証明書 (Google Cloud IoT Core 認証情報) の認証情報 IDを指定します。
useAzureIoTBoolean

転送先のサービスとして「Azure IoT Hub」を選択するかを設定します。

  • true: Azure IoT Hub を選択する
  • false: Azure IoT Hub 以外を選択する
azureIoTCredential.$credentialsId (*5)StringuseAzureIoTtrue のときに、Azure IoT Hub の MQTT ブローカーに送信するクライアント証明書の認証情報 IDを指定します。認証情報 ID は、認証情報ストア に Azure IoT 認証情報を登録したときに指定しています。詳しくは、AWS IoT と接続する を参照してください。
addSubscriberHeader (*1) (*3) (*4) (*5)Boolean

トピックに {トピック名}/{IMSI} という形式で IoT SIM の IMSI を付与するかを設定します。この機能は、Publish に対応します。

  • true: IMSI を追加します。
  • false: IMSI を追加しません。
replaceTopic (*1) (*3) (*4) (*5)Boolean

トピック名に存在するプレースホルダー ({{imsi}} / {{simId}} / {{imei}}) を各セッション情報で置換します。当プレースホルダーは Publish、Subscribe の両方に対応します。

  • {{imsi}} : IMSI で置き換えます。
  • {{simId}} : SIM ID で置き換えます。
  • {{imei}} : 通信モジュールの IMEI で置き換えます。

IMEI は接続するキャリアやプランによっては取得できない場合があり、その場合は {{imei}}unknown-imei で置き換えます。

versionString201912 または 201509 (サポート終了予定) を指定します。プラットフォームバージョンについては、プラットフォームバージョン 201509201912 の違い を参照してください。
  • (*1) 以下のプロパティがすべて false の場合に有効です。
    • usePubnub
    • useGoogleIoT
    • useAzureIoT
  • (*2) ユーザー名、パスワードに #{imsi}#{imei} が含まれている場合、接続した端末の IMSI、IMEI が自動的に置換されます。
  • (*3) usePubNubtrue の場合に有効です。
  • (*4) useGoogleIoTtrue の場合に有効です。
  • (*5) useAzureIoTtrue の場合に有効です。

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

Publish

ここでは、オープンソースとして提供されている MQTT メッセージブローカーである mosquitto-clients の mosquitto_pub を使用して Publish します。

接続先の MQTT ブローカーによってはコネクションが切断されたりエラーになったりする場合があります

接続先の MQTT ブローカーがサポートしている QoS を指定してください。サポートしていない QoS を指定した場合、コネクションが切断されたりエラーになったりする場合があります。たとえば、Azure IoT Hub にデータを送信する場合は、-q 1 (QoS 1) を指定します。

mosquitto-clients のインストール

mosquitto-clients は、サイト からダウンロードおよびインストールしてください。

なお、Raspberry Pi の場合は、以下のコマンドでインストールできます。

$ sudo apt install mosquitto-clients

デバイスから Publish します。

$ mosquitto_pub -d -h beam.soracom.io -p 1883 -t test -m "Hello, World"
Client mosqpub/82534-MBP sending CONNECT
Client mosqpub/82534-MBP received CONNACK
Client mosqpub/82534-MBP sending PUBLISH (d0, q0, r0, m1, 'test', ... (12 bytes))
Client mosqpub/82534-MBP sending DISCONNECT

転送先の MQTT ブローカーで、以下のように表示されます。

1482290763: New connection from 52.198.xxx.xxx on port 8080.
1482290763: New client connected from 52.198.xxx.xxx as mosqpub/82534-MBP (c1, k60).
1482290763: Sending CONNACK to mosqpub/82534-MBP (0, 0)
1482290767: Received PUBLISH from mosqpub/82534-MBP (d0, q0, r0, m0, 'test/4401031********', ... (12 bytes))
1482290767: Received DISCONNECT from mosqpub/82534-MBP
1482290767: Client mosqpub/82534-MBP disconnected.

ここでは [IMSI 付与] をオンにしているため、トピックに IMSI が付与されています (test/4401031********)。

Subscribe

mosquitto-clients の mosquitto_sub を使ってデバイスから Beam へ Subscribe し、転送先の MQTT ブローカーからメッセージを Publish してみます。

  1. デバイスで Subscribe します。

    $ mosquitto_sub -d -h beam.soracom.io -p 1883 -t test
    
    Client mosqsub/82586-MBP sending CONNECT
    Client mosqsub/82586-MBP received CONNACK
    Client mosqsub/82586-MBP sending SUBSCRIBE (Mid: 1, Topic: test, QoS: 0)
    Client mosqsub/82586-MBP received SUBACK
    Subscribed (mid: 1): 0
    

    Subscribe を受ける転送先 MQTT ブローカーで、以下のように表示されます。

    1482291094: New connection from 52.198.xxx.xxx on port 8080.
    1482291094: New client connected from 52.198.xxx.xxx as mosqsub/82586-MBP (c1, k60).
    1482291094: Sending CONNACK to mosqsub/82586-MBP (0, 0)
    1482291094: Received SUBSCRIBE from mosqsub/82586-MBP
    1482291094:     test (QoS 0)
    1482291094: mosqsub/82586-MBP 0 test
    1482291094: Sending SUBACK to mosqsub/82586-MBP
    
  2. MQTT ブローカーに別のクライアントからメッセージを Publish します。

    1482291169: New connection from 127.0.0.1 on port 8080.
    1482291169: New client connected from 127.0.0.1 as mosqpub/3516-ip-10-0-0- (c1, k60).
    1482291169: Sending CONNACK to mosqpub/3516-ip-10-0-0- (0, 0)
    1482291169: Received PUBLISH from mosqpub/3516-ip-10-0-0- (d0, q0, r0, m0, 'test', ... (12 bytes))
    1482291169: Sending PUBLISH to mosqsub/82586-MBP (d0, q0, r0, m0, 'test', ... (12 bytes))
    1482291169: Received DISCONNECT from mosqpub/3516-ip-10-0-0-
    1482291169: Client mosqpub/3516-ip-10-0-0- disconnected.
    

    Publish されたメッセージを Beam 経由でデバイスが受け取り、以下のように表示されます。

    Client mosqsub/82586-MBP received PUBLISH (d0, q0, r0, m0, 'test', ... (12 bytes))
    Hello, World
    

MQTT エントリポイントに関する制限事項と注意事項

MQTT エントリポイントには以下の制限事項や注意事項があります。

  • MQTT 接続時 (connect コマンド) のオプションについて
    • connect の keepalive に設定できる値は、0 または 5 以上 から 1200 以下の整数です。それ以外の値を設定した場合、connect リクエストに NOT_AUTHORIZED コードを返却します。
    • Beam では session の状態の保存を行っていませんが、MQTT ブローカーには clean session のパラメータをそのまま転送します。
  • Beam は、無通信時 (一定時間通信がない場合) に TCP コネクションを切断します。
    • keepalive に 0 以外の値が設定されているとき、Beam は keepalive の 1.5 倍の時間、通信がない場合に TCP コネクションを切断します。
    • keepalive が 0 に設定されている場合、Beam は 30 分間通信がない場合に TCP コネクションを切断します。
  • MQTT 接続中にセルラー通信のセッションが切断された場合、Beam との TCP セッションは不通になりますが、Beam ではそれを検知できません。
    • 端末側で常時接続するユースケースの場合は、keepalive を有効化するか、クライアント側でセルラー通信のセッション断を検知して再接続する仕組みの導入を強く推奨します。

      keepalive に 5 以上 1200 以下の整数を指定すると、keepalive が有効となり、セッション断を検知できます。keepalive を有効化するとクライアントが指定された間隔で PINGREQ パケットを送出します。

    • セルラー通信の切断は、SORACOM ユーザーコンソールまたは SORACOM API で IoT SIM のセッションを再確立する と再現できます。

  • Beam 設定で種別を「Azure IoT Hub」または「Google Cloud IoT Core」 にして接続する場合は、トークンの有効期限が 1 時間で失効します。Azure を利用する場合は X.509 証明書で認証した接続 の利用も検討してください。

プラットフォームバージョン 201509201912 の違い

プラットフォームバージョン 201509 は 2022 年 8 月 1 日にサポートを終了しました

引き続き、プラットフォームバージョン 201509 は利用できますが、SORACOM サポート対象外です。また、201509 バージョンは今後廃止され、動作が 201912 バージョンに統一される予定です (廃止日未定)。 MQTT エントリポイントのプラットフォームバージョン変更時の注意事項 を確認いただき、すみやかに移行してください。

MQTT エントリポイントの動作はプラットフォームバージョンによって異なります。 プラットフォームバージョンには 201912 (推奨) と 201509 (サポート終了予定) の 2 つがあります。

プラットフォームバージョン 201912 は、接続先ブローカーとの互換性・信頼性が向上しています。新たに MQTT エントリポイントを利用する場合は、201912 を選択してください。

移行について

詳しくは、MQTT エントリポイントのプラットフォームバージョン変更時の注意事項 を参照してください。

課金対象メッセージ

デバイスと Beam、Beam と MQTT ブローカーの間でメッセージをやり取りしたときに、それぞれを個別に 1 リクエストとカウントし、リクエスト数に応じて課金されます (*1)。たとえば、クライアントからメッセージを 1 通 PUBLISH した場合、2 リクエストとカウントされます。

項目プラットフォームバージョン 201509プラットフォームバージョン 201912
デバイス → BeamSUBSCRIBE, UNSUBSCRIBE, PUBLISH, PINGREQSUBSCRIBE, UNSUBSCRIBE, PUBLISH
Beam → MQTT ブローカーSUBSCRIBE, UNSUBSCRIBE, PUBLISH, PINGREQSUBSCRIBE, UNSUBSCRIBE, PUBLISH
Beam ← MQTT ブローカーPUBLISHPUBLISH
デバイス ← BeamPUBLISHPUBLISH

MQTT のバージョンおよび仕様に関する違い

項目プラットフォームバージョン 201509プラットフォームバージョン 201912
Beam → MQTT ブローカーに接続する際の MQTT バージョンMQTT バージョン 3.1.1 で接続します。デバイスが指定する MQTT バージョンで接続します。MQTT バージョン 5 には対応していません。
QoSQoS 0 のみ利用できます。(*1)接続先 MQTT ブローカーが対応する QoS 値を利用できます。たとえば、ブローカー側が QoS 1 に対応している場合は、QoS 1 を利用できます。
will利用できません。接続先 MQTT ブローカーが対応していれば、利用できます。
  • (*1) QoS 1、2 を指定してメッセージを送ることはできますが、メッセージの到達性を保証しません。

転送先に接続するプロトコル

項目プラットフォームバージョン 201509プラットフォームバージョン 201912
証明書 (keycert) を利用している場合常に MQTTS プロトコルで転送先に接続されます。転送先に指定されたプロトコルで接続します。MQTT バージョン 5 には対応していません。
証明書 (keycert) を利用していない場合転送先に指定されたプロトコルで接続します。転送先に指定されたプロトコルで接続します。MQTT バージョン 5 には対応していません。

MQTT エントリポイントのプラットフォームバージョン変更時の注意事項

プラットフォームバージョンを 201509 から 201912 へ変更する際に、各バージョンの仕様の違いに依存した問題が発生する可能性があります。運用中のデバイスでプラットフォームバージョンを変更する際には、テスト用のデバイスなどを利用して事前に動作確認をしてください。

たとえば、以下のようなケースで、201912 へ変更後に接続エラーが発生することが報告されています。

クライアントが接続時に MQTT バージョンの指定をしていない場合 (特に Azure IoT Hub、Google IoT Core を利用している場合)

MQTT バージョンを確認してください

MQTT ブローカーによっては、MQTT バージョン 3.1 で接続すると、接続エラーが発生します。デバイスが MQTT バージョン 3.1.1 で接続していることを確認してください。MQTT バージョンの変更方法については MQTT クライアントやデバイスの取扱説明書を参照してください。

プラットフォームバージョン 201509 においては、クライアントが指定している MQTT バージョンに関わらず、ソラコムプラットフォームが MQTT バージョン 3.1.1 を使用して MQTT ブローカーに接続していました。

プラットフォームバージョン 201912 においては、アーキテクチャの変更によって、常にクライアントが指定する MQTT バージョンを使用して接続するように変更されました。そのため、クライアントが MQTT ブローカーが対応していない MQTT バージョン (3.1) を指定して接続した場合、接続エラーが発生します。また、デフォルトの MQTT バージョンが 3.1 になっている MQTT クライアントやデバイスが複数確認されています。

Azure IoT Hub または Google IoT Core を利用している場合

Azure IoT Hub または Google IoT Core は MQTT バージョン 3.1 をサポートしていないことを確認しています。 これらを利用している場合は、クライアントが接続時に MQTT バージョン 3.1.1 を指定していることを事前に必ず確認してください。

なお、MQTT バージョンの変更方法については MQTT クライアントやデバイスの取扱説明書を参照してください。

転送先に接続するプロトコルに MQTT を指定した状態で証明書を利用していた場合

プラットフォームバージョン 201509 においては、証明書 (keycert) を利用している場合、転送先に接続するプロトコルの設定に関わらず MQTTS プロトコルで転送先に接続されます。

プラットフォームバージョン 201912 においては、証明書の利用有無に関わらず、転送先に指定されたプロトコルで接続します。

転送先のプロトコルが正しく設定されているかを事前に確認ください。