2 Oracle Compute REST APIの概要

この項では、Oracle Compute Cloud Service REST APIコマンドを使用して、 Oracle Public Cloud Machine上のOracle Computeサイトを管理する方法について説明します。

トピック:

REST APIリクエストおよびレスポンスについて

A REST APIトランザクションには、APIリクエストおよび関連するAPIレスポンスがあります。

APIリクエストは、次の部分からなります:

APIリクエスト・メソッド - Oracle Computeオブジェクトで実行する操作を指定します。サポートされているREST APIメソッドを参照してください。
リソースURL - Oracle Public Cloud Machine上のターゲットOracle Computeオブジェクトの完全修飾されたURIを指定します。オブジェクト名についてを参照してください。
リクエスト・ヘッダー - REST APIリクエスト・ヘッダーを指定します。 REST APIリクエスト・ヘッダーを参照してください。
リクエスト本文 - Oracle Computeオブジェクトで操作を実行するために必要なカスタム化されたパラメータのリストを指定します。

APIレスポンスは、次の部分からなります:

HTTPレスポンス・コード - REST APIリクエストが成功したか、または失敗したかを指定します。 HTTPレスポンス・コードを参照してください。
レスポンス・ヘッダー - REST APIレスポンス・ヘッダーを指定します。
レスポンス本文 - REST APIリクエストのレスポンスで返されるJavaScript Object Notation (JSON)エンコードされたデータを指定します。

サポートされているHTTPメソッド

次の表で、Oracle Public Cloud Machineオブジェクトを呼び出せるREST HTTPメソッドについて説明しています。

注意:

特定のオブジェクトに対するメソッドの一部は、サポートされていません。

メソッド	説明
`POST`	リクエスト本文でJSON形式のデータを使用して、オブジェクトを作成します。
`GET`	リクエストURIで指定されたオブジェクトに関する情報を取得します。
`PUT`	リクエスト本文でJSON形式のデータを使用して、オブジェクトの属性を更新します。
`DELETE`	リクエストURIで指定されたオブジェクトを削除します。

オブジェクト名について

REST APIコールを実行できる各Oracle Computeオブジェクトは、そのURIにより一意に識別されます。インスタンス、ストレージ・ボリュームまたはSSH鍵などのオブジェクトは、コンテナの階層の位置に基づいて名付けられます。

たとえば、オブジェクト名/mytenant/public/8e7c16ad-1bc4-4743-a9ce-781be4e26f24は、このインスタンス8e7c16ad-1bc4-4743-a9ce-781be4e26f24がコンテナpublic,にあり、publicがコンテナmytenantにあることを示します。

REST APIリクエスト・ヘッダー

次のヘッダーがHTTPリクエストで正しく指定されていることを確認してください。

リクエスト・ヘッダー	説明
`Accept:`	いくつかの例外を除き、REST APIは、そのレスポンスにJavaScript Object Notation (JSON)でエンコードされたデータを返します。 `Accept:`ヘッダーを指定して、JSON形式およびAPIのバージョン番号の両方を示す必要があります。サポートされているAPIプロトコルはv3です。コンテナ内のオブジェクトの名前(詳細ではなく)のみを取得する`GET`コールは、このヘッダーを`application/oracle-compute-v3+directory+json`に設定しますその他の目的にはすべてヘッダーを`application/oracle-compute-v3+json`に設定します例: Accept: application/oracle-compute-v3+json
`Accept-Encoding:`	HTTPクライアントが、サポートされているエンコードされた値に設定されていることを確認します。例: Accept-Encoding: gzip;q=1.0, identity; q=0.5
`Accept-Charset:`	APIは、UTF-8エンコード・データのみを送信および受信します。使用するHTTPクライアントが、JSONデータを含む文字データをエンコードおよびコード解除することを確認します。例: Accept-Charset: UTF-8
`Content-Type:`	HTTPリクエスト本文内のすべてのコンテンツを、JSONでエンコードする必要があります。また、APIプロトコル・バージョンは、リクエストおよびレスポンス・メッセージの両方で指定されます。コンテンツ・タイプは、次のとおりです: `application/oracle-compute-v3+json` `multipart/oracle-compute-v3+form-data` `application/x-tar` サーバーで、予期されるレスポンス内のデータのバージョンが`Content-Type:`ヘッダーで指定されます。サーバーがリクエスト内でクライアントによって指定されたバージョンをサポートしていない場合、サーバーは、HTTPステータス・コード415 (Unsupported Media Type)で応答します。サーバーがクライアントでサポートされているすべてのバージョンでレスポンスを返せない場合、ステータス・コード406 (Not Acceptable)で応答します。例: Content-Type: application/oracle-compute-v3+json
`Cookie:`	`Cookie:`ヘッダーを、サービスに対するそれぞれのリクエストに含めます。 `Set-Cookie`ヘッダーの値を、`POST /authenticate/`コールで受信したレスポンスに設定します。認証を参照してください。

HTTPレスポンス・コード

次の表に、HTTPレスポンス・コードとその意味をリストします。

HTTPレスポンス・コード	説明
2XX	API Successful リクエストが成功したことを示します。
201	Created リクエストの追加/更新が成功しました。
204	内容なし。削除リクエストがレスポンス・コンテンツなしに成功しました。
4xx	APIClientError クライアント側のエラーで、HTTPの4xxエラーです。
401	APIUnauthorizedError リクエストにはユーザー認証または認可が必要です。
403	APIForbiddenError リクエストは正常にフォーマットされましたが、サーバーは正常に終了しませんでした。この問題は、認証とは関係ありません。リクエストを繰り返さないようにしてください。
404	APINotFoundError リクエストに一致するURIを検索できませんでした。これは一時的な状態のため、リクエストを繰り返してください。
405	APIMethodNotAllowedError リクエストラインで指定されたメソッドが、リクエストURIで識別されるリソースに対して許可されていません。この例外は、オブジェクトでサポートされていないメソッドがリクエストに含まれている場合に発生します。
406	APINotAcceptableError レスポンスを生成するリクエストで指定されたリソースが、リクエストの受信ヘッダーで許可されていない特性を持ちます。
409	APIConflictError リクエストは、リソースの状態との競合のため、またはリソースがすでに存在するため、完了できませんでした。既存のオブジェクトを削除してリクエストがオブジェクトを作成できるようにするか、一意の識別子を使用して新しいオブジェクトを作成します。
410	APIGoneError リクエストされたリソースは存在しません。このエラーは、インスタンスが存在しますが稼働中ではなく、このインスタンスの複製を同じ識別子を使用して作成できません。
413	APIRequestTooLarge リクエストが、最大アップロード・サイズを超えるイメージのアップロードを試みました。デフォルトの最大サイズは、10GBです。この制限を変更するには、`site.conf`ファイルを編集して、次のように行を変更します:`[services] [[api] [[[max_upload]]]`。
415	APIUnsupportedTypeError サーバーは、リソースのメソッドでサポートされていない形式がリクエストに含まれているため、リクエストを完了できません。このエラーは、JSON形式のエラーを示します。
5xx	APIServerError 内部エラーが発生し、サーバーはリクエストを正常に処理できませんでした。
500	APIUncaughtExceptionError サーバーで予期しない状態が発生し、リクエストを処理できませんでした。このエラーはコードを含みます。このエラーを使用して、My Oracle Supportに問題を報告してください。
501	APINotImplementedError サーバーは、リクエストを正常に処理するために必要な機能をサポートしていません。
503	APIServiceUnavailable 一時的な過負荷またはメンテナンス状態にあるため、サーバーがリクエストを処理できません。このエラーは、通常、サーバーの負荷に関係し、一時的なものです。リクエストを繰り返してください。
502/504	APIGatewayError Oracle Computeサービス層が応答しません。これは、通常、サービスのフェイルオーバーに関係し、一時的なものです。リクエストを繰り返してください。
507	APIInsufficientStorage サーバーが、リクエストを完了するために必要なデータを格納できません。この状態は一時的なものです。リクエストを繰り返してください。

cURLを使用したREST APIコールの起動

HTTPリクエストを適切なリソースURIに送信することにより、Oracle Compute Cloud ServiceのREST APIと対話できます。 REST APIコールの起動には、一般的なブラウザの拡張やプラグインなどのクライアントを含め、複数のツールがあります。cURLは、HTTPリクエストの構築および送信用のコマンドライン・ツールです。このトピックでは、cURLを使用して、REST APIコールをOracle Compute Cloud Serviceに送信する方法について説明します。

前提条件

cURLのSSL対応バージョン、または他の任意のREST APIクライアント。

たいていのLinuxインストールにはcURLが含まれています。 cURLをダウンロードし、インストールするには、http://curl.haxx.se/download.htmlを参照してください。
Oracle Compute Cloud ServiceのRESTエンドポイントURL。 Oracle ComputeリソースのURIを参照してください
リクエストおよびリクエストに含めるパラメータの送信先となるリソースURI。

REST APIのサマリー(リソース・パスのアルファベット順)を参照してください。使用可能なすべてのリソースがリストされています。インスタンスごとに、サポートされているパラメータに関する参照ドキュメントへのリンクも記載されています。
Oracle Compute Cloud Serviceインスタンスのユーザー名およびパスワード。『Oracle Compute Cloud Serviceの使用』のOracle Compute Cloud Serviceのスタート・ガイドに関する項を参照してください。

この情報が手元にない場合、Oracle Cloud管理者またはテナント管理者に連絡をしてください。

手順

認証トークンを、次に示すcURLコマンドの例のようにOracle compute Cloud Serviceから取得します:

コマンドを単一の行で入力します。この例では読みやすくするために改行が使用されています。
```
curl -i -X POST
     -H "Content-Type: application/oracle-compute-v3+json"
     -d '{"user":"/mytenant/myuser","password":"ft7)Dvjo"}'
        https://api.oc.example.com/authenticate/
```
次の例に示すように、POSTリクエストに対するレスポンスで、Set-Cookieヘッダーを探します。
```
Set-Cookie: nimbula={"identity": "{\"realm\": \"mytenant\", \"value\": \"{\\
\"customer\\\": \\\"acme\\\", ....Bb2U5uoJ2nwU7g1fDBcII/US6e7yLYqWSdb/U
ItvUiLo7/SARyfG+RmqnuFcJDoczaNssUmLLBikq8IPNAxaSIvGZmzK7K4anTwXcAhVg==\"}
"}; Path=/; Max-Age=300
```
注意:

Set-Cookieヘッダーおよび値は、単一の行になる点に注意してください。この例では読みやすくするために改行が使用されています。
次のLinuxホストの場合の例に示すように、認証cookieを環境変数に格納します。ここで示す例は、読みやすいように短くしてあります。コマンドは、一重引用符で囲んだcookie値の全体を含んでいる必要があります。
```
export ORACLE_COMPUTE_COOKIE='nimbula={"identity": "{\"realm\": \"mytenant\", \"value\": ...cAhVg==\"}"}; Path=/; Max-Age=300'
```
次の例に示すように、必要なHTTPリクエストをOracle Compute Cloud Serviceに送信します。

例1: 利用可能なシェイプのリストの取得
次のGETリクエストを送信します。
```
curl -X GET -H "Cookie: $ORACLE_COMPUTE_COOKIE" https://api.oc.example.com/shape/
```
ORACLE_COMPUTE_COOKIEは、前の手順で認証cookieを格納した変数の名前です。
次の例に示すように、このコマンドでは利用可能なすべてのシェイプの詳細がJSON形式で返されます。

注意:
このサンプル・レスポンスは、読みやすくするために形式が変更されており、また簡潔にする目的で後半部分が省略されています。
```
{
  "result": [
    {
      "ram": 7680,
      "cpus": 2.0,
      "uri": "https://api.oc.example.com/shape/oc3",
      "name": "oc3"
    },
    {
      "ram": 15360,
      "cpus": 4.0,
      "uri": "https://api.oc.example.com/shape/oc4",
      "name": "oc4"
    },
    {
      "ram": 30720,
      "cpus": 8.0,
      "uri": "https://api.oc.example.com/shape/oc5",
      "name": "oc5"
    }
  ]
}
```

REST APIのサマリー(リソース・パスのアルファベット順)

この表は、リソース・パス別のRESTリソース(アルファベット順)、および各リソースでサポートされているメソッドを示しています。

RESTリソース	サポートされるメソッド	詳細情報
`/authenticate/`	`POST`	ユーザーの認証
`/info/`	`GET`	サイト情報の取得
`/imagelist/`	`DELETE`、`GET`、`POST`、`PUT`	イメージ・リストの管理
`/imagelist/name/entry/`	`DELETE`、`GET`、`POST`、`PUT`	イメージ・リスト・エントリの管理
`/instance/`	`DELETE`、`GET`、`POST`、`PUT`	インスタンスの管理
`/machineimage/`	`DELETE`、`GET`、`POST`、`PUT`	マシン・イメージの管理
`/orchestration/`	`DELETE`、`GET`、`POST`、`PUT`	オーケストレーションの管理
`/property/storage/`	`GET`	ストレージ・プロパティの表示
`/quota/`	`GET`	テナント割当て制限の表示
`/svcnet/`	`GET`	サービス・ネットワークの表示
`/shape/`	`GET`	シェイプの表示
`/snapshot/`	`DELETE`、`GET`、`POST`、`PUT`	スナップショットの管理
`/sshkey/`	`DELETE`、`GET`、`POST`、`PUT`	SSH鍵の管理
`/storage/attachment/`	`DELETE`、`GET`、`POST`、`PUT`	ストレージ・アタッチメントの管理
`/storage/volume/`	`DELETE`、`GET`、`POST`、`PUT`	ストレージ・ボリュームの管理
`/tenant/`	`GET`	テナントの表示
`/user/`	`DELETE`、`GET`、`POST`、`PUT`	ユーザーの管理
`/vcable/`	`GET`	vCableの表示
`/vethernet/`	`DELETE`、`GET`、`POST`、`PUT`	vEthernetの管理
`/vnet/`	`DELETE`、`GET`、`POST`、`PUT`	vNETの管理
`/vnetaccess/`	`GET`	vNET Accessの表示
`/vnetreservation/`	`DELETE`、`GET`、`POST`、`PUT`	vNET予約の管理