OCIのREST API利用入門ガイド（概要・セットアップ・実行方法）Oracle CloudのREST APIを利用した操作方法

OCIではクラウド環境の管理のため、ブラウザでアクセスできるGUI（コンソール画面）が提供されています。
そしてこのコンソール画面から行う操作のほとんどは、OCIが提供しているREST API経由でも実行が可能です。

今回はこのOCIで提供されているREST APIについて、実際に利用するまでの流れを紹介します。

REST APIという言葉の定義

始めに、REST APIとはどのようなものか、 「API」 「REST」 「REST API」 の3つの用語に分けて見ていきましょう。

APIとは

PCを操作する際、我々は視覚的に表示されたアプリケーションに対して、マウスやキーボードで操作を行います。
これらはGUI（Graphical User Interface）と呼ばれ、アプリケーションが人間向けに用意しているインターフェースです。

一方、APIは「Application Programming Interface」の略称で、アプリケーションが外部のアプリケーション向けに用意しているインターフェースです。

一言でAPIと言ってもその形式はAPIによって様々です。
特に昨今、APIと言うとネットワーク通信を介して利用するものをイメージする人が多いかもしれませんが、それはAPIの中でも「Web API」と呼ばれるものです。
例えばネイティブアプリがOSの機能を使うために呼び出したり、ローカルのアプリケーション同士でのやり取りに使ったりするものもAPIです。

RESTとは

RESTは「Representational State Transfer」の略で、設計思想の一つです。

元々提唱されたRESTは抽象的なものであり、必ずしもHTTPを使ったWeb APIの事を指す言葉では無いとされています。

しかし現実的には、RESTといえばHTTPでURLがリソースを表していてJSONが返ってきて…と考えて問題はありませんし、今回紹介する本題（OCIのREST APIの紹介）とずれてしまうので、ここでは「世間一般で利用されているWebサービスのREST」の説明とさせてください。

WikipediaではRESTの原則について以下のように紹介されています。

• ステートレスなクライアント/サーバプロトコル
• すべての情報（リソース）に適用できる「よく定義された操作」のセット
• リソースを一意に識別する「汎用的な構文」
• アプリケーションの情報と状態遷移の両方を扱うことができる「ハイパーメディアの使用」
  引用：Representational State Transfer 『ウィキペディア (Wikipedia): フリー百科事典』 

これらはいくつかあるRESTの定義の中でも特に重要な項目として挙げられた4つで、実際にWebサービスで提供する場合にはそれぞれ以下のように適用されます。

REST APIとは

ここまででRESTが何なのかご理解いただけたと思います。

それでは、今回の主題であるREST APIとは何かと言うと、言葉の通りREST仕様に則って設計されたWeb APIのことです。
昨今公開されているWeb APIの大半はこのREST APIとして実装されています。

システムがWeb APIを提供しようとした際、そのシステムが独自に設計して定義したAPI仕様でWeb APIを作ってしてしまうと、そのAPIを使う人は、まずAPI仕様を読み込んで理解して、API仕様に合わせた実装をして、と非常に大変です。
そこで、高い柔軟性と拡張性を持ち、世界的に共有されているRESTに則った設計でAPIを実装することで、APIを提供する側も利用する側も煩雑な設計や説明を省略することができます。

OCIで用意されているREST APIとは

OCIを管理するためにブラウザからアクセスする画面をOCIコンソールと言います。
このOCIコンソールで行う操作の大半は、API経由で実行することができるようにREST APIが公開されています。
（OCIコンソールの操作でも実際にこのREST APIが使われています）

なお、RESTの原則は以下のような形で採用されています。

• Cookieを利用しないHTTP通信（ステートレス）
• URLで操作対象のリソースを表す
• HTTPメソッドで操作を表す（GET・POST・DELETE等）
• データ形式はJSON

実際に公開されているAPIの一覧とその利用方法、公式ドキュメントのAPI Reference and Endpointsをご確認ください。

Oracle CloudのREST APIを実行する方法

言葉の定義について理解できたところで、実際にOCIのREST APIを使ってみましょう。
OCI REST APIを実行するには、大きく分けて3つの方法があります。

方法 1. OCI CLIを使ってREST APIを実行する

PCやサーバにOCI REST API用のCLI（コマンドライン・インターフェース）をインストールして利用することで、APIのURLやリクエストを自分で一から作成せずにAPIを利用することができます。

OCI CLIはWindows・Linux・Mac等のOSに対応しており、簡単な手順でセットアップすることができます。

CLIはその名の通りコマンドラインで実行するツールなので、簡単にシェルスクリプトに組み込むような使い方ができます。

方法 2. SDKを使ってプログラムに組み込む

OCI REST APIをプログラムから簡単に扱うために、オラクル社から様々なプログラミング言語でのOCI SDKが提供されています。
2023年7月時点で、Java・Python・TypeScript・JavaScript・.NET(C#)・Go・RubyのSDKが提供されており、全てオープンソースです。

公式SDKのため信頼性も高く、何よりも実装が圧倒的に快適になるので、プログラムからOCI REST APIを利用するならばSDKの利用をおすすめします。

それぞれのSDKとそのリファレンスは公式ドキュメントの ソフトウェア開発キットおよびコマンドライン・インタフェース からご確認ください。

方法 3. 自分でHTTPリクエストを作る

CLIもSDKも使わない場合、自分でHTTPリクエストを作成してREST APIを呼び出すことになります。

これはOCI REST APIの仕様に則った形式で署名を作成する必要があり、なかなかに大変です。
詳しい署名方法については公式ドキュメントの リクエストの署名 をご確認ください。

この方法は、ここまでで紹介した方法を使うことができない環境の場合に、やむを得ず使うぐらいでしょう。
基本的にはSDKやCLIを利用した方が確実で効率的です。

OCI CLIの使い方

それでは、ここまで紹介したOCI REST APIの実行方法の中から、今回は最も手軽なOCI CLIの使い方について紹介していきます。

OCI CLIを使うには2つの方法があります。

方法 1. OCIクラウドシェルを利用する

OCIクラウドシェルとは、OCIコンソールから利用できるブラウザベースのCLIツールです。
OCIコンソールのメニューから接続するとクラウド環境に軽量なVMが立ち上がり、その中でBashシェルが実行できます。

ここでのポイントは、このOCIクラウドシェルには初めから様々なツールがインストールされており、
OCI CLIについてもインストール済み、さらにサインインしたユーザーでの認証のセットアップまで済んでいるという点です。
これにより、クラウドシェルを起動したらすぐにOCI CLIのコマンドを実行することができます。

ただし注意しなければいけない点としては、クラウドシェルはあくまで一時的な作業スペースなので、
ストレージは5GB固定で、長期間利用しない場合にはストレージは削除されます。
そのため、例えば出力したファイルは別途Object Storageへ転送するなどの考慮が必要です。

クラウドシェルでのOCI CLIは、簡単なデモやちょっとした作業の際に利用すると良いでしょう。

方法 2. PC・サーバにセットアップする

2つめの方法は手元のPC端末やサーバ上からOCI CLIを実行する方法です。 OCI CLIをツールに組み込んだり繰り返し実行したりするようならば、クラウドシェルよりもこちらが一般的でしょう。

PCやサーバでOCI CLIを使えるようにしよう

クラウドシェルの方は特にセットアップも無いので、ここからはPCやサーバにOCI CLIをインストールして実行するまでの流れを紹介します。

OSによる差異はありますが、PC端末でもサーバでも手順は変わりません。

OCI CLIをインストールする

OCI CLIをインストールする方法は、それぞれのOSごとに以下のような方法が用意されており、
どれも簡単な手順でインストールまで完了することができます。

• 【Windows】 インストーラPowerShellスクリプト
• 【Oracle Linux】 yum/dnf（パッケージ管理システム）
• 【その他Linux・Unix】 インストーラシェルスクリプト
• 【Mac】 Homebrew（パッケージマネージャー）

その他、手動・オフラインでインストール方法も提供されています。
各OSでの実際の手順や最新の情報は、公式ドキュメントのクイックスタート内、 CLIのインストール をご確認ください。

OCI CLIをセットアップする

OCI CLIのインストールが完了しても、そのままではまだCLIを利用することはできません。
利用するための設定が必要です。

大まかな流れとしては以下の通りです。

1. APIを実行するIAMユーザーを作成
2. セットアップ用の各種情報を収集
3. OCI CLIでoci setup config を実行、集めた情報を入力
4. 生成されたAPIキーペアの公開鍵をOCIコンソールでIAMユーザーに登録

こちらも実際の手順は公式ドキュメントのクイックスタート内、 構成ファイルの設定 にセットアップ方法が記載されているのでそちらをご確認ください。

OCI CLIを使ってREST APIを実行してみる

ここまででOCI CLIを使う準備が完了しました。
それでは実際にOCI CLIを使ってOCIのREST APIを実行してみましょう。

まずは試しに以下のコマンドを実行します。

正常に実行できれば、有効なコンパートメントの一覧がJSON形式で返ってきます。

このようにOCI CLIを使えば、oci ～の形でコマンドを実行するだけで様々なリソースに対して、作成・参照・更新・削除等の操作を簡単に行うことができます。
ブラウザのOCIコンソール上から実行可能な操作であれば大半は対応するREST APIと、そのCLIコマンドが用意されているのでOCI CLI Command Referenceから確認してみてください。

なお、CLIでも内部ではREST APIを実行しているので、レスポンスはREST APIと同じになります。
CLIのドキュメントページにはレスポンスについての記載が無いので、レスポンスについて知りたい場合はAPI Reference and Endpointsで対応するAPIのページを確認しましょう。

その他注意点：APIの実行権限

CLIを利用する場合でもSDKを利用する場合でも、最終的にはREST APIを実行するということなので、必ずOCIのIAM（Identity and Access Management）ユーザーでの認証が必要になります。

とりあえずのお試しであればOCIコンソールにサインインしているユーザーをそのまま使ってもいいですが、実運用では別途API実行用のユーザーを作成し、適切な権限を付与した方が良いでしょう。

必要なポリシー設定については ポリシー・リファレンス に記載されています。
こちらを参照し、実行するAPIに必要なポリシーをユーザーグループへ設定してください。

おわりに

今回はOracle CloudのREST APIとCLIでの実行方法について紹介しました。

実際のところ、APIを実行する際にはCLIかSDKを利用することになるため、HTTPリクエストを自力で作成して直接APIを実行するようなことはあまり無いと思います。
しかし、実行可能な処理やそのパラメータやレスポンスについて把握するためには、APIリファレンスを参照することになります。
CLIやSDKを利用する場合においても実際にどのAPIが実行されるのかは意識しておきましょう。

OCI CLIは実行環境のセットアップも非常に簡単です。
今回は紹介できませんでしたが、SDKについても各言語で簡単に導入して利用できる環境が用意されています。

システムでのOCIとの連係から、日々の業務で繰り返し行うOCI関連作業の自動化まで、色々な用途にOracle CloudのREST APIを活用してみてください。

システムエグゼでは、OCIを活用した基盤構築やデータ移行、アプリケーション開発といった多岐にわたるサービスを展開しています。ご興味のある方はぜひシステムエグゼまでお問い合わせください。