第3章 REST API クイックスタートの例

本章では、基本的な Red Hat Enterprise Virtualization 環境をセットアップし、仮想マシンを作成する REST API の機能の例を示します。
以下の例には、通常の標準的な前提条件に加えて、次の項目が必要となります。
  • Red Hat Enterprise Virtualization Hypervisor をインストールした、ネットワーク接続/設定済みのホスト。
  • 仮想マシンにインストールする任意のオペレーティングシステムを格納した ISO ファイル。本章では、インストール ISO の例に Red Hat Enterprise Linux Server 6 を使用しています。
  • 選択したオペレーティングシステム ISO ファイルを更新する Red Hat Enterprise Virtualization の engine-iso-uploader ツール。
以下の例では、cURL を使用して、クライアントアプリケーションによる REST 要求について具体的に説明します。HTTP 要求に対応したアプリケーションはいずれも cURL の代わりに使用できる点に注意してください。

重要

以下の例では、記載内容をわかりやすくするために、HTTP 要求ヘッダーの Host:Authorization: のフィールドを省略していますが、これらのフィールドは必須フィールドであり、ご使用の Red Hat Enterprise Virtualization Manager インストール固有のデータを記載する必要があります。

重要

cURL の例にはすべて、認証情報 (USER:PASS) と証明書の場所 (CERT) 用のプレースホルダーが含まれています。cURL を使用して実行する要求がすべて証明および認証の要件を満たしていることを確認してください。

注記

Red Hat Enterprise Virtualization Manager は、各リソースの id 属性用にグローバル一意識別子 (GUID) を生成します。以下の例に記載の識別子コードは、ご使用の Red Hat Enterprise Virtualization 環境の識別子コードとは異なる場合があります。

3.1. 例: API エントリーポイントへのアクセス

以下の要求は、API の主要エントリーポイントの表現を取得します。

例3.1 API エントリーポイントへのアクセス

要求:

GET /api HTTP/1.1
Accept: application/xml

cURL コマンド:

# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \
    --cacert [CERT] https://[RHEVM Host]:443/api

結果:

HTTP/1.1 200 OK
Content-Type: application/xml

<api>
    <link rel="capabilities" href="/api/capabilities"/>
    <link rel="clusters" href="/api/clusters"/>
    <link rel="clusters/search" href="/api/clusters?search={query}"/>
    <link rel="datacenters" href="/api/datacenters"/>
    <link rel="datacenters/search" href="/api/datacenters?search={query}"/>
    <link rel="events" href="/api/events"/>
    <link rel="events/search" href="/api/events?search={query}"/>
    <link rel="hosts" href="/api/hosts"/>
    <link rel="hosts/search" href="/api/hosts?search={query}"/>
    <link rel="networks" href="/api/networks"/>
    <link rel="roles" href="/api/roles"/>
    <link rel="storagedomains" href="/api/storagedomains"/>
    <link rel="storagedomains/search" href="/api/storagedomains?search={query}"/>
    <link rel="tags" href="/api/tags"/>
    <link rel="templates" href="/api/templates"/>
    <link rel="templates/search" href="/api/templates?search={query}"/>
    <link rel="users" href="/api/users"/>
    <link rel="groups" href="/api/groups"/>
    <link rel="domains" href="/api/domains"/>
    <link rel="vmpools" href="/api/vmpools"/>
    <link rel="vmpools/search" href="/api/vmpools?search={query}"/>
    <link rel="vms" href="/api/vms"/>
    <link rel="vms/search" href="/api/vms?search={query}"/>
    <special_objects>
        <link rel="templates/blank"
          href="/api/templates/00000000-0000-0000-0000-000000000000"/>
        <link rel="tags/root"
          href="/api/tags/00000000-0000-0000-0000-000000000000"/>
    </special_objects>
    <product_info>
        <name>Red Hat Enterprise Virtualization</name>
        <vendor>Red Hat</vendor>
        <version revision="0" build="0" minor="0" major="3"/>
    </product_info>
    <summary>
        <vms>
            <total>5</total>
            <active>0</active>
        </vms>
        <hosts>
            <total>1</total>
            <active>1</active>
        </hosts>
        <users>
            <total>1</total>
            <active>1</active>
        </users>
        <storage_domains>
            <total>2</total>
            <active>2</active>
        </storage_domains>
    </summary>
</api>

エントリーポイントは、仮想化環境内のコレクションへのリンクをユーザーに提供します。各コレクションリンクの rel= 属性は、各リンクの参照ポイントを提供します。この例の次のステップでは、rel="datacenter" リンクで入手可能な datacenter コレクションについて考察します。
エントリーポイントには product_infospecial_objectssummary などのその他のデータも含まれます。このようなデータについては別の章で説明しています。