原文はこちら。
https://blogs.oracle.com/OracleCloud4Developers/entry/oracle_documents_cloud_service_and
Oracle Documents Cloud Serviceでは、クラウドで直接REST APIを使ってファイルやフォルダ、ユーザーの管理ができる一連の機能を提供しています。
Oracle Documents Cloud Service
https://cloud.oracle.com/documents
この記事ではAPIの利用例をご紹介します。今回は、Node.jsでの操作についてご紹介します。
メインコンテナ、メインコンテナの子、特定のフォルダやファイルに関する情報にアクセスします。また、特定のファイルの内容を取得したり、アイテムを削除したり、項目の名前を変更したりします。これらはすべてNode.jsのExpressフレームワークを使用して構築したWebアプリケーションを介して実行します。
今回の例を実施するにあたっての前提条件は以下の通りです。
- Node.js
- Expressフレームワーク
- 結果表示のためのテンプレートエンジン
- 開発環境に含まれる、Node.js用RESTクライアント
- スクリプト記述用テキストエディタ
- APIのエンドポイントURL
- 認証のための資格証明（ユーザー名とパスワード）
- サービスのメインコンテナに配置する2個のテキストファイル
アプリケーションの全貌は下図をご覧ください。
Node.js自身がHTTP Serverの機能を持っており、ルーティング、テンプレート化が簡単という理由から、Expressフレームワークを使うことにしました。
HTTP Serverが受け取ったリクエストは、REST APIと対話する適切なスクリプトにルーティングされます。スクリプトがAPIからレスポンスを受け取ると、即座に描画テンプレートを使ってブラウザに対してレスポンスを描画します。
テンプレートエンジンとしてEJSを、専用RESTクライアントとしてnode-rest-clientを選択しました。これらの2種類はExpressフレームワークとともに以下のコマンドを実行し、node package managerを使ってインストールすることができます。
- npm install ejs
- npm install node-rest-client
- npm install express
アプリケーションサーバは非常に基本的なものです。Expressフレームワークと、テンプレートエンジン、2個のルーティングを設定します。最初のルーティングはインデックスページ、もう一つはREST APIへのHTTPリクエストを処理するページです。サーバーはポート番号3000でリクエストを受け付けます。
APIのエンドポイントURLを知るため、サービスのWebアプリケーションにログインします（cloud.oracle.comでデータセンターを選択、アイデンティティ・ドメイン、ユーザー名、パスワードを入力、Documentsクラウドサービスを選択して、サービスのコンソールを開きます）。
Webアプリケーションにリダイレクトされると、/home/nameascを/apiで置き換えることでAPIのエンドポイントを取得できます。WebアプリケーションのURLは以下のような構成になっています。
https://<account>-<identity domain>.documents.<datacenter>.oraclecloud.com/documents/home/nameasc
例として、実際のURLが以下のようであれば
https://foo-bar.documents.us.oraclecloud.com/documents/home/nameasc
APIのエンドポイントURLは以下のようになります。
https://foo-bar.documents.us.oraclecloud.com/documents/api
今後、このドメインを例にして説明を進めます。
APIの認証に使うユーザー名とパスワードはWebアプリケーションログイン時と同じものですが、この場合、アイデンティティ・ドメインは不要です。
前提条件として記載したように、サービスのメインコンテナに2個のテキストファイルを配置することを忘れないでください。
サービスのフォルダ構成を明確にするために、下図をご覧ください。
実際のREST APIとの通信を司るスクリプトには2個のハンドラがあります。一つはGETリクエスト用、もう一つは自身へのPOSTリクエスト用です。
GETリクエストの場合、ボタンを持つフォームを含むテンプレートをレンダリングしますが、POSTリクエストの場合、さらにJSON形式で認証のための資格証明を含むテキストファイルを開き、その内容を解析してオブジェクトに格納します。
ファイルの中身は、次のような感じになります。
{"user" : "john.doe@company.com", "password" : "supersecret"}
続いて、基本認証を使ってAPIに対し認証するための組み込み機能を提供するnode-rest-clientが必要です。
var RESTClient = require('node-rest-client').Client;
restClient = new RESTClient({user : credentials.user, password : credentials.password});
その後、ファイルはAPIのエンドポイントURLを設定します。
var apiURL = "https://foo-bar.documents.us.oraclecloud.com/documents/api";
最後に、実際のリクエストをREST APIに対して送信する機能が含まれています。
//perform the api request
restClient.get(apiURL, function(data, apiResponse){
//set up params to be passed into the template
var params = {
respData: ((typeof data) == 'object') ? JSON.stringify(data) : data
}
//send HTTP response (render template)
res.render('rest', params);
});
ここで説明したPOSTハンドラはHTMLフォームが発行されたタイミングで呼び出されます。
REST APIへのリクエスト発行の最終ステップでNodeサーバーを起動しています。
この例はローカルのUbuntu上にインストールされたNode.jsを使っています。開始する場合には、ターミナルを開き、以下のコマンドを実行します。
sudo nodemon <path file.js="" server="" to="">
個人的には、スクリプト変更時に自動的にサーバーを再起動してくれ、手作業による再起動が不要なため、nodemonを使っています。
サーバーが起動したら、ブラウザでhttp://localhost:3000にアクセスすると、アプリケーションのインデックスページが開きます。これはこの記事の最初に説明した2個目のルートです。
2個目のルートへアクセスすると、フォームを含むテンプレートを表示するGETハンドラを起動します。フォームをルートに送信すると、POSTハンドラが呼び出され、スクリプトがAPIにアクセスします。APIからレスポンスが返ると、フォームの同じテンプレートを使って結果を表示します。
注意いただきたいのは、APIへの最初のリクエストはAPIの基本パスへのGETリクエストです。APIのデータフォーマットのデフォルトはJSONで、以下のような形式です。
{items: [{"version": "1.0", "isLatest": false}, {"version": "1.0", "isLatest": true }]}
メインコンテナに関する情報を入手するために、スクリプトを編集し、"/folders/self"を付加してapiURL変数を変更します。URLを以下のような感じに変更します。
https://foo-bar.documents.us.oraclecloud.com/documents/api/folders/self
上記URLへのGETリクエストを実行すると、APIはメインコンテナの情報をレスポンスとして返します。メインコンテナの子の情報を取得するには、エンドポイントURLの"/self"を"/items"に置き換えます。変更した結果、URLは以下のようになります。
https://foo-bar.documents.us.oraclecloud.com/documents/api/folders/items
上記URLへのGETリクエストを実行すると、APIはメインコンテナの子、つまりファイルやフォルダの情報をレスポンスとして返します。今回の場合、子は事前にメインコンテナにアップロードした2個のファイルです。
［注意］
"/folders/items"パスを使ってメインコンテナの子にアクセスします。メインコンテナに含まれるすべてのフォルダとファイルはおのおののIDを使ってアクセスします。
続いて、ファイルの一つの情報を取得しましょう。このために、ファイルのIDが必要です。このファイルのIDは先ほどメインコンテナの子の問い合わせの際に入手しました。この操作で利用するエンドポイントURLは以下のようになります。
https://https://foo-bar.documents.us.oraclecloud.com/documents/api/files/<file id>
上記URLに対するGETリクエストを実行すると、APIはファイルに関する情報（作成日、ファイル名、IDなど）を返します。ファイルの中身を取得したい場合には、URLに"/data"を付加します。URLは以下のようになります。
https://foo-bar.documents.us.oraclecloud.com/documents/api/files/<file id>/data
［注意］
ファイルの内容を問い合わせる際、APIの応答はJSON形式ではなく、ファイルの中身のみを含むプレーンテキスト形式です。
上記のURLに対しGETリクエストを発行すると、APIはファイルの内容を返します。以下はその例です。
"Hello Docs. This is file1's content"
開発、テストフェーズにて、このWebアプリケーションを使ってAPIが返す情報を常にダブルチェックすることができます。
ここまでで、APIを使って情報を取得しましたが、続いての例ではファイルを削除します。
アイテムの削除はアイテムの情報を入手するのと同じぐらいシンプルで、単にAPIへのリクエストメソッドをDELETEに変更すればよいのです。URLはアイテムの情報を入手した際に使ったものと同じです（先ほど追加した"/data"のことは忘れています）。RESTクライアントを使って、この形式でDELETEリクエストを送信することができます。
client.delete(requestPath, function(data, response){
// do something with the response
});
これらの修正をスクリプトに対して実施し、リクエストをAPIに送信すると、操作結果を含むレスポンスが返ってきます。以下はその例です。
{ "errorCode" : "0" … }
これはファイルの削除が成功したことを示しています。
最後の例として、既存のリソースの名前を変更します。今回は、メインコンテナに残る別のファイルを対象にします。
ファイル名を変更するには、PUTリクエストをファイルのパスに対し発行しますが、ファイルの新規名称を含む追加のパラメータを指定する必要があります。URLのパターンはファイル情報を入手したときと同じです。以下はコード例です。
var args = { parameters:{"name" : "changed-name.txt"} };
client.put(requestPath, args, function(data, response){
// do something with the response
});
PUTリクエストをこのファイルのURLパスに送信すると、APIはファイルの情報を返します。その情報には新しいファイル名が含まれています。
先ほど実施したように、Webアプリケーションを使ってファイル名が正しく変更されていることを確認できます。
REST APIの機能に関する詳細情報は、REST APIリファレンスをご覧ください。
Developing for Oracle Documents Cloud Service
Oracle Documents Cloud Service REST API Reference
http://docs.oracle.com/cloud/latest/documentcs_welcome/WCCCD/GUID-205EBBB4-F8D5-4FD0-B82F-210960F5C6F7.htm#WCCCD3724
