2015年5月27日

[Database, JavaScript] node-oracledb 0.6.0 is on NPM (Node.js driver for Oracle Database)

原文はこちら。
https://blogs.oracle.com/opal/entry/node_oracledb_0_6_0

Node-oracledb 0.6.0がNPMからご利用いただけるようになりました。
Node-oracledb
https://www.npmjs.com/package/oracledb
Oracle Database Node.jsドライバは高パフォーマンスなNode.jsアプリケーションにパワーを与えます。
このリリースで、一つ変更が入りました。node-oracledbはNode.js 0.10、0.12、そしてio.jsを使ってビルドされています。 Richard Natalがサポートを追加してくれました。GitHubプルリクエストに感謝しています。
Richard Natal
https://github.com/BigousBuild with NaN #43
https://github.com/oracle/node-oracledb/pull/43
node-oracledbに関する詳細はnode-oracledbのGitHubページからどうぞ。
Oracle Database driver for Node.js
https://github.com/oracle/node-oracledb

2015年5月19日

[SOA/BPM, FMW] Intiatorタスクの前にサービスアクティビティを配置する

BPMに関する質問が届いていたのでご紹介します。

Q) Initiatorユーザーアクティビティに初期値を設定したいのだけど、データベースから取得した値を使いたい。それって可能なの?
A) 11gと12cではやり方が違いますが、実現できます。


11gまで(11.1.1.9も含みます)

Initiatorに対応する画面内でManaged Beanを使ったり、ユーザーアクティビティのデータ・アソシエーションでXPath式を使ったりする必要があります。
Initiatorの前には、スクリプトタスクのみ配置可能という制限があるため、Database Adapterを使うなど、サービスコールを使うことはできません。もし配置すると、ブロッカーに成り得ないという警告メッセージがBPM Studio(JDeveloper)で出てきます。


12c(12.1.3)から

12c(12.1.3)では、その制限がなくなっています。


つまり、上記のような配置をしても動作する、ということですね。
動作確認のため、次のようなサンプルアプリケーションを作ってみました。このコンポジット・アプリケーションは、BPMNプロセスとユーザータスクで構成されており、dbRefernceというサービスを参照しています。


このdbReferenceというサービスはDatabase Adapterを介して、データベースに定義したFunctionを呼び出しています。このFunctionは、簡単のため実行開始時の日時をIDとして取得するようにしてあります。
# もちろんXPath式を使えばこの値は簡単に取得できますが、あくまでもサンプルです。
create or replace function getID
RETURN VARCHAR2
IS
BEGIN
  RETURN to_char(systimestamp,'yyyy/mm/dd hh24:mi:ss.ff3');
END;
先ほどのBPMプロセス内のサービスタスクで、データアソシエーション(データマッピング)し、Functionを呼び出した結果を取得します。


Initiatorタスクに、取得した値を渡すよう、データアソシエーションを設定しておきます。


ユーザータスクの画面は出来合いのものを使うことにして、デプロイしました。
BPM Workspaceから実行してみます。
[アプリケーション]からプロセスを起動してみると・・・


dbReferenceサービスを使って取得したデータを表示しているようです。
Fusion Middleware Controlからも確認します。


上図の赤枠で囲んだ部分をクリックすると、データの入出力がXML形式で表示されます。その中身がこちら。
<auditQueryPayload auditId="5030" ciKey="40062" xmlns="http://xmlns.oracle.com/bpmn/engine/audit">
   <serviceOutput>
      <element name="OutputParameters" isBusinessIndicator="false">
         <value>
            <![CDATA[<OutputParameters xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://xmlns.oracle.com/pcbpel/adapter/db/sp/dbReference">
   <GETID>2015/05/19 20:11:51.597</GETID>
</OutputParameters>
]]>
         </value>
      </element>
   </serviceOutput>
   <dataState>
      <dataObject name="dataObject1" isBusinessIndicator="false">
         <value>
            <![CDATA[<dataObject1 xmlns:def="http://www.w3.org/2001/XMLSchema" xsi:type="def:string" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">2015/05/19 20:11:51.597</dataObject1>
]]>
         </value>
      </dataObject>
   </dataState>
</auditQueryPayload>
GETIDというFunctionを呼び出した結果が表示されていることがわかります。

[Database] Create a PDB directly from a stand-alone database?

原文はこちら。
https://blogs.oracle.com/UPGRADE/entry/create_a_pdb_directly_from

データベースをOracle Single-/Multitenantに移行するための隠された機能がドキュメントに記載されています。

NON$CDBオプションを使ってリモートクローンを実行する

ドキュメントを読んでみると、ドキュメントではあまり言及していません。例えば要件や正しい構文、例がありません。
Oracle® Database SQL Language Reference 12c Release 1 (12.1)
Database SQL Language Reference
CREATE PLUGGABLE DATABASE
http://docs.oracle.com/database/121/SQLRF/statements_6010.htm#SQLRF55686
Oracle® Database SQL言語リファレンス 12cリリース1 (12.1)
CREATE PLUGGABLE DATABASE
http://docs.oracle.com/cd/E57425_01/121/SQLRF/statements_6010.htm#SQLRF55686
FROM 句までスクロールしてみましょう。
http://docs.oracle.com/database/121/SQLRF/statements_6010.htm#SQLRF55801(英語)
http://docs.oracle.com/cd/E57425_01/121/SQLRF/statements_6010.htm#SQLRF55801(日本語)

... FROM NON$CDB@dblink ... このオプションは、スタンドアロンデータベースをプラグインし、プラガブルデータベースにすることができる、ということのようです。面白そうですね、やってみましょう。

Test 1 - Oracle Database 11.2.0.4をプラグインしてみる

ドキュメントにはどのリリースに限られているのか記載がないので、まずはシンプルにOracle Database 11.2.0.4で試してみました。
  1. 既存のCDBから11.2.0.4データベースに向けてデータベースリンクを作成しました。
  2. SOURCEDB を読取り専用モードで起動しました。
  3. プラガブルデータベースをSOURCEDBから作成しようとしました・・・が、失敗しました。
    SQL> create pluggable database PDB1 from non$cdb@sourcedb;
    create pluggable database PDB1 from non$cdb@sourcedb
                                                 *
    ERROR at line 1:
    ORA-17627: ORA-28002: the password will expire within 7 days
    ORA-17629: Cannot connect to the remote database server

Test 2 - ファイルシステムのOracle Database 12.1.0.2をプラグインしてみる

Thanks to Tim Hall のブログエントリのおかげで、謎が解けました。
Multitenant : Clone a Remote PDB or Non-CDB in Oracle Database 12c (12.1.0.2) - Cloning a Remote Non-CDB
http://oracle-base.com/articles/12c/multitenant-clone-remote-pdb-or-non-cdb-12cr1.php#cloning-remote-non-cdb
まず、Test 1が失敗した理由は単純なことで、Oracle Database 11.2.0.4でCREATE PLUGGABLE DATABASEの権限を持つユーザーを設定していなかったためです。しかしこれは後ほどわかった要件です。
  1. SOURCEDBにPluggable Databaseを作成する権限を有するユーザーが必要です。
    GRANT CREATE PLUGGABLE DATABASE TO sourcedb_user;
  2. SOURCEDBをシャットダウンした後に、読取り専用モードで立ち上げます。
    SHUTDOWN IMMEDIATE;
    STARTUP OPEN READ ONLY;
  3. CDBからSOURCEDBに向けてデータベースリンクを作成します。
    CREATE DATABASE LINK sourcedblink
    CONNECT TO sourcedb_user IDENTIFIED BY password USING 'upgr12';
  4. ここまでの準備のあと、スタンドアロンのUPGR12データベースからプラガブルデータベースを作成します。
    CREATE PLUGGABLE DATABASE pdb_upgr12 FROM NON$CDB@sourcedblink
    FILE_NAME_CONVERT=('/oradata/UPGR12','/oradata/CDB2/pdb_upgr12');
  5. しかし、新たに作成したPDBのステータスをチェックすると、OPENの状態ではあるものの、RESTRICTモードでしかないことがわかるはずです。そのため、noncdb_to_pdb.sqlを実行する必要があります。新規作成したPDBに接続し、スクリプトを実行します。
    ALTER SESSION SET CONTAINER=pdb_upgr12;
    @?/rdbms/admin/noncdb_to_pdb.sql

まとめ

このコマンドを使うと、簡単にスタンドアロンデータベースをコンテナデータベースにプラグインすることができますが、以下のような制限事項があります。
  • 移行元のデータベースは少なくともOracle Database 12.1.0.1以上でなければならない
  • 移行元のデータベースは同一OSプラットフォーム上になければならない
  • 移行元のデータベースはコンテナデータベースと同一バージョンでなければならない
  • noncdb_to_pdb.sqlスクリプトの実行が必要
最後に、DBMS_PDB.DESCRIBEを使ってXMLマニフェストファイルを作成するという特別なステップを回避できることが唯一の簡略化のように見えますが、それ以外では特にメリットが見いだせません。

[Java] GlassFish Images on Docker Hub

原文はこちら。
https://blogs.oracle.com/theaquarium/entry/glassfish_images_on_docker_hub

最前線のJava EE開発者やGlassFishユーザーの皆様にすてきなお知らせがあります。新規リリースおよびまもなくリリースされるものを簡単に試すことができるよう、GlassFishアプリケーションサーバのイメージ2個をDocker HubにPushしています。
Docker Registry (GlassFish)
http://registry.hub.docker.com/u/glassfish/

GlassFish Nightly Builds

このイメージは最新のGlassFishのビルドをベースにしています。新たなビルドが出来ると更新されます。試してみたい場合、以下のように実行します。
# docker run -ti -p 4848:4848 -p 8080:8080 glassfish/nightly
asadmin-consoleが立ち上がりますので、start-domainを使ってドメインを起動します。
asadmin> start-domain
コンソールには、 http://localhost:4848 でアクセスします。デフォルトの管理者ユーザ名とパスワードは以下の通りです。
user=admin / password=glassfish

GlassFish Ozark - MVC RI

このイメージはJava EE 8プラットフォームに加わる予定の新たな仕様であるMVC 1.0を実行するために必要な変更を使って修正されたGlassFish 4.1です。このイメージの実行のためには以下のコマンドを実行します。
# docker run -ti -p 8080:8080 glassfish/ozark
これでGlassFishが起動され、Ozark Samplesアプリケーションがデプロイされますので、 http://localhost:8080 で試してみてください。

DockerコンテナのGlassFishで楽しんでください。

2015年5月18日

[WLS, FMW] Node Manager: WebLogic’s Most Misunderstood Feature

原文はこちら。
https://blogs.oracle.com/oracleuniversity/entry/node_manager_weblogic_s_most

By Brad Herren, Senior Principal Instructor, Oracle University
1週間のWebLogic Serverの研修期間中100問の質問をもらうとすれば、そのうちの75個はNode Managerに関するものです。
これは非常に興味深いことです。WebLogic Serverの経験がある方が研修に来られるのですが、Node Managerが何者か、何をするものかをご存じないのです。
Node Managerに対するよくある誤解は、実はNode Managerは本来できることよりももっと機能がある、と思っていたり(ある人は本来の機能の半分もできないと思っていたり)されている、というところにあります。基本的にNode Managerを使ってサーバを起動することができます。サーバの停止時にも利用できます。
Node Managerの価値は、サーバを起動し、サーバがクラッシュした場合、またはサーバがある理由で障害が発生した場合に、自動的に障害が発生したサーバを再起動する、というところにあります。

Make a WebLogic domain interact with Node Manager: 11g versus 12c

複数のホストが存在する環境、例えば、2個のコンピュータに対してWebLogic Serverをインストールし、両ホストにまたがるドメインを構成したとしましょう。
WebLogic Serverの管理サーバで動作するアプリケーションである管理コンソールより、管理サーバはリモートホストの状態を取得することができます。これを実現するためにNode Managerユーティリティを使います。
マルチホスト環境では、Node Managerを両ホストに立てます。例えばHost01のNode Manager、Host02のNode Managerがポート番号5556で動作するような感じです。そして再度、デフォルトの設定を使ったと仮定します。この場合、両Node Managerは各ホストに固有です。WebLogic Server 11gではそうでした。

11g Configuration

これに対処するための方法が12cで導入されました。具体的にはNode Managerをドメイン固有に配置できるようになりました。WebLogic Homeから実行するのではなく、Node ManagerはDomain Homeから実行します。WebLogic Homeから実行するために使われるものと同じJVMではあるものの、Node Managerをドメイン固有にして、Node Managerと対話するようドメインを構成できます。

12c Configuration

Failed servers and stuck threads

Node Managerを使うと、スタックしたスレッド(10分以上経過しているスレッド)やOut of Memory例外が原因で障害が発生したサーバを支援することができます。スタックしたスレッドが問題のあるコードが原因で発生した場合、WebLogic Serverを構成して、事前定義済みのスタックスレッドの個数を超えた時点で、サーバ自身を"kill"(停止)させることができます。
Node Managerはサーバを再起動して問題を解決しようとします。Webinarで、Node Managerがサーバを起動する方法、障害が発生したサーバを再起動する方法をご覧頂けます。無料のシミュレーションアプリケーション(StuckThreadForFree)を使い、簡単なプロセスの停止とスタックしたスレッドを持つサーバを作成し、Node Managerに障害が発生したサーバを再起動させることができます。

この記事で説明したように、Node Managerを使ってサーバの起動/再起動/シャットダウンの流れを紹介するWebinarに参加されることを願っています。このWebinar(WebLogic's Most Misunderstood Feature)は、Oracle Learning Streamsからご覧頂けます。
WebLogic's Most Misunderstood Feature (Oracle Middleware Learning Stream)
http://education.oracle.com/pls/web_prod-plq-dad/db_pages.getpage?page_id=724&get_params=streamId:22,p_loId:1475&intcmp=WWOUBLOGPOSTNOD051515
Oracle Learning Streams
http://education.oracle.com/pls/web_prod-plq-dad/db_pages.getpage?page_id=745&intcmp=WWOUBLOGPOSTNOD051515

2015年5月14日

[JDeveloper, ADF, FMW] Oracle JDeveloper and ADF 11.1.1.9 Are Available

原文はこちら。
https://blogs.oracle.com/jdeveloperpm/entry/oracle_jdeveloper_and_adf_11

本日、11.1.1.*系のJDeveloperとADFの最新版、11.1.1.9がリリースされました。それぞれダウンロードページから入手いただけます。
Oracle JDeveloper 11g (11.1.1.9.0) Downloads
http://www.oracle.com/technetwork/developer-tools/jdev/downloads/jdeveloper111190-2538883.html
Application Development Framework Downloads
http://www.oracle.com/technetwork/developer-tools/adf/downloads/index.html
このバージョンはFusion Middleware 11.1.1.9(SOA、WEbCenter、BI extensionを含む)に対応します。ADF開発者向けに、11.1.1.*系に対しての作業を続けており、このバージョンでは12.1.3で既に利用可能な強化ポイントを取り込んでいます。
具体的には、多くの新しいデータ可視化コンポーネントをアプリケーションで活用頂けるようになりました。例えばグラフのためのHTML5描画を使って、よりリッチな体験を提供することができるようになっています。また、新しいダイアグラムや主題地図(thematic map)コンポーネントも含んでいます。デッキ、引き出し、ダッシュボードコンポーネントではアニメーションを組み込んだ新たなレイアウトを作成します。

その他にも様々な新機能が追加されています。詳細は新機能ページをご確認ください。
Oracle JDeveloper and Oracle ADF 11g 11.1.1.9.0: New Features
http://www.oracle.com/technetwork/developer-tools/jdev/index-088099.html

2015年5月13日

[Database] New white paper: Fast Application Notification (FAN)

原文はこちら。
https://blogs.oracle.com/dbcloudcoverage/entry/new_white_paper_fast_application

Fast Application Notification (FAN) Includes FANwatcher:A utility to subscribe to ONS and view FAN eventshttp://www.oracle.com/technetwork/database/options/clustering/overview/fastapplicationnotification12c-2538999.pdf
Fast Application Notification (高速アプリケーション通知/FAN)は、計画されたメンテナンスや計画外の停止、負荷の偏りに伴うOracle Databaseインスタンスの停止や無応答といった、エンドユーザーがぶち当たる可能性のある、イケてない体験を解決するための、重要なコンポーネントです。FANを使うと、End-to-Endでのアプリケーションの完全自動回復や実際のトランザクションパフォーマンスに基づいた実行時の負荷分散が可能です。

FANを使って、Oracle Real Application ClustersおよびOracle Data Guardに組み込まれた継続的なサービスと継続的な接続をアプリケーションやアプリケーションにまで拡張します。データベースサービスの状態が変わる(ON、OFF、または無応答)と、最新のステータスがFANイベントを通じて関心を持っているサブスクライバに対し通知されます。FANは、データベース・サービスやインスタンス、データベース自体、そしてクラスタを形成するノードの状態の変化を迅速に通知します。これはGlobal Data Services(GDS、分散データベースシステム)が搭載されたOracle Database 12cから提供を開始しています。
OracleドライバとOracleプールはFANイベントを使い以下のことを実現します。
  1. 計画メンテナンスの間、アプリケーションに一切エラーを返さずに、メンテナンスを実施する
  2. 非常に高速に障害を検知し、アプリケーションのリカバリをリアルタイムに実施する
  3. パフォーマンスにばらつきがある際に、実行時に流入作業量の負荷分散を実施し、また、インスタンスを残したり、利用可能になったシステムやリソースを参加させたりする
  4. (例えば、連続したWebセッションといった関連する会話をベストパフォーマンスを出すために一緒にルーティングする、というような)流入するワークに対するアフィニティのアドバイスを行う
ホワイトペーパーの内容は以下の通りです。
  1. データベースシステムのFANイベントを有効にすることで得られるメリットの説明
  2. FANイベントおよびそのイベントが発行されたフィールドの解説
  3. FANイベントをFANwatcherを使って確認する方法の説明
  4. OracleアプリケーションやOracle以外のアプリケーションのためにFANイベントを統合し、有効化する手順の紹介
対象読者として、以下を想定しています。

  • RACデータベース管理者
  • Data Guardデータベース管理者
  • アプリケーションやアプリケーションサーバ、監視コンソールや内部業務ワークフローシステムと統合し、計画メンテナンスや計画外停止の迅速な通知をが必要なアプリケーションインテグレータ

2015年5月12日

[Database] Oracle for SAP Technology Update

原文はこちら。
https://blogs.oracle.com/partnertech/entry/oracle_for_sap_technology_update

OracleとSAPは27年以上にわたって共通する数万件のお客様に対し継続的に深く関与しています。SAPアプリケーションをOracleプラットフォームへデプロイすることで、End-to-EndのSAPインフラストラクチャーソリューションを提供し、このソリューションにより、生産性やパフォーマンスが改善され、システム利用率が向上し、環境に優しいデータセンターができあがります。両社は最近、Oracle Databaseの技術とワールドクラスの顧客サポートをさらに推し進めるため、長期にわたる販売代理店契約ならびにサポート契約を更新しました。
Oracle for SAP Technology Update は、SAPのお客様に対し、Oracle製品やサービスの情報やアップデートを提供するための年刊誌です。最新版は今月発行されました。最新刊のトピックを一部ご紹介しましょう。
  • Oracle Database 12c for SAP: Roadmap and Base Certification Features 
  • Implementing a Data Management Infrastructure for SAP with Oracle Database Options and Packs
  • Why Oracle Database and Engineered Systems for SAP
  • Oracle Mission-Critical Support Services for SAP Customers
  • Oracle DB and Oracle Solaris related Notes for SAP
  • Why more and more SAP customers are migrating to Solaris
  • Oracle Security Solutions for SAP environments
  • Customer Examples
最新版は以下からご覧いただけます。
Oracle® for SAP® TECHNOLOGY UPDATE #24
http://www.oracle.com/us/solutions/sap/oracle-sap-newsletter-vol24-en-2526053.pdf
(訳注)
日本語版は今しばらくお待ちください。

2015年5月10日

[JavaScript, Database] node-oracledb 0.5.0 is on NPM (Node.js driver for Oracle Database)

原文はこちら。
https://blogs.oracle.com/opal/entry/node_oracledb_0_5_0

ちょっと時間があきましたが、Node.js driver for Oracle Databaseの0.5.0 Preview Releaseバージョンをリリースしました。
Node.js driver for Oracle Database
https://github.com/oracle/node-oracledb
  • isAutoCommit属性の名前をautoCommitに変更しました。
    isExternalAuth属性の名前をexternalAuthに変更しました。
    これらの2個の属性名の変更により、node-oracledb 0.4.2との後方互換性が損なわれています。0.5.0へ移行にあたっては、当該属性をコードで検索し、置換する必要があります。
    ドライバがPreview Releaseの状態である間にこれらの変更を実施したかったのです。GitHubにてこの変更について警告するエントリをUpしています。
    Thinking of changing attribute names isAutoCommit & isExternalAuth to autoCommit & externalAuth #67
    https://github.com/oracle/node-oracledb/issues/67
  • INバインドに対し空配列エントリを与えないように、outBinds配列の要素数カウントを修正しました。bind-by-position型配列の値をexecute()関数のバインドパラメータとして渡すと、その結果を返す配列outBindsは、各INバインドに対応する空の位置を含めていましたが、これを変更し、OUTバインドを持つようにしました。この変更に伴い、コードを書き換える必要があるかもしれません。
  •  UPDATE test SET NAME = 'abc' RETURNING id INTO :idbv のような"DML RETURNING" バインド変数のサポートを追加しました。詳しくはドキュメントをご覧下さい。
    node-oracledb: Documentation for the Oracle Database Node.js Driver
    7.2.3 DML RETURNING Bind Parameters
    https://github.com/oracle/node-oracledb/blob/master/doc/api.md#dmlreturn
    任意の STRING OUTバインドに対して maxSize を十分大きくしておかないと、エラーが発生しますのでご注意ください。このコードを使って引き続きエッジ・ケースの調査をしていますが、取り急ぎご紹介しておきます。再度申し上げますが、これはプレビューリリースです。
  • 無効なタイププロパティのエラーメッセージを整理しました。
  • 変更内容のトラッキングのために、変更履歴ファイルを追加しました。
    変更履歴
    https://github.com/oracle/node-oracledb/blob/master/CHANGELOG.md
node-oracledbの詳細については、GitHubページをご覧下さい。
Oracle Database driver for Node.js
https://github.com/oracle/node-oracledb

2015年5月5日

[Java] Java EE 7 Maintenance Review Draft

原文はこちら。
https://blogs.oracle.com/theaquarium/entry/java_ee_7_maintenance_review

Java EE 7 Platform Specification (JSR 342) は現在メンテナンスリリースのプロセスに入っています。
JSR 342: JavaTM Platform, Enterprise Edition 7 (Java EE 7) Specification
https://jcp.org/en/jsr/detail?id=342
提案された変更を確認すれば、この更新が仕様自体を明確にすることを意図していることがわかることでしょう。
Java EE 7 MR Changes
https://java.net/attachments/lists/javaee-spec/users/2015-04/20/JavaEE7-MR-Changes
提案された変更はいずれも、Java EE 7のRI(参照実装)やTCK (Technology Compatibility Kits) に影響を与えることはありませんが、唯一仕様自体が影響を受けます。
提案された変更について、Java EE7 Experts Groupの間で合意に達したようなので、すべてがうまくいけば、アップデートがまもなくJCPに提出され、正式にMaintenance Reviewプロセスが始まることになるでしょう。
[javaee-spec users] [jsr366-experts] Updated Java EE 7 Maintenance Review Draft
https://java.net/projects/javaee-spec/lists/users/archive/2015-04/message/20
(訳注)
メンテナンスリリースのドラフトは以下のURLでご覧頂けます。
Java EE 7, Rev A, Maintenance Review Draft
https://java.net/downloads/javaee-spec/JavaEE_7_Platform_MR_Draft.pdf

2015年5月4日

[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
ここまでご覧いただきありがとうございます。この記事が皆様のお役に立つことを願っております。フィードバックや将来の例に関する提案、質問があれば、(原文の)コメント欄にどうぞ。
さらに、TwitterLinkedInでのフォローもどうぞ。