付録A cURL を用いた API の使用法

本付録では REST の要求を cURL に適応させる方法について説明しています。 cURL は、 HTTP など各種のプロトコル間でデータを転送するコマンドラインツールです。 Linux、 Windows、 Mac OS、 Solaris などいろいろなプラットフォームに対応しています。 ほとんどの Linux のディストリビューションには cURL がパッケージとして同梱されています。
cURL をインストールする
Red Hat Enterprise Linux ユーザーの場合は次のようにターミナルコマンドを使って cURL をインストールします。
yum install curl
他のプラットフォームの場合には、 cURL の Web サイトでインストール方法を確認してください (http://curl.haxx.se/)。
cURL を使用する
cURL ではコマンドラインインターフェースを使って HTTP サーバーに要求を送信します。 要求の統合には次のコマンド構文が必要です。
Usage: curl [options] uri
uri により目的の HTTP アドレスが参照され要求が送信されます。 これは API エントリポイントパス内の Red Hat Enterprise Virtualization Manager ホスト上の場所になります (/api)。

cURL のオプション

-X COMMAND, --request COMMAND
使用する要求のコマンドです。 REST API では、 GETPOSTPUTDELETE のいずれかを使用します。
例: -X GET
-H LINE, --header LINE
要求に含ませる HTTP ヘッダーです。 ヘッダーが複数必要な場合は複数のヘッダーオプションを使用します。
例: -H "Accept: application/xml" -H "Content-Type: application/xml"
-u USERNAME:PASSWORD, --user USERNAME:PASSWORD
Red Hat Enterprise Virtualization ユーザーのユーザー名とパスワードです。 この属性は Authorization: ヘッダーの代替として動作するので便利です。
例: -u admin@internal:p@55w0rd!
--cacert CERTIFICATE
REST API との SSL 通信用証明書ファイルの場所です。 証明書ファイルはクライアントマシン上にローカルに保存されます。 SSL を回避する場合は -k 属性を使用します。 証明書の取得方法については 2章認証とセキュリティ を参照してください。
例: --cacert ~/Certificates/rhevm.cer
-d BODY, --data BODY
送信する要求のボディです。 POSTPUTDELETE などの要求で使用します。 要求内にボディが存在する場合は Content-Type: application/xml を必ず指定してください。
例: -d "<cdrom><file id='rhel-server-6.0-x86_64-dvd.iso'/></cdrom>"
実例
次の例では REST の要求を cURL コマンド構文に適応させる方法を示します。

例A.1 GET 要求

次の GET 要求で vms コレクション内の仮想マシンを一覧表示します。 GET 要求はボディを含まない点に注意してください。
GET /api/vms HTTP/1.1
Accept: application/xml
メソッド (GET)、 ヘッダー (Accept: application/xml)、 URI (https://[RHEVM-Host]:8443/api/vms) を次の cURL コマンドに適応させます。
$ curl -X GET -H "Accept: application/xml" -u [USER:PASS] --cacert [CERT] https://[RHEVM-Host]:8443/api/vms
vms コレクションの XML 表現が表示されます。

例A.2 POST 要求

次の POST 要求で vms コレクション内に仮想マシンを作成します。 POST 要求にはボディが必要な点に注意してください。
POST /api/vms HTTP/1.1
Accept: application/xml
Content-type: application/xml

<vm>
  <name>vm1</name>
  <cluster>
    <name>default</name>
  </cluster>
  <template>
    <name>Blank</name>
  </template>
  <memory>536870912</memory> 
  <os>
    <boot dev="hd"/>
  </os>
</vm>
メソッド (POST)、 ヘッダー (Accept: application/xmlContent-type: application/xml)、 URI (https://[RHEVM-Host]:8443/api/vms)、 要求のボディを次の cURL コマンドに適応させます。
$ curl -X POST -H "Accept: application/xml" -H "Content-type: application/xml" -u [USER:PASS] --cacert [CERT] -d "<vm><name>vm1</name><cluster><name>default</name></cluster><template><name>Blank</name></template><memory>536870912</memory><os><boot dev='hd'/></os></vm>" https://[RHEVM-Host]:8443/api/vms
REST API により新しい仮想マシンが作成され、 そのリソースの XML 表現が表示されます。

例A.3 PUT 要求

次の PUT 要求で仮想マシンリソースのメモリが更新されます。 PUT 要求にはボディが必要な点に注意してください。
PUT /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<vm>
    <memory>1073741824</memory>
</vm>
メソッド (PUT)、 ヘッダー (Accept: application/xmlContent-type: application/xml)、 URI (https://[RHEVM-Host]:8443/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399)、 要求ボディを次の cURL コマンドに適応させます。
$ curl -X PUT -H "Accept: application/xml" -H "Content-type: application/xml" -u [USER:PASS] --cacert [CERT] -d "<vm><memory>1073741824</memory></vm>" https://[RHEVM-Host]:8443//api/vms/082c794b-771f-452f-83c9-b2b5a19c039
REST API により新しいメモリー設定で仮想マシンが更新されます。

例A.4 DELETE 要求

次の DELETE 要求で仮想マシンのリソースが削除されます。
DELETE /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
メソッド (DELETE) と URI (https://[RHEVM-Host]:8443/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399) を次の cURL コマンドに適応させます。
$ curl -X DELETE -u [USER:PASS] --cacert [CERT] https://[RHEVM-Host]:8443//api/vms/082c794b-771f-452f-83c9-b2b5a19c039
REST API により仮想マシンが削除されます。 DELETE 要求の結果が空のため、 Accept: application/xml ヘッダーはオプションになります。

例A.5 ボディがある DELETE 要求

次の DELETE 要求ではオプションのボディで指示されているように仮想マシンのリソースが強制削除されます。
DELETE /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
  <force>true</force>
</action>
メソッド (DELETE)、 ヘッダー (Accept: application/xmlContent-type: application/xml)、 URI (https://[RHEVM-Host]:8443/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399)、 要求のボディを次の cURL コマンドに適応させます。
$ curl -X DELETE -H "Accept: application/xml" -H "Content-type: application/xml" -u [USER:PASS] --cacert [CERT] -d "<action><force>true</force></action>" https://[RHEVM-Host]:8443//api/vms/082c794b-771f-452f-83c9-b2b5a19c039
REST API により仮想マシンが強制削除されます。

cURL ライブラリ (libcurl)
標準のコマンドラインツールに加え、 cURL にはプログラミング言語統合用のライブラリとなる libcurl も搭載されています。 対応プログラミング言語および統合方法については、 libcurl Web サイト (http://curl.haxx.se/libcurl/) を参照してください。