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 コンソールおよび REST API セキュリティーを参照してください。
REST API には大/小文字の区別があります。例えば、キュー・マネージャーの名前が qmgr1 である場合に以下の URL に対して HTTP GET を実行しても、情報は表示されません。
```
/ibmmq/rest/v1/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を実行する必要があります。

手順

URL を構成します。
1. 次の接頭部 URL で始めます。
  IBM MQ 9.0.4 以降の場合:
```
https://host:port/ibmmq/rest/v1/admin
```
  IBM MQ 9.0.3 またはその前 :
```
https://host:port/ibmmq/rest/v1
```
  host
  
  administrative REST API が使用可能なホスト名または IP アドレスを指定します。
  
  デフォルト値は localhostです。
  
  port
  
  administrative REST API が使用する HTTPS ポート番号を指定します。
  
  デフォルト値は 9443です。
  
  HTTP 接続を使用可能にすれば、HTTPS ではなく HTTP を使用できます。 HTTP の有効化について詳しくは、 HTTP および HTTPS ポートの構成を参照してください。
  
  接頭部 URL を判別する方法について詳しくは、 REST API URL の判別を参照してください。
2. URL パスにリソースを追加します。
  使用可能なリソースは次のとおりです。
  例えば、キュー・マネージャーと対話するには、/qmgr を接頭部 URL に追加して、以下の URL を作成します。
  IBM MQ 9.0.4 以降の場合:
```
https://localhost:9443/ibmmq/rest/v1/admin/qmgr
```
  IBM MQ 9.0.3 またはその前 :
```
https://localhost:9443/ibmmq/rest/v1/qmgr
```
3. オプション: オプションのパス・セグメントを URL に追加します。
  各オブジェクト・タイプの参照情報では、オプションの各セグメントを中括弧 { } で囲むことで URL 内に指定できます。
  
  例えば、キュー・マネージャー名 QM1 を URL に追加して、以下の URL を作成します。
  IBM MQ 9.0.4 以降の場合:
```
https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QM1
```
  IBM MQ 9.0.3 またはその前 :
```
https://localhost:9443/ibmmq/rest/v1/qmgr/QM1
```
4. オプション: オプションの照会パラメーターを URL に追加します。
  疑問符 (?) を追加します。変数名、等号 =、および URL に対する値または値のリスト。
  
  例えば、キュー・マネージャー QM1 のすべての属性を要求するには、以下の URL を作成します。
  IBM MQ 9.0.4 以降の場合:
```
https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QM1?attributes=*
```
  IBM MQ 9.0.3 またはその前 :
```
https://localhost:9443/ibmmq/rest/v1/qmgr/QM1?attributes=*
```
5. オプションの照会パラメーターをさらに URL に追加します。
  
  アンパーサンド & を URLに追加してから、ステップ dをもう一度実行してください。
URL に対して適切な HTTP メソッドを起動します。オプションの JSON ペイロードを指定し、認証のために適切なセキュリティー資格認定を提供します。以下に例を示します。
- 選択したプログラミング言語の HTTP/REST 実装を使用します。
- REST クライアント・ブラウザー・アドオンや cURL などのツールを使用します。