[Cloud, FMW, WebCenter] Oracle Documents Cloud Service - REST API

原文はこちら。
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でのフォローもどうぞ。