原文はこちら。
https://blogs.oracle.com/OracleCloud4Developers/entry/oracle_documents_cloud_service_rest2
Oracle Documents Cloud Serviceは一連の機能を提供します。例えばクラウドのファイルやフォルダ、ユーザーの管理を直接REST APIで実施することができます。
Oracle Documents Cloud Service
https://cloud.oracle.com/documents
このチュートリアルは基本的なAPI利用のサンプルから構成されていますが、説明している内容をより一層理解するためには、まだごらんになったことがないのであれば、Oracle Documents Cloud Serviceの概要を一読してください。
Oracle Documents Cloud Service
https://blogs.oracle.com/OracleCloud4Developers/en/entry/learning_short_cuts_for_oracle
このショーケースでは、Node.jsでアイテムを操作する方法をご紹介します。メインコンテナ、メインコンテナの子、特定のフォルダやファイルの情報にアクセスします。また、特定のファイルの中身を取得したり、アイテムの削除、アイテム名称の変更を実施します。最後に、APIのレスポンスデータ形式をJSONからXMLに変更する方法を確認します。
この演習に先立ち、以下のものが必要です。
- Node.js
- HTTPクライアントもしくは開発環境内のNode.js専用のRESTクライアント
- スクリプトを記述するためのテキストエディタ
- APIのエンドポイントURL
- 認証のための資格証明（ユーザー名とパスワード）
コマンドラインからNode.jsを立ち上げますが、これはNode.jsサーバをお持ちであれば同じことを実施します。
クライアント用に、専用のRESTクライアントを使うことを推奨します。今回はnode-rest-clientを使います。
node API REST client
https://www.npmjs.com/package/node-rest-client
APIのエンドポイントURLを決定するために、Documents Cloud ServiceのWebアプリケーションにログインします。Webアプリケーションのドメイン名はAPIのドメイン名と同一です。ドメイン名がわかると、そのドメイン名に
“/documents/api”を連結してください。ドメイン名は以下のような構成です。
https://< account >-< identity domain >.documents.< datacenter >.oraclecloud.com
例として、実際のドメイン名は次のような感じです。
https://foo-bar.documents.us.oraclecloud.com
ここから、エンドポイントURLは
https://foo-bar.documents.us.oraclecloud.com/documents/api
ということがわかります。
今後、このサンプルドメインを参考として利用することにします。
サービスにサインアップすると、認証資格証明を入手します。
フォルダ構造を説明するため、以下の図をご覧ください。
Node.jsスクリプトは認証資格証明をJSON形式で持つファイルを開き、その内容をパースしてオブジェクトに格納します。
ファイル中の文字列は以下のようになっています。
{"user" : "john.doe@company.com", "password" : "supersecret"}
パースされたオブジェクトをこの形式で定数リストに配置します。
var consts = {
credentials : JSON.parse(file.toString()),
url : "https://foo-bar.documents.us.oraclecloud.com",
apiPath : "/documents/api",
apiVersion : "/1.1",
mainFolder : "/folders/self",
mainFolderItems : "/folders/items"
}
このコードスニペットをスクリプトに追加し、RESTクライアントを取得します。
var Client = require('node-rest-client').Client;
サービスに対して身元を証明するため、基本認証を使います。RESTクライアントは基本認証のための組み込み機能を提供しています。以下のようにクライアントを初期化しましょう。
var options_auth={user : consts.credentials.user, password : consts.credentials.password};
client = new Client(options_auth);
今やるべきことは、URLを作成し、リクエストを発行することです。まずはメインコンテナの情報を取り出します。
var requestPath = consts.url + consts.apiPath + consts.apiVersion + consts.mainFolder;
この文字列連結の結果、以下のような文字列ができあがります。
https://foo-bar.documents.us.oraclecloud.com/documents/api/1.1/folders/self
［注意］メインコンテナには“/folder/self”を使ってアクセスします。メインコンテナに含まれるフォルダやファイルは各々のIDを使ってアクセスします。
メインコンテナの情報を取得するため、GETリクエストを発行します。RESTクライアントで、以下のようにリクエストを作成します。
client.get(requestPath, function(data, response){
// do something with the response
});
APIはコンテナの情報を伴って応答を返します。
コンテナの子の情報にアクセスしたい場合、URLパスを変更し、“folders/self”ではなく“/folders/items”に対しリクエストを送信する必要があります。URLパスは以下のような感じになります。
https://foo-bar.documents.us.oraclecloud.com/documents/api/1.1/folders/items
これでメインコンテナのすべての子（各々のIDを含む）の情報を取得できます。
続いて、IDを知っている前提で、一つの子の詳細情報を取得しましょう。この場合、子はフォルダであり、リクエストのパスは以下のようになります。
https://foo-bar.documents.us.oraclecloud.com/documents/api/1.1/folders/< folder id >
新たにリクエストのURLパスを作成したら、メインコンテナを問い合わせたときのように、GETリクエストを発行すると、先ほどのメインコンテナのレスポンスと同様、レスポンスでフォルダの情報が返ってきます。
フォルダではなくファイルの情報を取得したい場合、以下のようなリクエストURLを使います。
https://foo-bar.documents.us.oraclecloud.com/documents/api/1.1/files/< file id >
ファイルの中身を取得する場合、単に"/data"をURLに追加します。URLはこんな感じになります。
https://foo-bar.documents.us.oraclecloud.com/documents/api/1.1/files/< file id >/data
アイテムの削除の場合、アイテムの情報を入手できればよいので、リクエストのメソッドをDELETEに変更します。URLはアイテムのパスで、アイテムの情報を入手するときに試用したものと同じです（先ほど追加した"/data"は削除しておきましょう）。RESTクライアントを使って、このような形でDELETEリクエストを送信することができます。
client.delete(requestPath, function(data, response){
// do something with the response
});
最後に、ファイル名を変更してみましょう。
ファイル名を変更する場合、アイテムのURLに対しPUTリクエストを発行し、その際、変更後のファイル名を含む追加パラメータを指定します。コードは以下のようになります。
var args = {
parameters:{"name" : "changed-name.txt"}
};
client.put(requestPath, args, function(data, response){
// do something with the response
});
取り上げた状況の各々で、APIはJSON形式で通常は応答を変えいます。しかし、JSONではなくXML形式で応答を返すよう操作することができます。XMLで応答を返すようにするには、以下のようにリクエストにヘッダを追加します。
var args = {
headers:{"Accept": "application/xml"}
};
client.< request method >(requestPath, args, function(data, response){
// do something with the response
});
REST APIの機能に関する詳細は、以下のREST API Referenceをご覧下さい。
Oracle® Cloud 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
ここまでご覧いただきありがとうございます。この記事が皆様のお役に立つことを願っております。フィードバックや将来の例に関する提案、質問があれば、（原文の）コメント欄にどうぞ。
さらに、
Twitterや
LinkedInでのフォローもどうぞ。
