| Oracle® Enterprise Manager Cloud管理ガイド 12c リリース5 (12.1.0.5) B70509-13 |
|
 前 |
 次 |
クラウド・コンピューティングは、動的に拡張可能なデプロイ済リソースをサービスとしてネットワーク経由で提供するスタイルのコンピューティングです。提供するサービスをサポートするクラウドの基盤となるインフラストラクチャについての知識や経験は不要で、これらのインフラストラクチャを管理する必要もありません。エンタープライズ(企業、政府、その他の組織)は既存のITインフラストラクチャおよびITリソースを共有可能なクラウド・パラダイムに統合するため、クラウド・イネーブラは、エンタープライズがビジネス・プロセスや経済モデルにあわせてクラウドをカスタマイズする際に使用できる統一APIを用意する必要があります。
ここで説明するRepresentational State Transfer (REST) APIは、リソース・モデルとその属性に重点が置かれています。
この章の内容は次のとおりです。
ITデプロイメントが複雑になるにつれて、インフラストラクチャ・リソースの抽象化はコンプライアンスや構成に関する問題への対処に関連するようになってきました。さらに、このようなリソースの抽象化により、管理者が大幅に介入する必要なしに、コンシューマは必要なサービスを自ら用意し、操作時にサービスを制御できるようになります。
REST APIにより、インフラストラクチャ・プロバイダは、顧客に次の作業を許可する形でサービスを提供できます。
サービスの論理単位の定義とメタデータを含むテンプレートの参照。
テンプレートのクラウドへのデプロイおよびオンデマンドでのITトポロジの構成。
リソースに対する操作の実行(ONLINE、OFFLINEなど)。
このREST APIはHTTPプロトコルに基づいており、GET、POST、PUTおよびDELETEリクエストがすべて使用されます。ここで説明するリソース表現は、JavaScript Object Notation (JSON)を使用しています。
このREST APIはUniform Resource Identifier (URI)空間の特定の構造を前提としていません。開始点はクラウド・サービス・プロバイダによって提供されるURIで、クラウドそのものを識別します。クラウドの表現には、クラウド内の他のリソースのURIが含まれます。クラウド・リソースに対する操作は、リソースのURIへのHTTPリクエストを作成することで実行されます。
このクラウドREST APIの仕様には、次のようなものがあります。
すべてのリクエストおよびレスポンス、エラー・メッセージ、共通リソース属性に適用される共通の動作。
リクエストとレスポンスで使用されるJSONデータ構造を説明するリソース・モデル。
クラウド・リソースに送信されるリクエストおよび予想されるレスポンス。
クラウドREST APIを使用すると、Enterprise Managerをカスタムビルドまたはサード・パーティのセルフ・サービス・コンソールおよびサービス・デスクと統合できます。サンプル・シナリオをいくつか示します。
データベースおよびOracle VMアセンブリを、カスタムビルドのセルフ・サービス・コンソールからデプロイする。
承認ワークフローの後に行われるプロビジョニングなど、大規模な調整フローへの統合。
データベースおよびOracle VMアセンブリをサービス・デスクからデプロイする。
一般にクラウドのテナント・インタフェースが異なり、サービスの調達、テナント登録などを提供するパブリック・クラウドの一部として。
次の表では、Enterprise Manager Cloud Controlクラウド・サービス・ポータルの、プラグイン12.1.0.4から12.1.0.5での重要な変更点について説明します。
Table 45-1 リソース・モデルに関する変更点(12.1.0.4から12.1.0.5)
| 概要 | 説明 | 影響 |
|---|---|---|
|
QuotaUsageリソースの可用性 |
サービス・ファミリ・タイプからAPIを介してリソース割当て制限使用量情報を確認できます。 |
割当て制限使用量を参照するための追加属性が各リソース・モデルに追加されます。 |
|
ServiceTemplateFindsリソースの可用性 |
サービス・ファミリ・タイプでは、サービス・テンプレートのリソースの問合せのサポートを提供できます。 |
クラウド・レベル相互作用により、リスト基準を満たすサービス・テンプレートのリストが返されます。 |
次の表に、Enterprise Manager Cloud Controlクラウド・サービス・ポータルの、プラグイン12.1.0.2から12.1.0.4での重要な変更点を示します。
Table 45-2 リソース・モデルに関する変更点(12.1.0.2から12.1.0.4)
| 概要 | 説明 | 影響 |
|---|---|---|
|
x-specification-versionヘッダーの導入 |
x-specification-versionは、このリリースで導入された新しいヘッダーです。このヘッダーの目的は、サポートされる様々なバージョンのクラウド・リソース・モデル間の切替えをバックエンド・サーバーに通知することです。 デフォルトで、このヘッダーを指定しない場合、サーバーでは最新バージョンのリソース・モデルが自動的に使用されます。 現在、各サーバー・レスポンスもx-specification-versionを含むことができます。 |
クライアントが以前(12.1.0.4クラウド・サービス・ポータル以前)のリソース・モデルを12.1.0.4クラウド・サービス・ポータルで使用する必要がある場合、次のヘッダーを指定できます。 x-specification-version: 10000 たとえば、GET /em/cloud with x-specifcation-version: 10000で、12.1.0.4以前のリリースのクラウド・サービス・ポータルのクラウド・リソースが返されます。 |
|
サービス指向性に更新されたクラウド・メディア・タイプ |
このリリース以前、最上位のクラウド・メディア・タイプはIaaS中心のものでした。しかし、このリリースではMiddleware as a Serviceが追加され、クラウド・メディア・タイプは汎用サービス・モデルとなり、メディア・タイプを再構築しないで、XaaSをシステムにプラグインして追加できるようになりました。 |
クラウド・メディア・タイプは下位互換性でなくなりました。(ただし、x-specifiction-versionヘッダーの使用により、クライアントの以前のメディア・タイプへの切替えは引き続き可能です)。 |
|
ゾーンに統合されるVDC概念 |
IaaS中心のVDCがサポートするリソース関係は、汎用性の高いゾーン・リソースに統合されます。VDCリソースは、現在、12.1.0.4クラウド・サービス・ポータルのリソース・モデルから表示できません。 |
12.1.0.4クラウド・サービス・ポータルのリソース・モデルとの相互作用は、VDCではなくゾーン中心となります。 |
|
リソースへのmedia_type属性の追加 |
各リソースにmedia_type属性が追加され、汎用サービス・モデルのクライアント・イントロスペクションがサポートされます。つまり、同じ抽象メディア・タイプを展開する異なるメディア・タイプのリソースのリストをリソースのコレクション属性に含めることができます。 |
Webサービスとの相互作用をイントロスペクトできます。たとえば、クラウド・リソースには、様々なXaaSから取得されたサービス・テンプレートのリストを説明するservice_templates属性があります。 service_templates内の各サービス・テンプレート・アイテムは様々なメディア・タイプにできますが、これらのメディア・タイプには、汎用サービス・テンプレート・モデルのすべての属性を含める必要があります。 |
|
受入れヘッダーはオプションに |
相互作用の目的が明白な場合、受入れヘッダーを指定する必要はありません。 |
WebサービスによってリソースURIが自動的にイントロスペクトされ、最も固有のメディア・タイプのリソースが返されます。 |
|
汎用メディア・タイプと固有メディア・タイプ |
継承をサポートするため、このバージョンには汎用メディア・タイプと固有メディア・タイプの概念が導入されています。たとえば、application/oracle.com.cloud.common.ServiceTemplateは汎用メディア・タイプ、application/oracle.com.cloud.common.VMTemplateは前述の汎用タイプを展開する固有タイプです。 固有タイプから他の固有タイプを展開できます(オブジェクト継承と同様)。 |
汎用タイプを使用してリソースを照会できるようになりました。たとえば、URIが固有タイプYのリソースを表し、Yが汎用タイプXを展開する場合、GET URIは値Xの受入れヘッダーも受け入れます。 さらに、固有タイプYの属性には汎用タイプXの属性を含める必要があり、これにより、クライアントは汎用タイプのリソースと相互作用できるようになります。 |
この項では、Oracle Cloud Computing PlatformでサポートされるREST APIで発生するすべてのリクエストとレポートに適用される制約を指定します。
すべてのプラットフォームAPIは、ハイパーテキスト転送プロトコル(HTTP)バージョン1.1(RFC 2616)に基づいています。各リクエストは、特別の定めのないかぎり、HTTP基本認証(RFC 2617)を使用して認証されます。このため、公共インターネット(およびVPNなどの安全なチャネル以外)から送信されるリクエストはHTTPSプロトコルを使用する必要があります。
システム内のリソースはURIによって識別されます。操作を開始するには、リソースのURIが既知である必要があります。URIを逆参照すると、リソース属性を含むリソースの表現および関連するリソースへのリンクが生成されます。
URIのレイアウトについての仮定またはリソースURIの構造は作成されません。
この仕様では、リソース表現とリクエストの本文は、RFC 4627で指定されたとおりにJavaScript Object Notation (JSON)でエンコードされます。各リソース・タイプには、次のパターンと一致する独自のメディア・タイプがあります。
application/oracle.com.cloud.common.Xxxxx+json
Xxxxxは、各リソースの個別の表現形式に固有の識別子の一部です。この識別子は、vnd.com.oracle.cloudの空間でグローバルに一意である必要があります。また、メディア・タイプをRFC 4288に従って登録する必要があります。
プラットフォームには、JSONで使用できるすべてのリソースの表現が用意されている必要があります。プラットフォームは、JSONでエンコードされたリクエストを受け入れる必要があります。
Oracle Cloud Platform APIを実装するサービスに対するリクエストでは、次の表に示すいくつかのHTTPヘッダーが使用されます。
表45-3 リクエスト・ヘッダー
| ヘッダー | サポートされる値 | 説明 | 必須 |
|---|---|---|---|
|
Accept |
メディア・タイプまたはメディア・タイプ・パターンのカンマ区切りリスト |
受入れ可能なメディア・タイプをサーバーに示します。 |
レスポンス・メッセージ本文を生成するリクエストで推奨されます。 |
|
Authorization |
「Basic」およびユーザー名とパスワード(RFC 2617に準拠して)。 |
このリクエストを作成したユーザーを識別します。 |
ほとんどのリクエストで必須。 |
|
Content-Length |
リクエスト・メッセージ本文の長さ(バイト単位)。 |
メッセージ本文のサイズを示します。 |
メッセージ本文を含むリクエストでは必須。 |
|
Content-Type |
リクエスト・メッセージ本文を示すメディア・タイプ。 |
リクエスト・メッセージ本文の表現と構文を示します。 |
メッセージ本文を含むリクエストでは必須。 |
|
Host |
メッセージを受信するホストを識別します。 |
単一のIPアドレスで複数のオリジン・ホストをサポートするのに必要です。 |
すべてのリクエスト。 |
|
X-YYYYYClient-Specification-Version |
仕様バージョン番号を含む文字列。 |
このクライアントがプログラムされたYYYYY APIの仕様バージョンを宣言します。 |
いいえ。 |
次の表に、プラットフォームから返されるレスポンスに含まれる、特定のHTTPヘッダーを示します。
表45-4 レスポンス・ヘッダー
| ヘッダー | サポートされる値 | 説明 | 必須 |
|---|---|---|---|
|
Content-Type |
レスポンス・メッセージの本文を示すメディア・タイプ。 |
レスポンス・メッセージ本文の表現と構文を示します。 |
メッセージ本文を含むレスポンスでは必須。 |
|
Location |
新しく作成されたリソースまたは参照された元のリソースの正規のURI。 |
リソース表現のリクエストに使用できるURIを返します。 |
新規リソースの作成リクエストまたは既存リソースの変更リクエストに対するレスポンスでは必須。 |
|
Max-age、public、no-store、mustrevalidate、proxyrevalidate。 |
リソース表現をキャッシュする方法と、その鮮度を示します。 |
いいえ。頻繁には変更されないパブリック・リソース(パブリック・アセンブリやテンプレートのリストなど)の場合、緩やかなキャッシュ制約を許可してレスポンスを最適化します。 特権リソースや認可ヘッダーを含むリソース・リクエストで、これが返されることはありません。 |
Oracle Cloud Computing Platform APIは、説明に示されている状況下で、次の表に示す標準のHTTPレスポンス・コードを返します。
表45-5 HTTPレスポンス・コード
| ヘッダー | 説明 |
|---|---|
|
100 Continue |
クライアントは要求を継続する必要があります。この仮のレスポンスを使用して、プラットフォームで要求の最初の部分が受信され、まだ拒否されていないことをクライアントに通知します。クライアントはリクエストの残りを送信して続行します。リクエストがすでに完了している場合は、このレスポンスを無視します。 |
|
200 OK |
リクエストは正常に完了しました。このリクエストによって、URIでアドレス可能な新規リソースが作成され、新規リソースの表現を含むレスポンス本文が返された場合、200ステータスは新しく作成されたリソースの正規のURIを含むLocationヘッダーとともに返されます。 |
|
201 Created |
新規リソースを作成したリクエストは完了し、新規リソースの表現を含むレスポンス本文は返されません。新しく作成されたリソースの正規のURIを含むLocationヘッダーが返されます。 |
|
202 Accepted |
要求の処理は受け入れられましたが、処理は完了していません。HTTP/1.1仕様どおり、返されるエンティティ(ある場合)にはリクエストの現在のステータスの表示が含まれる必要があります。まだ完了していないリソースの正規のURIを含むLocationヘッダーが、進行状況を示すステータス属性とともに返されます。 |
|
400 Bad Request |
情報が欠落しているか不適切であるため(入力フィールドでの検証エラー、必須値の欠落など)、リクエストを処理できませんでした。 |
|
401 Unauthorized |
このリクエストに認証資格証明がないか、または無効です。 |
|
403 Forbidden |
資格証明はサーバーによって認識されましたが、ユーザーはこのリクエストを実行する権限を持っていません。 |
|
404 Not Found |
リクエストで、存在しないリソースのURIが指定されました。 |
|
405 Method Not Allowed |
リクエストで指定されたHTTP動詞(DELETE、GET、HEAD、POST、PUT)は、このリクエストURIではサポートされていません。 |
|
406 Not Acceptable |
このリクエストによって識別されたリソースは、リクエストのAcceptヘッダーのいずれかのメディア・タイプに対応する表現を生成できません。 |
|
409 Conflict |
プラットフォームでサポートされるリソースの現在の状態の競合の原因となるため、作成または更新リクエストを完了できません。たとえば、既存のリソースにすでに割り当てられている一意の識別子で新規リソースを作成しようとしたり、まだ完了していないリソース属性を変更しようとしました。 |
|
410 Gone |
要求されたリソースはサーバーで使用できなくなりました。転送アドレスが不明です。この状況は永続的なものと想定されます。リンク編集機能を持つクライアントは、ユーザー承認の後でRequest-URIへの参照を削除する必要があります。 この状況が永続的であるかどうかをサーバーが特定できない、またはそのことを判断する機能がサーバーにない場合は、ステータス・コード404(Not Found)をかわりに使用する必要があります。このレスポンスはキャッシュ可能です(キャッシュ不可と指定されていない場合)。 |
|
412 Precondition Failed |
1つ以上の要求ヘッダー・フィールドに指定されている事前条件が、サーバーでのテストで+と評価されました。クライアントはこのレスポンス・コードを使用して、現在のリソース・メタ情報(ヘッダー・フィールド・データ)に事前条件を設定できます。これにより、リクエストされたメソッドが目的外のリソースに適用されるのを阻止できます。 |
|
500 Internal Server Error |
サーバーに予期しない状況が発生し、リクエストを遂行できなくなりました。 |
|
501 Not Implemented |
サーバーは(現在)、要求を満たすために必要な機能をサポートしていません。 |
|
503 Service Unavailable |
現在、サーバーは、一時的なオーバーロードまたはメンテナンスのため、要求を処理できません。 |
この仕様のすべてのリソース・エンティティには、次の共通リソース属性を含めることができます。
この属性は、リソースのライフサイクルを示すリソースの状態を表します。これは、エンティティ固有のセマンティクを持つリソースによって表されるエンティティのステータスとは異なります。
次の表に、この属性のデータ・モデルを示します。
表45-6 ResourceStateデータ・モデル
| フィールド | タイプ | 説明 | 発生 |
|---|---|---|---|
|
state |
文字列 |
リソースの最新の既知の現行状態。ライフサイクル状態を含むラベルです(例: INITIATED、CREATING、CREATED、DESTROYING、DESTROYED、READY)。 ベンダーの拡張機能がある場合、ベンダーはセマンティックを公開して文書化する必要があります。 |
1 |
|
progress |
0から100の整数 |
進行状況をおおよそのパーセントで示します。すべてのstateラベルがこのフィールドに意味を与えるわけではありません。 |
0..1 |
|
messages |
Message[] |
注目すべきやり取りを示す、メッセージ・データ・モデル・インスタンスを含みます。 |
0..1 |
この属性は、リソースのコレクション・フィールドを表すメタ・リソースです。たとえば、VDCにVMのコレクションが含まれ、VMのリストを表すフィールドがこのタイプに実装されます。
リソース・モデルでは、コレクション・フィールドはコレクション<タイプ>として示されます(例: コレクション<VM>)。
表45-7 コレクション<タイプ>データ・モデル
| フィールド | タイプ | 説明 | 発生 |
|---|---|---|---|
|
uri |
URI |
エンティティのコレクションを表すURI。 |
1 |
|
type |
文字列 |
このコレクションに含まれるエンティティのタイプ。 |
1 |
|
total |
整数 |
要素リストで安全に収容できると想定される要素数合計。 |
0..1 |
|
elements |
<TYPE>[] |
このコレクション内のエンティティのリスト。エンティティのURIは、プラットフォームによって移入される必要があります。URIを逆参照する場合、クライアントはAcceptヘッダーのtypeフィールドを使用する必要があります(type = URIの場合を除く)。 返されない場合、コレクションは空白のリストです。 |
0..1 |
リソース・タイプの他に、コレクションはtypeフィールドがURIのコレクション<URI>もサポートしています。この基本的なタイプ・コレクションには、URIを適切に逆参照できる追加のタイプ・キャストが必要です。
この基本的なタイプ・コレクションには、URIを適切に逆参照できる追加のタイプ・キャストが必要です。コレクション・タイプのコレクションを持つこともできます(例: コレクション<コレクション<サーバー>>)。
リクエストが成功すると、一般にリクエストしたアクションが正常に実行または送信されたことを示す、200 (OK)、201 (Created)、202 (Accepted)または204 (No Content)などのHTTPステータス・コードが返されます。
さらに、リクエストした情報の表現を含むレスポンス・メッセージ本文(適切なメディア・タイプの)が含まれることもあります。しかし、エラーが発生することもあります。
様々な根本的な原因が、400-499(クライアント側のエラー)または500-599(サーバー側の問題)の範囲のHTTPステータス・コードによって示されます。
レスポンスがエラー・ステータス・コード(400-499または500-599)で返される場合、エラーの内容を示すゼロ以上のメッセージ・データ・モデルを含むレスポンス・メッセージ本文も返されます。これらのメッセージのテキスト値は、クライアント側アプリケーションのユーザーとのやり取りなどに使用されます。
1つのエラー・レスポンスに含まれるメッセージのリスト全体が、メッセージ・データ・モデルにカプセル化されます。メディア・タイプはContent-Typeヘッダーで返されます。クライアントはMessagesメディア・タイプをAcceptヘッダーに含めることはできません。
個別メッセージには、次のフィールドが含まれます。
表45-9 個別メッセージ・データ・モデル
| フィールド | タイプ | 説明 | 発生 |
|---|---|---|---|
|
code |
文字列 |
個別メッセージごとに、ゼロ以上のメッセージ・データ。 |
0..1 |
|
field |
文字列 |
このメッセージが関連付けられているリクエスト・データ・モデルのフィールド名。 |
0..1 |
|
hint |
文字列 |
問題の性質を示す、ローカライズされたテキスト。クライアントが試すことのできた可能性のある回避策が含まれることがあります。 |
0..1 |
|
text |
文字列 |
このメッセージによりレポートされた問題の性質を示す、ローカライズされたテキスト。 |
1 |
|
severity |
文字列 |
このメッセージで示されたエラー状態の重大度を表すラベル。 ベンダーは、このフィールドに関連する列挙子とそのセマンティックを公開する必要があります。 |
0..1 |
|
stack_trace |
文字列 |
このメッセージに関連するベンダー固有のスタック・トレース。 |
0..1 |
|
source |
文字列 |
このメッセージをトリガーしたサービス実装コンポーネントのシンボリック識別子。 |
0..1 |
