REST コマンドの実行

REST コマンドは多種多様なプログラムで実行できます。このコマンドを実行するには、REST リソース上のメソッドを呼び出し、JSON 形式でパラメーターか要求を渡します。
注: REST コマンドの使用には、Web インターフェースを使用するのと同じアクセス権が必要です。アクセス権については、役割とアクセス権を参照してください。

例: curl を使った簡単な REST コマンドの実行

Linux プログラム curl を使用すれば、REST コマンドを手軽に実行できます。REST コマンドを実行するには、いずれか 1 つの REST リソースの URL を作成し、使用するメソッドを指定して、パラメーターを追加します。 例えば、次の curl コマンドは、すべてのアクティブなコンポーネントのリストを取得します。このコマンドは component リソースの GET メソッドを呼び出し、active パラメーターに値 true を渡します。
curl -k -u admin:admin 
  https://hostname:port/cli/component?active=true 
  -X GET
注: このコマンドは、1 行で入力する必要があります。ここでは見やすくするために行を分けてあります。
注: この例では、-k スイッチを使用して、非セキュアでサーバーに接続します。認証をセットアップする方法については、REST コマンドのための認証を参照してください。
hostname および port には、このサーバーのホスト名とポートを使用します。例えば、ホスト名が ucdeploy.example.org、ポートのデフォルト値が 8443 であれば、curl コマンドは次の例のようになります。
curl -k -u admin:admin 
  https://ucdeploy.example.org:8443/cli/component?active=true 
  -X GET
このコマンドの応答は、サーバー上のすべてのアクティブなコンポーネントの JSONArray リストです。この応答の例については、Get information about all components on the serverを参照してください。

REST コマンドへのパラメーターの引き渡し

多くの REST コマンドには 1 つ以上のパラメーターがあります。これらのパラメーターを渡すには、それらを URL に追加します。例えば version/getLink コマンドの GET メソッドには、アプリケーションの名前または ID、バージョンの名前または ID、リンクの名前の 3 つのパラメーターがあります。JPetStore-APP コンポーネントのリンクを取得するには、コマンドは次の例のようになります。
curl -k -u admin:admin 
  "https://fit-vm13-108.rtp.raleigh.ibm.com:8443/cli/
  version/getLink?component=JPetStore-APP
  &version=1.0
  &linkName=IBM%20web%20site"
ここでは、URL の疑問符 (?) の後に、パラメーターと値のペアがそれぞれ追加されています。各ペアはアンパーサンド (&) で区切られています。curl は Linux コマンドであり、Linux のコマンド行ではアンパーサンドに特別な意味があるため、URL はパラメーターも含めて引用符で囲まれています。
注: すべてのパラメーター値を URL エンコードする必要があります。前の例では IBM web site という値を linkName パラメーターの値として渡しています。このパラメーターを URL の一部として含めるには、スペースを URL エンコード値の %20 に置き換える必要があります。

コマンドへの JSON ストリングの引き渡し

さらに複雑なコマンドでは、JSON ストリングまたはファイルをパラメーターの代わりに、あるいはパラメーターに追加して送る必要があります。
例えば、application/create リソースの PUT メソッドはアプリケーションを作成します。このコマンドを使用するには、新しいアプリケーションの名前、説明、およびいくつかのプロパティーを指定する JSON ストリングを渡さなければなりません。このコマンドの JSON ストリングは、次のテンプレートに従っている必要があります。
{
  "description": "Description",
  "enforceCompleteSnapshots": "Specify true to require 
     an explicit version for each component",
  "name": "Application name or ID",
  "notificationScheme": "Notification scheme"
}
このテンプレートはコマンドの参照情報にリストされています。Create an application from a JSON fileを参照してください。
例えば次の JSON ストリングは、My Application という名前のアプリケーションを表しています。
{
  "description": "My new application",
  "enforceCompleteSnapshots": "false",
  "name": "My Application",
  "notificationScheme": "Default Notification Scheme"
}
この JSON ストリングを application/create リソースに渡すには、ストリングをファイルに保存するか、それをコマンド内に含めます。例えば、ストリングを newApplication.json という名前のファイルに保存する場合、コマンドは次の例のようになります。
curl -k -u admin:admin 
  https://fit-vm13-108.rtp.raleigh.ibm.com:8443/cli/application/create 
  -X PUT -d @newApplication.json
また、次の例に示すように、ストリングをコマンドに直接渡すこともできます。
curl -k -u admin:admin 
  https://fit-vm13-108.rtp.raleigh.ibm.com:8443/cli/application/create 
  -X PUT 
  -d {"description":"My new application",
      "enforceCompleteSnapshots":"false",
      "name":"My Application 67",
      "notificationScheme":"Default Notification Scheme"}

JSON ストリングの作成

コマンドに使用する JSON ストリングのテンプレートは、主に 2 つの方法で取得できます。このテンプレートは各コマンドの参照情報にリストされています。また、これに相当するコマンド行クライアントのコマンドを、-t オプション付きで実行することもできます。このオプションを付けて CLI コマンドを実行すると、JSON テンプレートが出力されます。

サーバー・インターフェースは REST API を使用するため、通常の手順でサーバーにログインし、Web アプリケーションが生成する要求をモニターすることも可能です。これらの要求は Web ブラウザーの拡張機能や外部プログラムでモニターできます。例えば、resource/create リソースの PUT メソッド用の JSON ストリングを確認するには、次の図に示すように、Web サーバー上に通常の手順でリソースを作成し、ブラウザー要求の JSON ストリングを調べます。REST コマンドの JSON ストリングは、このストリングと同じか、それと似たものになります。

サーバーが使用する JSON ストリングを Web ブラウザー拡張機能からモニターする

応答

コマンドに成功すると、ほとんどの場合は単純なストリング値か JSON ストリングのいずれかが返されます。
コマンドの結果に加えて、このコマンドは標準の HTTP 状況コードも返します。次は、REST コマンドから返される、特に一般的な状況コードのリストです。
200
コマンドは正常に実行されました。
400
  • コマンドを実行する権限がありません。
  • 必須パラメーターを指定しませんでした。
  • URL のリソース・パスが正しくありません。
404
取得しようとしているオブジェクトは存在しません。
405
HTTP メソッド名が正しくありません。
415
要求ヘッダーのコンテンツ・タイプが正しくありません。
500
サーバーでエラーが発生しました。

フィードバック