[Linux]

runmqsfb ( IBM MQ Bridge to Salesforceの実行)

IBM® MQ Bridge to Salesforceを構成して実行します。

[非推奨]注： IBM MQ Bridge to Salesforce は、2022年11月22日以降のすべてのリリースで非推奨となっている（ 米国公示書簡 222-341 参照）。

構文

この図は、注 1で説明されている runmqsfb コマンドの使用法の構文を示しています。
構文図を読むビジュアル構文図をスキップ runmqsfb  -m QMgrName -t TopicString -e EventName -p PushtopicName -q ReplayStatusQueueName -n ApplicationName -i interval  -f InputFileName  -o outputConfigFile  -w WaitTime  -k killFile  -r logFile  -d DebugLevel -b  -sf ファイル -sp mode

使用上の注意

  1. runmqsfb コマンドを実行して、 IBM MQ Bridge to Salesforce を開始し、 Salesforce および IBM MQに接続することができます。 接続が確立されると、ブリッジは Salesforce によって生成されたイベントを受信し、それらを IBM MQ ネットワークにパブリッシュするか、 Salesforce プラットフォーム・イベントのイベント・メッセージを作成します。
    runmqsfb -f configFile -r logFile -m QMgrName -t TopicString -e EventName -p PushtopicName -d debugLevel -i interval -w WaitTime -k killFile
    ランタイム処理にこのコマンドを使用する場合、必須パラメーターは -fで、前に作成した構成ファイルの名前が付き、-rにログ・ファイルの名前が付きます。 他のコマンド・パラメーターもコマンド行で指定すると、それらのコマンドによって構成ファイル内の値がオーバーライドされます。 この方法により、コアなデフォルトの構成を作成しておき、キュー・マネージャー名などの細かな違いに簡単に対応することができます。
  2. runmqsfb コマンドを使用して、 Salesforce および IBM MQに接続するために必要なパラメーターを定義するために使用される構成ファイルを生成することもできます。
    構成ファイルを作成する場合、 -f パラメーターと -b パラメーターはオプションです。入力構成ファイルは、 IBM MQ Bridge to Salesforceのサンプル・ディレクトリー /opt/mqm/mqsf/sampに含まれています。
    runmqsfb [-b][-f inputConfigFile] -o outputConfigFile
    この方法でコマンドを実行すると、各構成パラメーターの値を入力するプロンプトが表示されます。 既存の値を保持するには、Enter を押します。 既存の値を削除するには、 Spaceを押してから、 Enterを押します。 詳しくは、 構成パラメーターを参照してください。
  3. [MQ 9.2.0 Jul 2020][MQ 9.2.0 Jul 2020] IBM MQ 9.2.0 より、強化されたプロテクション・パラメーターの使用法は以下の通りである：
    構成モード
    新しく入力されたパスワードは、新しい鍵で保護された出力構成ファイルに書き込まれます。 ただし、既存のパスワードの形式は変更されません。
    デフォルトの鍵が使用されている場合 (つまり、鍵ファイルが指定されていない場合) は、警告が出されます。
    環境変数を使用した batch 構成モードでのパスワードの提供は変更されません。つまり、環境変数の値はプレーン・テキストで提供されます。
    実行時モード
    パスワードが復号された時に、パスワードの形式が古いことが検出されると、警告メッセージが出され、警告の原因になったパラメーターの名前がそのメッセージに表示されます。これは、マイグレーションを促すためのメッセージです。 ただし、ブリッジはコマンドの処理を続けます。
    注: コマンド行に -sp 0 パラメーターを指定した場合は、古い形式を明示的に使用する必要があるため、警告メッセージは出されません。
    デフォルトの鍵が使用されている場合 (つまり、鍵ファイルが指定されていない場合) も、警告が出されます。
    パスワードを復号できない場合 (無効な鍵ファイルを指定した場合など) は、エラーになります。

コマンド行パラメーター

- -m QMgrName ConnFactoryName
キュー・マネージャー名または接続ファクトリー名。
-r logFile
必須。 トレース情報のログ・ファイルの場所と名前。 ログ・ファイルのパスと名前を構成ファイルまたはコマンド行で指定できます。
-t TopicString
IBM MQ トピック・ルート。
-e EventName
Salesforce プラットフォーム・イベント名 (繰り返すことができます)。 コマンド行では、複数の -e 項目 (ブリッジが listen するイベント・タイプごとに 1 つ) を指定できます。 イベント名の基本部分を指定する必要があります。 ブリッジは、Salesforce に接続するときに自動的に 「/event」または 「/topic」という接頭部を追加します。 複数の -e パラメーターはコンマで区切ります。
-p PushtopicName
Salesforce プッシュ・トピック名 (繰り返し可能)。 コマンド行では、複数の -p 項目 (ブリッジが listen するトピック・タイプごとに 1 つ) を指定できます。 トピック名の基本部分を指定する必要があります。 ブリッジは、Salesforce に接続するときに自動的に 「/event」または 「/topic」という接頭部を追加します。 複数の -p パラメーターはコンマで区切ります。
- i間隔
モニター間隔。 0 を入力するとモニターが無効になります。
-f inputConfigFile
構成ファイル。 -f パラメーターは、使用上の注意 1で説明されているように、 runmqsfb コマンドを実行して IBM MQ Bridge to Salesforceを開始する場合に必要です。 オプションとして、 -f パラメータを使用して、 使用上の注意2 で説明されているように、 既存のinputConfigFileから一部の値を再利用し、また一部の新しい値を入力することができます。 構成ファイルの作成時に -f パラメーターを指定しないと、プロンプトが出されるパラメーターの値はすべて空になります。
[MQ 9.2.0 Jul 2020]-n ApplicationInstanceName
同じキュー・マネージャーにブリッジのインスタンスが複数ある場合に、このオプションによってモニターで各インスタンスを区別できます。 この ID がアプリケーション名の一部として $SYS トピックに追加されるので、amqsrua などのモニターが別々のメタデータ・ツリーを取得できるようになります。
このオプションが空でなければ、メタデータのルート・トピックが "_" と選択値をアプリケーション名に追加します。 例えば、"2" に設定すると、以下に基づくパブリケーションになります。
$SYS/Application/runmqsfb_2/INFO/QMGR/<qmgr>/Monitor/METADATA
注: 実行中のブリッジ・インスタンス間で調整が行われないため、同じ ID を持つ 2 つのインスタンスが存在する可能性があります。 その場合は、モニタリング統計が混乱するだけです。
[MQ 9.2.0 Jul 2020]-q ReplyStatusQueueName
デフォルト値は SYSTEM.SALESFORCE.SYNCQ です。
複数のブリッジが同じキュー・マネージャーにアクセスし、 Salesforceからのインバウンド・メッセージがあるようにしたい場合は、それぞれに別個の同期キュー設定を用意する必要があります。
ブリッジ・インスタンスがどの Salesforce トピックにもサブスクライブしていない場合、同期キューはまったく使用されません。
注: 同期キューは排他的にアクセスされます。つまり、指定されたキューが別のインスタンスで既に開かれている場合、ブリッジは開始されません。
-o outputConfigFile
新しい構成ファイル。 -o パラメーターを指定してコマンドを実行すると、runmqsfb コマンドは -f ファイルから既存の構成値をロードし、各構成パラメーターの新しい値を入力するためのプロンプトを出します。
-k killFile
ブリッジを終了させるファイル。 -kパラメーターを指定してコマンドを実行し、ファイルを指定すると、そのファイルが存在する場合は、ブリッジ・プログラムが終了します。 Ctrl+C または kill コマンドを使用したくない場合に、このファイルを使用することはプログラムを停止する代替方法となります。 起動時にこのファイルが存在する場合は、ブリッジがそのファイルを削除します。 削除に失敗すると、ブリッジは異常終了しますが、ファイルの再作成をモニターします。
-d debugLevel
デバッグ・レベル、1、または 2。
1
簡潔なデバッグ情報が表示されます。
2
詳細なデバッグ情報が表示されます。
-w WaitTime
完全に開始するまで待機します。
-b
対話式のプロンプトではなく環境変数を使用して構成を実行します。 これを使用すると、プログラムで構成を設定できます。
環境変数の形式は runmqsfb_<attribute> です (<attribute> は、生成される構成ファイルの JSON フィールドです)。 以下に例を示します。
export runmqsfb_QueueManager=QM1
inputConfigurationFile (-f オプション) で指定する構成と環境変数がマージされ、outputConfigurationFile が作成されます。
この方法を使用する 1 つの方法は、 IBM MQ Bridge to Salesforceのすべてのインスタンスで使用される共通属性を含む構成ファイルを対話式に作成し、いくつかのインスタンス固有パラメーターに対してのみ環境変数をプログラマチックに適用することです。
[MQ 9.2.0 Jul 2020][MQ 9.2.0 Jul 2020]-sf ファイル
パスワード保護鍵が入っているファイル。
[MQ 9.2.0 Jul 2020][MQ 9.2.0 Jul 2020]-sp モード
パスワード保護モード。 値は次のいずれかです。
[MQ 9.2.2 Mar 2021]2
最新のパスワード保護モードを使用します。 これは、 IBM MQ 9.2.2からのデフォルト値です。
1
IBM MQ 9.2.2より前のバージョンとの互換性のために、 IBM MQ 9.2 パスワード保護モードを使用してください。 これは、 IBM MQ 9.2.2より前のバージョンのデフォルト値です。
0
IBM MQ 9.2より前のバージョンと互換性のある非推奨のパスワード保護モードを使用してください。

構成パラメーター

runmqsfb コマンドを実行して構成ファイルを作成する場合、パラメーターが 4 つのグループに分けてステップスルーされます。 パスワードは難読化され、入力中に表示されません。 生成された構成ファイルは JSON 形式です。 構成ファイルを作成するには、runmqsfb コマンドを使用する必要があります。 パスワードおよびセキュリティー証明書情報を、JSON ファイルで直接編集することはできません。
キュー・マネージャーへの接続
IBM MQ キュー・マネージャーに関連するパラメーター。
IBM MQ キュー・マネージャーまたは JNDI CF
必須。
IBM MQ 基本トピック
必須。 すべてのイベントは、 Salesforce イベント名の接頭部としてトピック・ルートを使用してパブリッシュされます。
IBM MQ チャネル
空の channel は、ローカル・バインディングを意味します。
IBM MQ CONNAME
複数インスタンス・キュー・マネージャーなどの複数の宛先を有効にするには、標準的な接続名の形式「host(port), host(port)」を使用します。 空の conname は、ローカル・バインディングを意味します。
IBM MQ パブリケーション・エラー・キュー
プラットフォーム・イベント・メッセージの作成に必要です。 誤った入力メッセージを処理するための IBM MQ エラー・キュー。 デフォルト・キュー SYSTEM.SALESFORCE.ERRORQ は、キュー・マネージャー上に必要な同期キューも作成する mqsfbSyncQ.mqsc スクリプト・コマンドを実行したときに作成されます。
IBM MQ シーシーディーティー URL
TLS 接続がキュー・マネージャーに必要な場合は、JNDI 定義または CCDT 定義を使用する必要があります。
JNDI 実装クラス名
JNDI プロバイダーのクラス名。 JNDI を使用する場合、「キュー・マネージャー名」パラメーターは、接続ファクトリー名を指します。
JNDI プロバイダー URL
JNDI サービスのエンドポイント。
IBM MQ UserId
IBM MQ パスワード
Salesforce への接続
Salesforceに関連するパラメーター。
Salesforce Userid (必須)
必須。 Salesforce アカウントの E メールにログインします。
Salesforce パスワード (必須)
必須。 Salesforce アカウントのパスワード。
Salesforce セキュリティー・トークン (必須)
必須。 Salesforce Force.com 「ホーム」 ページの 「管理」 メニューの 「セキュリティー管理」 セクションから生成できるセキュリティー・トークン。
ログイン・エンドポイント
Salesforce ログイン・エンドポイント URL、 https://login.salesforce.com。
コンシューマー・キー
Salesforce アカウントに接続済みアプリケーションとして IBM MQ Bridge to Salesforce を追加するときに生成するコンシューマー鍵。 詳しくは、 IBM MQ Bridge to Salesforceの構成 のステップ 5 を参照してください。
コンシューマーのシークレット
コンシューマー・キーと一緒に生成されたコンシューマー・シークレット。

OAuth コンシューマー・キーおよびシークレットの値はオプションですが、実動システムの場合は考慮に入れる必要があります。

TLS 接続の証明書ストア
TLS 接続の証明書ストアに関連するパラメーター。
TLS 証明書の個人用鍵ストア
必須。 Salesforce アカウント内に作成する鍵ストア。 詳しくは、 IBM MQ Bridge to Salesforceの構成のステップ 3 を参照してください。
鍵ストアのパスワード
必須。 Salesforce アカウントから鍵ストアをエクスポートするときに作成するパスワードです。
署名者証明書のトラステッド・ストア
必須。 トラステッド・ストアを追加しない場合は、TLS 証明書の個人用鍵ストアが使用されます。
トラステッド・ストアのパスワード
必須。 TLS 証明書の個人用鍵ストアを使用する場合、これは TLS 証明書の鍵ストアのパスワードです。
MQ 接続での TLS の使用
IBM MQ 接続に TLS を使用する場合は、Salesforce への接続に使用した鍵ストアと同じものを使用できます。

Salesforce 接続の場合、トラストストアが使用可能であり、少なくとも Salesforce システムを検証するための署名者証明書が含まれている必要があります。 Salesforceへの接続では、TLS 1.1 および TLS 1.2 プロトコルのみがサポートされます。 ユーザーの証明書は不要です。 トラストストア・パラメーターを指定しなかった場合は、鍵ストアが両方の役割で使用されます。 ストアは、CCDT または JNDI で IBM MQ 接続用に構成されたストアと同じにすることができます。

ブリッジ・プログラムの振る舞い
IBM MQ Bridge to Salesforceの動作に関連するパラメーター。
プッシュ・トピック名
一度に 1 つのプッシュ・トピック名を指定し、 enterを押すことによって次のパラメーターに進むことができます。
プラットフォーム・イベント名
一度に 1 つのプラットフォーム・イベント名を指定し、 enterを押して次のパラメーターに進むことができます。
モニター頻度
IBM MQ モニター頻度。
最低 1 回の配信
サービス品質。 少なくとも 1 回または最大 1 回の配信。
プラットフォーム・イベントの IBM MQ 資料のサブスクライブ
必須。 デフォルト・オプションは Nです。 Salesforce プラットフォーム・イベントのイベント・メッセージを作成するには、Y を入力してブリッジ機能を使用可能にする必要があります。
制御データとペイロードをパブリッシュ
リパブリッシュ時に、件名だけでなくメッセージ全体を送信します。
イベントの処理を開始するまでの遅延
ブリッジがイベントの処理を開始するまでの遅延。
stdout/stderr のコピー用のランタイム・ログ・ファイル
トレース情報のログ・ファイルのパスと名前。
[MQ 9.2.0 Jul 2020]ブリッジの固有 ID
デフォルト値は、ブリッジの固有 ID の指定なしです。
同じキュー・マネージャーにブリッジのインスタンスが複数ある場合に、このオプションによってモニターで各インスタンスを区別できます。 この ID がアプリケーション名の一部として $SYS トピックに追加されるので、amqsrua などのモニターが別々のメタデータ・ツリーを取得できるようになります。
このオプションが空でなければ、メタデータのルート・トピックが "_" と選択値をアプリケーション名に追加します。 例えば、"2" に設定すると、以下に基づくパブリケーションになります。
$SYS/Application/runmqsfb_2/INFO/QMGR/<qmgr>/Monitor/METADATA
注: 実行中のブリッジ・インスタンス間で調整が行われないため、同じ ID を持つ 2 つのインスタンスが存在する可能性があります。 その場合は、モニタリング統計が混乱するだけです。
[MQ 9.2.0 Jul 2020]未知の Salesforce トピックを警告として扱う
デフォルト・オプションは Nです。
サブスクライブ中にプッシュ・トピックまたはイベントが Salesforce に認識されない場合に終了するのではなく、警告を出して続行するには、このオプションを Y に設定する必要があります。
このオプションは、 Salesforce でトピックの作成が独立して行われ、すぐには使用できない場合に役立ちます。 既知のトピックに関してはブリッジを実行できるようになります。
ただし、既知でないトピックのサブスクライブを再試行するには、やはりブリッジの再始動が必要です。あるいは、再接続シーケンス (キュー・マネージャーの再始動など) を強制的に実行する必要があります。
[MQ 9.2.0 Jul 2020]再接続の最大試行回数を超えても再試行を継続する
デフォルト・オプションは Nです。
最終再試行タイマーの後も終了しないようにするには、このオプションを Y に設定する必要があります。 そうすると、最後のインターバルで再試行が永久に継続実行されます。
[MQ 9.2.0 Jul 2020] IBM MQ 、出版物は一度だけ配信？
Y か N のどちらかの値に設定できます。デフォルト値は設定されていません。 この値は、他のサービス品質属性から継承されます。
この属性は、 IBM MQ パブリケーションに対して永続サブスクリプションを作成するか、非永続サブスクリプションを作成するかを決定します。 既存のサービス品質は以下のように区別されます。
  • 非永続サブスクリプションの場合は最大 1 回
  • 永続サブスクリプションの場合は最低 1 回
フローの方向ごとに属性が別々になります。
これは、 Salesforceからのインバウンド・メッセージを最大 1 回、 ReplayIdに煩わされることなく、停止後に IBM MQ から保存済みアウトバウンド・メッセージを (少なくとも 1 回は) 送信したいという状況で役立ちます。
設定しない場合は、既存のサービス品質の値が使用されます。 構成ファイルを更新せずに (つまり、構成プロセスを実行せずに) 古いバージョンからマイグレーションすると、この状況になることに注意してください。
[MQ 9.2.0 Jul 2020]MQ 再生状況キュー
デフォルト値は SYSTEM.SALESFORCE.SYNCQ です。
複数のブリッジが同じキュー・マネージャーにアクセスし、 Salesforceからのインバウンド・メッセージがあるようにしたい場合は、それぞれに別個の同期キュー設定を用意する必要があります。
ブリッジ・インスタンスがどの Salesforce トピックにもサブスクライブしていない場合、同期キューはまったく使用されません。
注: 同期キューは排他的にアクセスされます。つまり、指定されたキューが別のインスタンスで既に開かれている場合、ブリッジは開始されません。
[MQ 9.2.0 Jul 2020]ログ・ファイルの数
デフォルト値は 3です。
出力を記録するためのログ・ファイルの循環が可能になります。 1 より大きい値を指定すると、構成したログ・ファイル名を基礎として、「.0」、「.1」といった番号がファイル・タイプの前に追加あるいは挿入されます。
デフォルト値を使用する場合は、索引を追加しないでください。
通常の stdout と stderr の処理に影響はありません。
[MQ 9.2.0 Jul 2020]各ログ・ファイルの最大サイズ
デフォルト値は 2097152 バイト (2 MB) です。
複数のログ・ファイルを構成する場合は、これがログが切り替えられるタイミングになります。
ログ・ファイルを 1 つだけ構成する場合は、このパラメーターは無視されます。
Push topic names および Platform event names は、コマンド行パラメーター -p および -e の入力と同じように、個別にまたはコンマ区切りのリストで入力できます。 Startup wait interval には、イベントの初期処理を遅らせるオプションが用意されています。 例えば、ブリッジとそれを使用する IBM MQ アプリケーションがすべてサービスとして実行される場合、それらが開始される順序を順序付けすることはできません。 したがって、アプリケーションがイベントを受信できるようになる前に、イベントがリパブリッシュされる可能性があります。 ブリッジの開始を遅らせると、アプリケーションが開始してイベントおよびプッシュ・トピックをサブスクライブするための時間を確保できます。

構成が読み取られるのは、ブリッジ処理の開始時のみです。 構成を変更した場合は、 IBM MQ サービス定義などを使用して再始動する必要があります。

例

使用上の注意 2で説明されているように、 runmqsfb を使用して構成ファイルを作成する場合、 -f パラメーターはオプションです。
runmqsfb -f inputConfigFile -o outputConfigFile
この例では、outputConfigFile が作成されます。
runmqsfb -o outputConfigFile
使用上の注意 1で説明されているように、 runmqsfb コマンドを使用して IBM MQ Bridge to Salesforceを実行する場合は、 -f パラメーターが必要です。
runmqsfb -f inputConfigFile -r logFile