Red Hat Summit Red Hat Summitサポートコンソール開発者トライアルの開始お問い合わせ

7.3. コレクション

7.3.1. コレクション
リンクのコピー

コレクションは、同じタイプのリソースのセットです。API は、最上位コレクションとサブコレクションの両方を提供します。最上位コレクションの例としては、環境内の全仮想化ホストを含む hosts コレクションがあげられます。また、サブコレクションの例としては、ホストリソースにアタッチされた全ネットワークインターフェースカードのリソースを含む host.nics コレクションがあげられます。

7.3.2. コレクション内の全リソースの一覧
リンクのコピー

エントリーポイントから取得したコレクション URI に対して GET 要求を実行して、コレクション内のリソースの一覧を取得します。
Accept HTTP ヘッダーを追加して、応答形式の MIME タイプを定義します。 
GET /api/[collection] HTTP/1.1
Accept: [MIME type]
Copy to Clipboard Toggle word wrap

7.3.3. 拡張リソースのサブコレクションの一覧
リンクのコピー

Accept ヘッダーに detail パラメーターを記載すると、API はコレクションの表現を拡張してサブコレクションを追加します。 
GET /api/collection HTTP/1.1
Accept: application/xml; detail=subcollection
Copy to Clipboard Toggle word wrap
複数のサブコレクションを追加するには 2 つの方法があります。第 1 の方法では、以下に示したように、複数の detail パラメーターを区切って記述します。 
GET /api/collection HTTP/1.1
Accept: application/xml; detail=subcollection1; detail=subcollection2
Copy to Clipboard Toggle word wrap
第 2 の方法では、以下に示したように、単一の detail パラメーターで、サブコレクションを + 演算子で区切ります。 
GET /api/collection HTTP/1.1
Accept: application/xml; detail=subcollection1+subcollection2+subcollection3
Copy to Clipboard Toggle word wrap
API は、以下のメインコレクションで、拡張サブコレクションをサポートしています。
Expand
表7.4 拡張サブコレクションを使用するコレクション
コレクション拡張サブコレクションのサポート
hostsstatistics
vmsstatistics、nics、disks

例7.1 vms コレクション内の拡張された statistics/nics/disks サブコレクションの要求

GET /api/vms HTTP/1.1
Accept: application/xml; detail=statistics+nics+disks
Copy to Clipboard Toggle word wrap

7.3.4. クエリーを使用したコレクションの検索
リンクのコピー

"collection/search" リンクに対する GET 要求は、そのコレクションの検索クエリーとなります。API は、検索クエリーの制約を満たすコレクション内のリソースのみを返します。 
GET /api/collection?search={query} HTTP/1.1
Accept: application/xml

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

<collection>
    <resource id="resource_id" href="/api/collection/resource_id">
        ...
    </resource>
    ...
</collection>
Copy to Clipboard Toggle word wrap

7.3.5. 検索結果の最大表示件数のパラメーター
リンクのコピー

結果一覧のサイズを制限するには、max URL パラメーターを使用します。Red Hat Enterprise Virtualization 3.4 より前のバージョンでは、結果のデフォルトサイズは SearchResultsLimit パラメーターで制限されていました。Red Hat Enterprise Virtualization 3.4 以降のバージョンでは、SearchResultsLimit パラメーターは REST API に効果がないため、max パラメーターを指定せずに API 検索クエリーを実行すると、すべての値が返されてしまいます。API 検索クエリーによる UI のパフォーマンス低下を防ぐためには、max パラメーターを指定することを推奨します。 
GET /api/collection;max=1 HTTP/1.1
Accept: application/xml

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

<collection>
    <resource id="resource_id" href="/api/collection/resource_id">
        <name>Resource-Name</name>
        <description>A description of the resource</description>
        ...
    </resource>
</collection>
Copy to Clipboard Toggle word wrap

7.3.6. 大文字と小文字の区別
リンクのコピー

デフォルトでは、検索クエリーはすべて大文字と小文字が区別されます。大文字/小文字の区別を切り替えるためのブール値オプションは、URL 構文で提供されます。

例7.2 大文字/小文字を区別しない検索クエリー

GET /api/collection;case-sensitive=false?search={query} HTTP/1.1
Accept: application/xml
Copy to Clipboard Toggle word wrap

7.3.7. クエリーの構文
リンクのコピー

API は、URI テンプレートを使用して GET 要求による検索 query を実行します。 
GET /api/collection?search={query} HTTP/1.1
Accept: application/xml
Copy to Clipboard Toggle word wrap
query テンプレートの値は、API が collection に送る検索クエリーを参照します。この query は、Red Hat Enterprise Virtualization 検索クエリー言語と同じ形式を使用します。
(criteria) [sortby (element) asc|desc]
sortby 句はオプションです。結果をソートする場合にのみ必要となります。
Expand
表7.5 検索クエリーの例
コレクション条件結果
hostsvms.status=upup 状態の仮想マシンを実行中の全ホストの一覧を表示します。
vmsdomain=qa.company.com指定したドメインで稼働中の全仮想マシンの一覧を表示します。
vmsusers.name=maryユーザー名が mary のユーザーに属する全仮想マシンの一覧を表示します。
eventsseverity>normal sortby time重大度が normal を超えるすべての events の一覧を表示し、time 要素値でソートします。
eventsseverity>normal sortby time desc重大度が normal を超えるすべての events の一覧を表示し、time 要素値の降順にソートします。
API は、query テンプレートを URL エンコードして、演算子や空白など予約文字を変換する必要があります。

例7.3 URL エンコードされた検索クエリー

GET /api/vms?search=name%3Dvm1 HTTP/1.1
Accept: application/xml
Copy to Clipboard Toggle word wrap

7.3.8. ワイルドカード
リンクのコピー

検索クエリーで、値の一部の代わりに、アスタリスクをワイルドカードとして使用します。

例7.4 ワイルドカードを使用した name=vm* の検索クエリー

GET /api/vms?search=name%3Dvm* HTTP/1.1
Accept: application/xml
Copy to Clipboard Toggle word wrap
このクエリーは、vm1、vm2、vma、vm-webserver など vm で始まる仮想マシン名をすべて表示します。

例7.5 ワイルドカードを使用した name=v*1 の検索クエリー

GET /api/vms?search=name%3Dv*1 HTTP/1.1
Accept: application/xml
Copy to Clipboard Toggle word wrap
このクエリーは、vm1、vr1、virtualmachine1 など v で始まり 1 で終わる仮想マシン名をすべて表示します。

7.3.9. ページネーション
リンクのコピー

Red Hat Enterprise Virtualization 環境の中には、リソースのコレクションが大量に含まれている場合がありますが、API は 1 つのコレクションに対する 1 回の検索クエリーに設定されているデフォルト数のリソースのみを表示します。デフォルト数以上のリソースを表示するには、page コマンドを検索クエリーに追加すると、API はコレクションを複数のページに分割します。

例7.6 リソースのページネーション

以下の例では、1 つのコレクション内の複数のリソースをページネーションします。URL エンコードされた要求は次のようになります。 
GET /api/collection?search=page%201 HTTP/1.1
Accept: application/xml
Copy to Clipboard Toggle word wrap
次の結果ページを表示させる場合は page 値を増やします。 
GET /api/collection?search=page%202 HTTP/1.1
Accept: application/xml
Copy to Clipboard Toggle word wrap
以下の例のように、page コマンドは、検索クエリー内で他のコマンドと併用することができます。 
GET /api/collection?search=sortby%20element%20asc%20page%202 HTTP/1.1
Accept: application/xml
Copy to Clipboard Toggle word wrap
このクエリーにより、コレクション一覧内の第 2 ページが選択した要素の順に表示されます。

重要

REST API はステートレスです。要求はすべて 1 つずつ独立しているため、別の要求との間で状態を保持することはできません。そのため、要求と要求の間でステータスが変更されると、ページの結果に整合性がなくなります。
たとえば、仮想マシンの一覧から特定のページを要求し、次のページを要求する前にステータスが変更された場合は、出力される結果でエントリーが足りないか、重複エントリーが含まれている可能性があります。

7.3.10. コレクション内のリソース作成
リンクのコピー

新規リソースの表現を含むコレクション URI に対して POST 要求を実行して、新規リソースを作成します。
POST 要求には、Content-Type ヘッダーが必要です。このヘッダーは、要求の一部として、本文コンテンツ内の表現の MIME タイプを API に通知します。
Accept HTTP ヘッダーを追加して、応答形式の MIME タイプを定義します。
各リソースタイプには、それぞれ固有の必須プロパティーがあります。これらのプロパティーは、新規リソース作成時にクライアントから提供されます。詳細については、各リソースタイプの説明を参照してください。
必須プロパティーが存在しない場合には、作成が失敗し、表現に不足している要素が示されます。 
POST /api/[collection] HTTP/1.1
Accept: [MIME type]
Content-Type: [MIME type]

[body]
Copy to Clipboard Toggle word wrap

7.3.11. 非同期要求
リンクのコピー

Expect: 201-created ヘッダーでユーザーによって要求が無効化されない限り、API は非同期の POST 要求を行います。
たとえば、仮想マシン、ディスク、スナップショット、テンプレートなど特定のリソースは非同期に作成されます。非同期のリソース作成の要求を実行すると 202 Accepted のステータスになります。202 Accepted のリソースの初期ドキュメント構造には creation_status 要素と作成ステータス更新用リンクも含まれます。以下が例となります。 
POST /api/collection HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<resource>
    <name>Resource-Name</name>
</resource>

HTTP/1.1 202 Accepted
Content-Type: application/xml

<resource id="resource_id" href="/api/collection/resource_id">
    <name>Resource-Name</name>
    <creation_status>
        <state>pending</state>
    </creation status>
    <link rel="creation_status" 
      href="/api/collection/resource_id/creation_status/creation_status_id"/>
      ...
</resource>
Copy to Clipboard Toggle word wrap
creation_status リンクに対して GET 要求を実行すると、作成ステータスの更新が提供されます。 
GET /api/collection/resource_id/creation_status/creation_status_id HTTP/1.1
Accept: application/xml

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

<creation id="creation_status_id"
  href="/api/collection/resource_id/creation_status/creation_status_id">
    <status>
        <state>complete</state>
    </status>
</creation>
Copy to Clipboard Toggle word wrap
非同期リソースの作成をオーバーライドするには Expect: 201-created ヘッダーが必要です。 
POST /api/collection HTTP/1.1
Accept: application/xml
Content-Type: application/xml
Expect: 201-created

<resource>
    <name>Resource-Name</name>
</resource>
Copy to Clipboard Toggle word wrap
トップに戻る
Red Hat logoGithubredditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。 最新の更新を見る.

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

Theme

© 2025 Red Hat