![[MQ 9.2.0 Jul 2020]](ng920.gif)
POST - JSON 形式のコマンド
このリソースを指定した HTTP POST メソッドを使用して、キュー・マネージャーに対して管理コマンドを直接実行依頼できます。 これらの管理コマンドは、プレーン・テキストの MQSC コマンドか、JSON 形式のコマンドとして、要求の本体に格納された状態で送信されます。
administrative REST API を使用して MQSC コマンドを送信するには、プレーン・テキストの MQSC コマンドを使用するか、JSON 形式のコマンドを使用します。
- プレーン・テキストの MQSC コマンドを使用する場合は、MQSC コマンドを、コマンド行に入力するのと同じように、要求の本体の中に指定します。 以下に例を示します。
応答は、プレーン・テキストの形式で返されます。{ "type": "runCommand", "parameters": { "command": "DEFINE CHANNEL(NEWSVRCONN) CHLTYPE(SVRCONN)" } } - JSON 形式のコマンドを使用する場合は、要求の本体の中に JSON 形式で MQSC コマンドを指定します。 以下に例を示します。
応答は JSON 形式で返されます。{ "type": "runCommandJSON", "command": "define", "qualifier": "channel", "name": "NEWSVRCONN", "parameters": { "chltype": "svrconn" } }
プレーン・テキストの MQSC コマンドの使用について詳しくは、 POST-プレーン・テキストの MQSC コマンドを参照してください。
この REST API コマンドHTTP と併用して、任意のMQSCコマンドを実行することができます。 ただし、要求本体で JSON 形式のコマンドを使用する場合には、次の MQSC コマンドはサポートされません。
- DISPLAY ARCHIVE
- DISPLAY CHINIT
- DISPLAY GROUP
- DISPLAY LOG
- DISPLAY SECURITY
- DISPLAY SYSTEM
- DISPLAY THREAD
- DISPLAY TRACE
- DISPLAY USAGE
AIX®, Linux®, and Windowsでは、この REST API コマンドは、 Multiplatforms での MQCMD_ESCAPE (Escape) PCF コマンドに似ています。
z/OS®では、この REST API コマンドは、コマンドをコマンド・サーバーに直接実行依頼するのと似ています。
- メッセージが要求キューに書き込まれます。 これらのメッセージでは、
MsgTypeがMQMT_REQUESTに設定され、FormatがMQFMT_STRINGまたはMQFMT_NONEに設定され、ペイロードとして MQSC コマンドのテキストが設定されています。 - キュー・マネージャーで実行されているコマンド・サーバーがメッセージを読み取り、それらを検証し、有効なコマンドをコマンド・プロセッサーに渡します。
- コマンド・プロセッサーはコマンドを実行し、コマンドに対する応答を、着信メッセージに指定されている応答先キューにメッセージとして書き込みます。
リソース URL
https://host:port/ibmmq/rest/v2/admin/action/qmgr/qmgrName/mqsc
- qmgrName
- コマンドを実行するキュー・マネージャーの名前を指定します。
HTTP 接続を使用可能にすれば、HTTPS ではなく HTTP を使用できます。 HTTP を有効にする方法の詳細については HTTP および HTTPS ポートの設定」 を参照してください。
要求ヘッダー
要求で以下のヘッダーを送信する必要があります。
- Content-Type
- このヘッダーは、値
application/jsonの後にオプションで;charset=UTF-8を付けて送信する必要があります。 - ibm-mq-rest-csrf-token
- このヘッダーを設定する必要がありますが、その値はブランクを含む任意のものにすることができます。
- 認証
- 基本認証を使用している場合、このヘッダーを送信する必要があります。 詳細については 、「 REST API 」の HTTP ベーシック認証の使用」 を参照してください。
要求で以下のヘッダーをオプションで送信できます。
- ibm-mq-rest-gateway-qmgr
- このヘッダーは、ゲートウェイ・キュー・マネージャーとして使用されるキュー・マネージャーを指定します。 ゲートウェイ・キュー・マネージャーは、リモート・キュー・マネージャーへの接続に使用されます。 詳しくは、 REST APIを使用したリモート管理を参照してください。
要求本体の形式
要求本体は、JSON 形式で UTF-8 エンコードにする必要があります。 要求本体内で、属性を定義し、名前付きの JSON オブジェクトを作成して追加の属性を指定します。 指定しなかった属性には、デフォルト値が使用されます。
次の属性を要求本体に含めることができます。
- タイプ
- 必須。
- コマンド
- 必須。
- qualifier
- ストリング。
- 名前
- オプション。
- responseParameters
- オプション。
- パラメーター
- オプション。
セキュリティー要件
呼び出し元は mqweb サーバーに対して認証されている必要があり、1 つ以上のMQWebAdmin、MQWebAdminRO、またはMQWebUserロールのメンバーでなければなりません。 administrative REST APIのセキュリティーについて詳しくは、 IBM MQ コンソールおよび REST API セキュリティーを参照してください。
トークン・ベースのセキュリティーを使用する場合は、要求と一緒に、ユーザーの認証に使用する LTPA トークンを Cookie として渡す必要があります。 トークン・ベースの認証について詳しくは、 REST API でのトークン・ベースの認証の使用を参照してください。
呼び出し元のセキュリティー・プリンシパルに、指定したキュー・マネージャーに対して MQSC コマンドを実行するための権限が付与されていなければなりません。
![[AIX、Linux、Windows]](../common/../com.ibm.mq.ref.adm.doc/ngalw.gif)
AIX, Linux, and Windowsでは、 setmqaut コマンドを使用して、 IBM MQ リソースを使用する権限をセキュリティー・プリンシパルに付与できます。 詳しくは、 setmqaut (権限の付与または取り消し)を参照してください。
![[z/OS]](../common/../com.ibm.mq.ref.adm.doc/ngzos.gif)
z/OSの場合は、 z/OSでのセキュリティーのセットアップを参照してください。
応答状況コード
- 200
- 指定したコマンドは、処理のためにキュー・マネージャーに正常に渡されました。
- 400
- 無効なデータが指定されました。
- 401
- 認証されませんでした。
- 403
- 許可がありません。
- 404
- キュー・マネージャーがありません。
- 500
- IBM MQからのサーバーの問題またはエラー・コード。
- 503
- キュー・マネージャーが実行されていません。
応答ヘッダー
応答では以下のヘッダーが返されます。
- Content-Type
- このヘッダーは、値
application/json;charset=utf-8と一緒に返されます。 - ibm-mq-rest-gateway-qmgr
- このヘッダーは、リソース URL 内にリモート・キュー・マネージャーが指定されている場合に返されます。 このヘッダーの値は、ゲートウェイ・キュー・マネージャーとして使用されるキュー・マネージャーの名前になります。
応答本体の形式
エラーが発生した場合、応答本体にエラー・メッセージが入ります。 詳しくは、 REST API エラー処理を参照してください。
応答本体の形式は、一貫性のある JSON スキーマを使用して標準化されています。 ただし、コンテンツはプラットフォームに応じて異なり、MQSC コマンド実行の基盤となるメカニズムを反映します。
応答本体の JSON 構造は次のとおりです。
{
"commandResponse" : [
{
"completionCode" : number,
"reasonCode" : number,
"message" : [
"string",
...
]
},
...
]
"overallCompletionCode" : number,
"overAllReasonCode" : number
}
応答のフィールドの意味は次のとおりです。
- commandResponse
- コマンド実行からの個々の応答を表す JSON オブジェクトからなる JSON 配列。
![[z/OS]](ngzos.gif)
sourceQmgr- 受信された応答の送信元キュー・マネージャー。
- overallCompletionCode
- 操作全体に関連付けられている完了コード。
- overallReasonCode
- 操作全体に関連付けられている理由コード。
例
- ローカル・キュー
Q1を定義します。 HTTP POST メソッドで以下の URL を使用します。次の JSON ペイロードが送信されます。https://localhost:9443/ibmmq/rest/v2/admin/action/qmgr/QM1/mqsc
REST コマンドが正常に完了し、応答コード 200 が返されます。 返される応答本体の JSON は次のとおりです。{ "type": "runCommandJSON", "command": "define", "qualifier": "qlocal", "name": "Q1", "parameters": { "share": "yes", "trigdata": "lowercasetrigdata", "trigdpth": 7, "usage": "normal" } }![[AIX、Linux、Windows]](ngalw.gif)
オン AIX, Linux, and Windows:{ "commandResponse": [ { "completionCode": 0, "message": ["AMQ8006I: IBM MQ queue created."], "reasonCode": 0 } ], "overallCompletionCode": 0, "overallReasonCode": 0 }オン z/OS:{ "commandResponse": [], "overallCompletionCode": 0, "overallReasonCode": 0 } - キューを表示します。 HTTP POST メソッドで以下の URL を使用します。次の JSON ペイロードが送信されます。
https://localhost:9443/ibmmq/rest/v2/admin/action/qmgr/QM1/mqsc
REST コマンドが正常に完了し、応答コード 200 が返されます。 返される応答本体の JSON は次のとおりです。{ "type": "runCommandJSON", "command": "display", "qualifier": "qlocal", "name": "Q1" }{ "commandResponse": [ { "completionCode": 0, "parameters": { "acctq": "QMGR", "altdate": "2019-06-06", "alttime": "12.01.21", "boqname": "", "bothresh": 0, "clchname": "", "clusnl": "", "cluster": "xxxx", "clwlprty": 0, "clwlrank": 0, "clwluseq": "QMGR", ... "share": "YES", ... "trigtype": "FIRST", "type": "QLOCAL", "usage": "NORMAL" }, "reasonCode": 0 } ], "overallCompletionCode": 0, "overallReasonCode": 0 } - キュー・マネージャー上のすべてのキューを表示し、
alttimeパラメーターとtrigdpthパラメーターを返すように要求します。 HTTP POST メソッドで以下の URL を使用します。次の JSON ペイロードが送信されます。https://localhost:9443/ibmmq/rest/v2/admin/action/qmgr/QM1/mqsc
REST コマンドが正常に完了し、応答コード 200 が返されます。 返される応答本体の JSON は次のとおりです。{ "type": "runCommandJSON", "command": "display", "qualifier": "qlocal", "name": "*", "responseParameters": ["alttime","trigdpth"] }{ "commandResponse": [ { "completionCode": 0, "parameters": { "alttime": "13.36.31", "queue": "Q0”, "trigdpth": 1, "type": "QLOCAL" }, "reasonCode": 0 }, { "completionCode": 0, "parameters": { "alttime": "13.37.59", "queue": "Q1", "trigdpth": 7, "type": "QLOCAL" }, "reasonCode": 0 } ], "overallCompletionCode": 0, "overallReasonCode": 0 } - z/OSの場合、キュー共有グループの QMGR1 と QMGR2 の両方に定義されているローカル・キュー
Q0を表示します。 HTTP POST メソッドで以下の URL を使用します。次の JSON ペイロードが送信されます。https://localhost:9443/ibmmq/rest/v2/admin/action/qmgr/QMGR1/mqsc
REST コマンドが正常に完了し、応答コード 200 が返されます。 返される応答本体の JSON は次のとおりです。{ "type": "runCommandJSON", "command": "display", "qualifier": "qlocal", "name": "q0", "parameters": { "cmdscope": "*" } }{ "commandResponse": [ { "completionCode": 0, "parameters": { "acctq": "QMGR", "altdate": "2019-01-21", "alttime": "10.23.43", "boqname": "", "bothresh": 0, "cfstruct": "", "clchname": "", "clusnl": "", "cluster": "", "clwlprty": 0, "clwlrank": 0, "clwluseq": "QMGR", ... "trigtype": "FIRST", "type": "QLOCAL", "usage": "NORMAL" }, "reasonCode": 4, "sourceQmgr": "QMGR1" }, { "completionCode": 0, "parameters": { "acctq": "QMGR", "altdate": "2019-03-19", "alttime": "13.05.02", "boqname": "", "bothresh": 0, "cfstruct": "", "clchname": "", "clusnl": "", "cluster": "", "clwlprty": 0, "clwlrank": 0, ... "trigtype": "FIRST", "type": "QLOCAL", "usage": "NORMAL" }, "reasonCode": 4, "sourceQmgr": "QMGR2" } ], "overallCompletionCode": 0, "overallReasonCode": 0 } - where パラメーターの使用例:
返される応答本体の JSON は次のとおりです。{ "type": "runCommandJSON", "command": "DISPLAY", "qualifier": "CHSTATUS", "name": "*", "parameters": { "where": "CHLTYPE EQ RCVR" } }{ "commandResponse": [{ "completionCode": 0, "reasonCode": 0, "parameters": { "current": "YES", "stopreq": "NO", "substate": "RECEIVE", "rqmname": "MQBB", "chldisp": "PRIVATE", "chltype": "RCVR", "conname": "192.168.0.1", "chstatus": "MQAA.TO.MQBB", "status": "RUNNING" } }], "overallReasonCode": 0, "overallCompletionCode": 0 }