1. Cloud管理ガイド
  2. クラウドAPIの使用
  3. クラウドAPIの概要

41 クラウドAPIの概要

クラウド・コンピューティングは、動的に拡張可能なデプロイ済リソースをサービスとしてネットワーク経由で提供するスタイルのコンピューティングです。

提供するサービスをサポートするクラウドの基盤となるインフラストラクチャについての知識や経験は不要で、これらのインフラストラクチャを管理する必要もありません。エンタープライズ(企業、政府、その他の組織)は既存の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を使用する場合

クラウドREST APIを使用すると、Enterprise Managerをカスタムビルドまたはサード・パーティのセルフ・サービス・コンソールおよびサービス・デスクと統合できます。サンプル・シナリオをいくつか示します。

  • データベースおよびOracle VMアセンブリを、カスタムビルドのセルフ・サービス・コンソールからデプロイする。

  • 承認ワークフローの後に行われるプロビジョニングなど、大規模な調整フローへの統合。

  • データベースおよびOracle VMアセンブリをサービス・デスクからデプロイする。

  • 一般にクラウドのテナント・インタフェースが異なり、サービスの調達、テナント登録などを提供するパブリック・クラウドの一部として。

共通の動作

この項では、Oracle Cloud Computing PlatformでサポートされるREST APIで発生するすべてのリクエストとレポートに適用される制約を指定します。

転送プロトコル

すべてのプラットフォームAPIは、ハイパーテキスト転送プロトコル(HTTP)バージョン1.1(RFC 2616)に基づいています。各リクエストは、特別の定めのないかぎり、HTTP基本認証(RFC 2617)を使用して認証されます。このため、公共インターネット(およびVPNなどの安全なチャネル以外)から送信されるリクエストはHTTPSプロトコルを使用する必要があります。

URI空間

システム内のリソースは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ヘッダーが使用されます。

表41-1 リクエスト・ヘッダー

ヘッダー サポートされる値 説明 必須

Accept

メディア・タイプまたはメディア・タイプ・パターンのカンマ区切りリスト

受入れ可能なメディア・タイプをサーバーに示します。

レスポンス・メッセージ本文を生成するリクエストで推奨されます。

Authorization

「Basic」およびユーザー名とパスワード(RFC 2617に準拠して)。

このリクエストを作成したユーザーを識別します。

ほとんどのリクエストで必須。

Content-Length

リクエスト・メッセージ本文の長さ(バイト単位)。

メッセージ本文のサイズを示します。

メッセージ本文を含むリクエストでは必須。

Content-Type

リクエスト・メッセージ本文を示すメディア・タイプ。

リクエスト・メッセージ本文の表現と構文を示します。

メッセージ本文を含むリクエストでは必須。

ホスト

メッセージを受信するホストを識別します。

単一のIPアドレスで複数のオリジン・ホストをサポートするのに必要です。

すべてのリクエスト。

X-YYYYYClient-Specification-Version

仕様バージョン番号を含む文字列。

このクライアントがプログラムされたYYYYY APIの仕様バージョンを宣言します。

いいえ

レスポンス・ヘッダー

次の表に、プラットフォームから返されるレスポンスに含まれる、特定のHTTPヘッダーを示します。

表41-2 レスポンス・ヘッダー

ヘッダー サポートされる値 説明 必須

Content-Type

レスポンス・メッセージの本文を示すメディア・タイプ。

レスポンス・メッセージ本文の表現と構文を示します。

メッセージ本文を含むレスポンスでは必須。

場所

新しく作成されたリソースまたは参照された元のリソースの正規のURI。

リソース表現のリクエストに使用できるURIを返します。

新規リソースの作成リクエストまたは既存リソースの変更リクエストに対するレスポンスでは必須。

Cache-Control

Max-age、public、no-store、mustrevalidate、proxyrevalidate。

リソース表現をキャッシュする方法と、その鮮度を示します。

いいえ。頻繁には変更されないパブリック・リソース(パブリック・アセンブリやテンプレートのリストなど)の場合、緩やかなキャッシュ制約を許可してレスポンスを最適化します。

特権リソースや認可ヘッダーを含むリソース・リクエストで、これが返されることはありません。

HTTPステータス・コード

Oracle Cloud Computing Platform APIは、説明に示されている状況下で、次の表に示す標準のHTTPレスポンス・コードを返します。

表41-3 HTTPレスポンス・コード

ヘッダー 説明

100 続行

クライアントは要求を継続する必要があります。この仮のレスポンスを使用して、プラットフォームで要求の最初の部分が受信され、まだ拒否されていないことをクライアントに通知します。クライアントはリクエストの残りを送信して続行します。リクエストがすでに完了している場合は、このレスポンスを無視します。

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

現在、サーバーは、一時的なオーバーロードまたはメンテナンスのため、要求を処理できません。

共通リソース属性

この仕様のすべてのリソース・エンティティには、次の共通リソース属性を含めることができます。

リソースの状態

この属性は、リソースのライフサイクルを示すリソースの状態を表します。これは、エンティティ固有のセマンティクを持つリソースによって表されるエンティティのステータスとは異なります。

次の表に、この属性のデータ・モデルを示します。

表41-4 ResourceStateデータ・モデル

フィールド データ型 説明 発生

state

文字列

リソースの最新の既知の現行状態。ライフサイクル状態を含むラベルです(たとえば、INITIATED、CREATING、CREATED、DESTROYING、DESTROYED、READY)。

ベンダーの拡張機能がある場合、ベンダーはセマンティックを公開して文書化する必要があります。

1

progress

0から100の整数

進行状況をおおよそのパーセントで示します。すべてのstateラベルがこのフィールドに意味を与えるわけではありません。

0..1

messages

メッセージ[]

注目すべきやり取りを示す、メッセージ・データ・モデル・インスタンスを含みます。

0..1

コレクション

この属性は、リソースのコレクション・フィールドを表すメタ・リソースです。たとえば、VDCにVMのコレクションが含まれ、VMのリストを表すフィールドがこのタイプに実装されます。

リソース・モデルでは、コレクション・フィールドはコレクション<タイプ>として示されます(たとえば、コレクション<VM>)。

表41-5 コレクション<タイプ>データ・モデル

フィールド データ型 説明 発生

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ヘッダーに含めることはできません。

表41-6 メッセージ・データ・モデル

フィールド データ型 説明 発生

messages

Message

個別メッセージごとに、ゼロ以上のメッセージ・データ。

0..n

個別メッセージには、次のフィールドが含まれます。

表41-7 個別メッセージ・データ・モデル

フィールド データ型 説明 発生

code

文字列

個別メッセージごとに、ゼロ以上のメッセージ・データ。

0..1

field

文字列

このメッセージが関連付けられているリクエスト・データ・モデルのフィールド名。

0..1

hint

文字列

問題の性質を示す、ローカライズされたテキスト。クライアントが試すことのできた可能性のある回避策が含まれることがあります。

0..1

text

文字列

このメッセージによりレポートされた問題の性質を示す、ローカライズされたテキスト。

1

severity

文字列

このメッセージで示されたエラー状態の重大度を表すラベル。

ベンダーは、このフィールドに関連する列挙子とそのセマンティックを公開する必要があります。

0..1

stack_trace

文字列

このメッセージに関連するベンダー固有のスタック・トレース。

0..1

source

文字列

このメッセージをトリガーしたサービス実装コンポーネントのシンボリック識別子。

0..1