はじめまして。11月よりCloudiiにjoinさせていただいている id:k-furusawa--g です。
今回はOracle Cloud のサービスの一つであるCompute Classic向けに提供されているREST APIを利用します。Oracle CloudのREST APIは各サービス毎にリクエストの仕方もドキュメントも異なっており、なかなかの取っ付きにくさですが、ComputeClassic向けに提供されているものが一番わかりやすく、とりあえずOracle Cloud のREST APIを使ってみたい方には入門としてぴったりだと思います。 今回は基本となる認証からインスタンス一覧取得までをご紹介します。
REST API利用には以下の公式ドキュメントを参考にさせていただきました。 docs.oracle.com docs.oracle.com
※利用前にユーザロールを確認
REST APIを使うにはロール設定が必要になります。
利用したいユーザに対し、Compute Classicの「Compute_Operations(Service管理者)」、「Compute_Monitor（Computeモニター)」を割り当ててください。 基本的な操作は「Service管理者」のロールさえ割り当ててあれば大丈夫です。
「Computeモニター権限」のみの場合はPOSTやPUTといった更新にかかわるAPIが使えないのでご注意ください。
詳しくは公式ドキュメントの「Compute Classicのロールについて」をご参照ください。
事前準備：Compute Classic のRESTエンドポイントとインスタンスIDを調べておく
事前にRESTエンドポイントとインスタンスIDを確認しておきましょう。 MyServiceからComputeClassicを選ぶことで確認可能です。
上記以外のやり方では、サイドメニューのServicesからCompute Classicを選び、表示されるサイト情報の上部にある「Site」からダイアログを表示させ確認可能です。
確認出来たらメモしておきましょう。
Compute Classic向けREST APIリクエストの組み立て
では早速リクエストを組み立てていきましょう。
URI
まずリクエスト先URIからです。
https://{api_endpoint}/{resource_base_path}/{resource_name}
{}で囲まれているのが設定値です。一つずつ見ていきましょう。
-
{api_endpoint}
サービスのRESTエンドポイントです。上記で事前に調べておいたものになります。
-
{resource_base_path}
RESTリソースのベースURIです。各タスクの持つエンドポイントと認識してください。ComputeClassicの認証の場合「/authenticate/」、インスタンスの場合「/instance/」といった具合です。
全タスクのエンドポイントは下記のドキュメントに書かれています。
REST API for Oracle Cloud Infrastructure Compute Classic - All REST Endpoints
-
{resource_name}
リクエスト対象となるリソースを特定する名前です。タスクによっては必要ありませんが、インスタンスの取得やイメージの取得など、参照するリソースの指定が必要なAPIは必要になります。
ほとんどの場合リソース所持者のユーザIDと上記で事前に調べておいたインスタンスIDを組み合わせて作成します。例えば、fugahoge@atomitech.jpというユーザが「TestInstance」というインスタンスを作成している場合、それを特定するリソース名は以下のようになります。
/Compute-インスタンスID/fugahoge@atomitech.jp/TestInstance/10d2b1d5-****-********************
ちなみに「Compute-インスタンスID」の部分はquota（割当）というそうです。ドキュメント上では「/Compute-インスタンスID/fugahoge@atomitech.jp/」をコンテナ、「/TestInstance/」をサブコンテナ、それらを合わせてインスタンス固有の名前「10d2b1d5--****************」で特定したものをリソース名としているようです。ややこしいですね！ 実際にはサブコンテナまでで詳細を取得することが可能です。
リクエストヘッダー
次にヘッダーです。設定できるヘッダーはいくつかあるのですが、全部書き出すと記事が長くなりすぎますので、今回は最低限指定しなければいけない「Accept」「Content-Type」「Cookie」をご説明します。
-
Accept
リクエスト成功時にAPIが返すレスポンス形式を決定します。
application/oracle-compute-v3+jsonもしくはapplication/oracle-compute-v3+directory+jsonと指定します。違いは「directory」がついているかいないかですが、application/oracle-compute-v3+json+directoryとは書けないので注意してください。application/oracle-compute-v3+directory+jsonを指定すると、詳細が省かれた内容が返ります。リクエストURIが十分でない場合に「directory」を省くと想定したレスポンスが返りませんのでご注意ください。 -
Content-Type
POSTやPUTリクエスト時には必須です。
application/oracle-compute-v3+jsonもしくはmultipart/oracle-compute-v3+form-dataを指定します。通常のHTTPリクエスト同様application/jsonでも送信できますが、一部のタスクでは失敗する恐れがあります。 -
Cookie
認証タスク以外のタスクへリクエストする際に必須となります。Cookieは認証タスクを送信することで得ることができます。この後説明します。
認証タスクを実行してCookieを取得する
ではauthenticateタスクに対してPOSTリクエストを送信し、Cookieを取得しましょう。公式ドキュメントは以下を参照してください。
REST API for Oracle Cloud Infrastructure Compute Classic - Authenticate User
今回はcURLで行います。リクエストの例を以下に示します。
curl -i -X POST\ -H "Content-Type: application/oracle-compute-v3+json"\ -d '{"user":"/Compute-インスタンスID/ユーザID","password":"ユーザパスワード"}'\ https://RESTエンドポイント/authenticate/
送信するとValueで「Set-Cookie」が返ると思います。この値の内容がCookieになります。このCookieは30分間有効です。
Set-Cookie: nimbula=eyJpZGVudGl0eSI6ICJ～
取得したCookieは変数に格納しておきましょう。 公式ドキュメントに倣って格納します。 ちなみに公式ドキュメントでは得られたValueの内容すべてを保持していますが、実際はSet-Cookie内の「nimbula」キーの内容のみでも大丈夫のようです。
export COMPUTE_COOKIE='Cookieの内容'
インスタンスを取得する
認証ができたのでインスタンスを取得しましょう。インスタンスの取得の前に参照可能なコンテナを取得します。
コンテナを取得するリクエストは以下のようになります。
curl -X GET\ -H "Cookie: $COMPUTE_COOKIE"\ -H "Accept: application/oracle-compute-v3+directory+json"\ https://RESTエンドポイント/instance/Compute-インスタンスID/
送信すると、参照可能なコンテナが一覧で返ります。具体的には以下のような感じです。
"result": [ "/Compute-インスタンスID/hogefuga@atomitech.jp/", "/Compute-インスタンスID/fugahoge@atomitech.jp/" ]
この段階ではリソースの特定には至っていないので、ヘッダーのAcceptから「directory」を外しapplication/oracle-compute-v3+jsonにすると、参照可能な全コンテナに含まれる全インスタンスが詳細付きで返ってきます。 所有者に関係なく、存在する全インスタンスを取得したいときなどは、そのほうが都合がいいかもしれません。今回は特定のコンテナに含まれるインスタンスの詳細取得にしたいので、「directory」付きです。
※「directory」を外す場合、URIの最後に「/」をつけるのを忘れないでください。忘れるとリソース名の指定とみなされ404NotFoundになります。
続いてコンテナに含まれるインスタンス一覧を取得しましょう。インスタンス取得の公式ドキュメントは以下を参照してください。
インスタンスを取得したいコンテナ名をURIに含めます。リクエストは以下のようになります。
curl -X GET\ -H "Cookie: $COMPUTE_COOKIE"\ -H "Accept: application/oracle-compute-v3+json"\ https://RESTエンドポイント/instance/Compute-インスタンスID/fugahoge@atomitech.jp/
送信するとresultで配列型のインスタンス詳細一覧が返りましたね！ jsonパースすると各パラメータ値が取得できていると思います。これでインスタンス取得ができました。
インスタンス名の一覧のみが欲しい場合は、ヘッダーのAcceptに「directory」をつけてください。インスタンスのサブコンテナ名までが取れると思います。サブコンテナ名なのでリソース名ではありませんのでご注意ください。
具体的には、「directory」をつけると以下のようなものが返っていると思います。
/Compute-インスタンスID/fugahoge@atomitech.jp/TestInstance/
さらにここから、特定のインスタンスの詳細のみを取り出しましょう。サブコンテナを指定してリクエストするだけです。
curl -X GET\ -H "Cookie: $COMPUTE_COOKIE"\ -H "Accept: application/oracle-compute-v3+json"\ https://RESTエンドポイント/instance/Compute-インスタンスID/fugahoge@atomitech.jp/TestInstance/
特定のインスタンスの詳細が取れましたね！
この取得のルールはマシンイメージの取得やsshkeyの取得も同じなので、インスタンスが取れれば他のタスクも呼び出せるはずです。
ただしインスタンスは他のタスクと違ってPOSTがありません。REST APIによるインスタンスの追加方法は公式ドキュメントに手順が記載されています。ドキュメント通りにリクエストをしていけばインスタンスの作成が可能です。
REST API for Oracle Cloud Infrastructure Compute Classic
この手順をコンソールと合わせて確認しつつ踏めば一通りAPIの動きを把握できると思います。
次回は Myservices API編をお送りできたらと思います！