administrative REST API の使用

administrative REST API を使用すると、キューマネージャやキューなど、さまざまな IBM® MQ オブジェクトを表す URL 上で HTTP メソッドが呼び出されます。 HTTP メソッド (POST など) は、URL で表されるオブジェクトに対して実行する操作のタイプを表します。 その操作に関する詳細は、HTTP メソッドのペイロードの一部として JSON 形式で指定したり、照会パラメーター内にエンコードしたりします。 操作の実行結果に関する情報は、一般には HTTP 応答の本体として返されます。

始める前に

administrative REST APIを使用する前に、以下のことを考慮してください。
  • administrative REST APIを使用するには、mqweb サーバーで認証を行う必要があります。 HTTP 基本認証、クライアント証明書認証、またはトークン・ベースの認証を使用して、認証を行うことができます。 これらの認証方式の使用方法について詳しくは、 IBM MQ Console および REST API セキュリティーを参照してください。
  • REST API には大/小文字の区別があります。 例えば、キュー・マネージャーの名前が qmgr1 である場合に以下の URL に対して HTTP GET を実行しても、情報は表示されません。
    /ibmmq/rest/v3/admin/qmgr/QMGR1
  • IBM MQ オブジェクト名で使用できる文字のすべてが URLに直接エンコードできるわけではありません。 そのような文字を正しくエンコードするためには、適切な URL エンコード方式を使用する必要があります。
    • スラッシュ / は、%2Fとしてエンコードする必要があります。
    • % 記号は、%25としてエンコードする必要があります。
  • 一部のブラウザーの動作を考慮し、オブジェクトの名前をピリオドやスラッシュの文字のみにすることは避けてください。

本タスクについて

REST API を使用してオブジェクトに対してアクションを実行する場合、まずそのオブジェクトを表す URLを構築する必要があります。 どの URL も、要求を送信するホスト名とポートを示す接頭部で始まります。 URL の残りの部分は、特定のオブジェクト、またはオブジェクトのセットを示します。これらはリソースと呼ばれます。

リソースに対して実行する操作によって、URL に照会パラメーターが必要かどうかが規定されます。 また、使用する HTTP メソッドや、追加情報を JSON 形式で URL に送信したり URL から戻したりするかどうかも決まります。 追加情報を HTTP 要求に含める場合もあれば、HTTP 応答の一部として追加情報が返される場合もあります。

URLを構築し、 HTTPで送信するためのオプションのJSONペイロードを作成したら、 HTTPを IBM MQ に送信できます。 選択したプログラミング言語に組み込んだ HTTP 実装を使用して、要求を送信できます。 cURL などのコマンド・ライン・ツール、Web ブラウザーや Web ブラウザー・アドオンを使用して、要求を送信することもできます。

重要: 少なくとも、ステップ 1.a および 1.bを実行する必要があります。

手順

  1. URL を構成します。
    1. 以下のコマンドを入力して、接頭部 URL を特定します。
      dspmqweb status
      使用する URL には、 /ibmmq/rest/ 句が含まれます。
    2. URL パスにリソースを追加します。
      以下の IBM MQ リソースが使用可能です。
      以下の Managed File Transfer リソースが使用可能です。

      例えば、キュー・マネージャーと対話するには、/qmgr を接頭部 URL に追加して、以下の URL を作成します。

      https://localhost:9443/ibmmq/rest/v3/admin/qmgr
    3. オプション： URLに任意の追加オプションのパスセグメントを追加します

      各オブジェクト・タイプの参照情報では、オプションの各セグメントを中括弧 { } で囲むことで URL 内に指定できます。

      例えば、キュー・マネージャー名 QM1 を URL に追加して、以下の URL を作成します。

      https://localhost:9443/ibmmq/rest/v3/admin/qmgr/QM1
    4. オプション： URLにオプションのクエリパラメータを追加します

      疑問符 (?) を追加します。 変数名、等号 =、および値または値のリストURL。

      例えば、キュー・マネージャー QM1 のすべての属性を要求するには、以下の URL を作成します。

      https://localhost:9443/ibmmq/rest/v3/admin/qmgr/QM1?attributes=*
    5. オプションの照会パラメーターをさらに URL に追加します。

      アンパーサンド & を URLに追加してから、 ステップ dをもう一度実行してください。

  2. URL に対して適切な HTTP メソッドを起動します。 オプションの JSON ペイロードを指定し、認証のために適切なセキュリティー資格認定を提供します。 以下に例を示します。
    • 選択したプログラミング言語の HTTP/REST 実装を使用します。
    • REST クライアント・ブラウザー・アドオンや cURL などのツールを使用します。