HCL Domino REST API の活用ポイントとCData Domino Driver での連携方法

CData Domino Driver が新しくREST API バージョンに対応しました！ そこで、HCL Domino REST API の使い方・活用ポイントとCData Driver での連携方法を紹介します。

Transcript

1. © 2024 CData Software Japan, LLC | www.cdata.com/jp HCL Domino REST API の活用ポイントと CData HCL Domino Driver での連携方法 DominoHub 2024 2024/06/13 CData Software Japan Kazuya Sugimoto -Lead Engineer
2. 2 About Speaker © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE CData Software Japan の Lead Engineer これまで300種類以上のAPIを見たり触った りしているAPI中毒な人。 最近の趣味はTesla API で収集したデータの 可視化。 Twitter：@sugimomoto Facebook：sugimomoto Blog：https://www.cdatablog.jp/
3. 3 本社：US(NC州), オフィス：日本 / 欧州 / インド / 中国 データアクセスおよびデータ接続ソリューションのリーディ ングプロバイダー 日本法人 : CData Software Japan 合同会社 本社：宮城県仙台市 設立：2016/06 〜 © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE CData Software EMPLOYEES 400+ ACTIVE CUSTOMERS 10,000+ OEM PARTNERS 180+
4. 本日のお話
5. 5 HCL Domino REST API 用連携コネクタリリース！（昨日） © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE
6. 6 これでもっとDomino の世界を楽しくできるぜ！ © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE FUN WITH DOMINO! DOMINOならでき る！DOMINOだか らできる！
7. 7 でも・・・ © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE
8. 8 実は以前から問い合わせはもらっていたが・・・ © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE 外部連携はしたいけど、 そもそもREST API って どうやって使うの？ REST API でどんなこと ができるの？ 自社の環境にどうやって 適用させたらいいの？ とりあえず別な環境で手 軽に試すことはできない の？ まだまだHCL Domino REST API そのものに関する 認知やナレッジが広がっていないかも・・・？
9. 9 本日のセッションでお伝えしたいこと © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE HCL Domino REST API って実は結構簡単に試せる！ 動かせる！ 環境構築をしてREST API を触って連携のイメージを掴もう！ それでもスクラッチで実装するのは敷居が高い？ Domino エコシステムの中の便利なツールを知って、 楽ができるところは楽をしよう！
10. HCL Domino REST API とは？
11. 11 HCL Domino REST API とは？ © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE • HCL Domino database・いわゆ るNotes アプリケーションとWeb API ベースの接続を行い、外部ア プリケーションからの連携を実現 する Web Service。 • 内部では以前より提供されてきた C-API を利用。このAPI をHTTP ベースのREST API に抽象化して アクセス。 • REST API 自体はDomino Server ないし Notes Client （現状は ベータのようですが）にインス トールして利用。 HCL Domino REST API Documentation https://opensource.hcltechsw.com/Domino-rest-api/index.html
12. 12 HCL Domino REST API はどんな機能をサポートしているの？ © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE • Notes アプリドキュメントの CRUD 操作やファイルのアップ ロード・ダウンロード、エージェ ントの実行などNotes アプリに関 わるほとんどの操作がREST API を通じて実行可能。 • OAuth による認証・認可フロー （Authorization Code Grant）を サポート。JWT を用いたトークン 認証。 • REST Ful な操作の他、DQL （Domino Query Language）や OData による柔軟なクエリをサ ポート。
13. 13 HCL Domino REST API のシステム要件 © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE • HCL Domino REST API を利用す るにはDomino 12.0.2 以上が必要。 • REST API バージョン毎でもサ ポートされるDomino バージョン に違いがある。 （※ちなみに、モジュールとしては 前述の通りC-API に依存し、疎結合 なアーキテクチャになっているよう で、一応12.0.2 以前のバージョンで も動作する、と書かれています。た だサポートの対象外にはなってしま うようです） HCL Domino REST API 1.x System Requirements https://support.hcltechsw.com/csm?id=kb_article&sysparm_article=KB0101789
14. 14 HCL Domino REST API の環境構築方法 © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE ① restapiInstall.jar を利用してDomino Server にインストールして利用 Linux/Mac/Windows java -jar restapiInstall.jar ^ -d="C:¥Program Files¥HCL¥Domino¥Data" ^ -i="C:¥Program Files¥HCL¥Domino¥notes.ini" ^ -p="C:¥Program Files¥HCL¥Domino" ^ -r="C:¥Program Files¥HCL¥Domino¥restapi" ^ -a ② 専用のDocker イメージを利用して構築 ← 今回はこちらを利用 Domino REST API Docker イメージにはDomino サーバーが含まれており 別のDomino インストールは不要。Standalone で手軽に試せる。 > docker load -i [name_of_tar_file].tar > docker-compose up ※ちなみに実運用を想定するのであれば、HTTPS化やIdentity Provider をどうするか、といった要素を考慮する必要がありますが、 今回はREST API の体験に焦点を充てるため、その部分は割愛
15. HCL Domino REST API 環境を 構築して実際に試してみよう！
16. 16 環境構築①：Docker Image を入手 © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE Docker イメージは「HCL Software License and Download Portal (Flexnet) https://hclsoftware.flexnetoperations.com/ 」もしくは「My HCLSoftware Portal https://my.hcltechsw.com/」から入手
17. 17 環境構築②：Docker compose file & .env file の入手 © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE https://opensource.hcltechsw.com/Domino-rest-api/references/downloads.html テストデータとしてDemo.nsf も 合わせてダウンロード docker-compose でそのまま実行でき るようにファイル名を「docker- compose-primary.yml」→「docker- compose.yml」、「sample.env」→ 「.env」にそれぞれ変更
18. 18 環境構築③：Docker Image のロード © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE > docker load -i [name_of_tar_file].tar
19. 19 環境構築④：.env ファイルの編集 © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE # Admin - the person SERVERSETUP_ADMIN_FIRSTNAME=Kazuya SERVERSETUP_ADMIN_LASTNAME=Sugimoto SERVERSETUP_ADMIN_CN=Kazuya Sugimoto SERVERSETUP_ADMIN_PASSWORD=Password! # cert domain and org SERVERSETUP_ORG_CERTIFIERPASSWORD=password SERVERSETUP_ORG_ORGNAME=restapi SERVERSETUP_SERVER_DOMAINNAME=restapi # The server you setup SERVERSETUP_NETWORK_HOSTNAME=restapiserver.domino.acme.com SERVERSETUP_SERVER_NAME=restapiserver # Container info CONTAINER_IMAGE=hclcr.io/domino/restapi:1.0.8 CONTAINER_NAME=domino-restapi CONTAINER_HOSTNAME=restapiserver.domino.acme.com CONTAINER_VOLUMES=domino_restapi_notesdata CONTAINER_IMAGE はロードし たイメージの名前に合わせる https://opensource.hcltechsw.com/Domino-rest-api/tutorial/installconfig/docker.html#update-env-file ADMINユーザーID・PWや サーバー名・ドメイン名を指定
20. 20 環境構築⑤：コンテナを構築 © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE > docker-compose up これだけで環境構築が完了！
21. 21 REST API 管理画面にアクセスしてみよう © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE localhost:8880 でREST API 管理 画面にアクセスが可能
22. 22 Domino/Notes クライアントからもアクセス可能 © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE REST API の管理用Notes アプリ ケーションも構成済み ※Hostsファイルに「127.0.0.1 restapiserver.domino.acme.com」追加済み
23. HCL Domino REST API スキーマ・スコープ構成
24. 24 HCL Domino REST API のデザイン © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE • Domino REST API は「スキー マ」という設定を用いてNotes ア プリケーションに含まれる Form・View・Agentの各要素を API のデータモデルとして公開。 • スキーマはScope（DataSource としても使われる）という要素を 通じてAPI 公開される。 • Scope はそれぞれのOAuth アプ リケーションで束ねられて、認 証・認可プロセス時にScope 要求 を受けて、利用できるスキーマの 範囲を決定。 Understanding HCL Domino REST API https://opensource.hcltechsw.com/Domino-rest-api/topicguides/understanding.html
25. 25 スキーマ・スコープ構成①：管理画面へのアクセス © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE REST API 管理画面の 「Configuration」を使って スキーマやスコープを構成
26. 26 スキーマ・スコープ構成②：スキーマの追加 © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE 対象とするNotes アプリを選択し て、スキーマとして登録する
27. 27 スキーマ・スコープ構成③：フォーム要素の追加 © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE API 公開するForm を選択 API 公開するフィールドを選択 読み取り・書き込みの許可なども 設定
28. 28 スキーマ・スコープ構成④：ビュー要素の追加 © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE API 公開するView を選択 エイリアスの設定も可能
29. 29 スキーマ・スコープ構成④：エージェント要素の追加 © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE API 公開するAgent を選択
30. 30 スキーマ・スコープ構成⑤：スコープの追加 © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE スコープの対象とするスキーマを 選択して、スコープを作成
31. 31 スキーマ・スコープ構成⑥：OAuth アプリ追加（今回は未使用） © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE Callback URL などと合わせて 先ほど構成したスコープを指定 • OAuth アプリケーションとして複 数のScopeを束ねたアプリケー ションを登録し、外部サービスか らの認証・認可プロセスも実装し て利用することも可能。 • ただAPI の利用としてOAuth アプ リの追加は必須ではない。 • 簡易的な内部利用だけであれば、 スコープだけでも十分かも。
32. HCL Domino REST API を Postman から触ってみる
33. 33 Postman とは？ © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE • Postman はAPI 開発のためのコラ ボレーション・テストツール。 • UI ベースで様々なAPI を検証した り、API 開発を迅速に行うための 機能が多く含まれている。 • OpenAPI Spec などを取り込んで API リクエストをまとめて手軽に 検証することも可能。 https://www.postman.com/
34. 34 Open API Spec をPostman へ取り込み © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE ここからOpen API Spec がダウ ンロード可能 ちなみにAPI ドキュメントからも API の検証は可能 Postman にインポートして API 検証を手軽に実施可能
35. 35 Postman の初期設定 © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE よく入力するURLやユーザーID・PW などは変数として登録しておくと便利
36. 36 API を触ってみる①：JWT の取得 © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE • 「/api/v1/auth」エンドポイント を利用してJWT を取得 POST /api/v1/auth HTTP/1.1 Host: localhost:8880 Content-Type: application/json Accept: application/json Content-Length: 62 { "password": "Password!", "username": "Kazuya Sugimoto" } 取得したトークンは 変数に登録しておく
37. 37 API を触ってみる②：Scope の一覧を取得 © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE • Scope の一覧取得は「scopes」 →「GET Retrieve lists of scopes available based on query」を利 用します。 GET /api/v1/scopes HTTP/1.1 Host: localhost:8880 Accept: application/json Authorization: Bearer eyJ0eXAiO
38. 38 API を触ってみる③：Scope に含まれるSchema を取得 © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE • このScope の名前を元に、 dataSource のクエリパラメータ を利用することで、Schema 情報 を取得可能。 • Schema 情報にはForm やView と してどのようなものが定義されて いるのかを識別することができ、 REST API と連携したアプリケー ションを開発する際の動的な機能 の補完などとして利用可能。 GET /api/v1/scope?dataSource=demoscope HTTP/1.1 Host: localhost:8880 Accept: application/json Authorization: Bearer eyJ0eXAiOiJK
39. 39 API を触ってみる④：View を使ってドキュメントを取得する © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE • ビューによるドキュメントの取得 は「lists」→「{name}」→ 「Pulls in view data」を利用。 • この際にURL にView の名前と利 用するScope 名をdataSource の クエリパラメータに付与してリク エストするのがポイント。 GET /api/v1/lists/Customers?dataSource=demoscope HTTP/1.1 Host: localhost:8880 Accept: application/json Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGci
40. 40 API を触ってみる⑤：ドキュメントを作成 © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE • ドキュメントの操作は 「document」→「POST Create a new document for a specified form.」を使用。 • Schema Management のForm の 設定画面で指定した項目をもとに、 リクエストボディでJSON のデー タを組み立てる。 POST /api/v1/document?dataSource=demoscope HTTP/1.1 Host: localhost:8880 Content-Type: application/json Accept: application/json Authorization: Bearer eyJ0eXAiOiJKV1QiLCJ { "Form": "Customer", "last_name": "Hello!", "first_name": "Kazuya" }
41. 41 API を触ってみる⑥：ドキュメントの更新 © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE • ドキュメントの更新では 「document」→「(unid)」→「PUT Perform an update on the document at the relevant mode」を利用。 • URIに更新対象のUNIDを加え、かつ クエリパラメータとして「Mode」を 指定。 PUT /api/v1/document/BF419E31B5B8052B48258512002F9274?dat aSource=demoscope&mode=default HTTP/1.1 Host: localhost:8880 Content-Type: application/json Accept: application/json Authorization: Bearer eyJ0eXAiOiJKV1QiL { "Form": "Customer", "last_name": "Hello Update!" }
42. 42 API を触ってみる⑦：ドキュメントの削除 © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE • ドキュメントの削除では 「document」→「(unid)」→ 「DELETE Delete the given document」を利用。 • 予め対象のForm・Mode で 「Formula for Delete Access」を 「@True」にしておく。 DELETE /api/v1/document/8DBCCA8A6B6FFE2700258B39004FC6F3?da taSource=demoscope&mode=default HTTP/1.1 Host: localhost:8880 Accept: application/json Authorization: Bearer eyJ0eXAiOiJKV1Q
43. 43 API を触ってみる⑧：DQL でクエリする © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE • DQL のクエリを利用することでSQL に似たクエリ言語でDomino のド キュメントデータを網羅的に取得す ることが可能。 • 「query」→「Send a DQL query and get JSON documents back」を 利用。 POST /api/v1/query?dataSource=demoscope&action=execute HTTP/1.1 Host: localhost:8880 Content-Type: application/json Accept: application/json Authorization: Bearer eyJ0eXAiOiJKV1QiL { "query": "form = 'Customer' and Color = 'Fuscia'", "mode": "default" }
44. CData HCL Domino Driver とは？
45. 45 BI・ETLなどお好みのツールからHCL Domino データに連携 © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE
46. 46 © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE 製品ポートフォリオ データコネクタ データ仮想化 データレプリケーション オートメーション API 開発・公開 CData Arc B2B 連携をノーコードで 自動化 CData API Server ノーコードでREST API 公 開 製品ポートフォリオ CData Drivers あらゆるデータに標準SQL でのリアルタイム接続を可能にする高機能・高品質データコネクタ CData Sync データ分析基盤、データパ イプラインの構築 CData DBAmp SQL Server でSalesforce と の双方向連携 CData Connect Cloud セルフサービスでのデータ接 続・仮想化 CData Virtuality エンタープライズグレードの データ仮想化 Enterprise Data Connectivity Solutions
47. 47 © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE CData Sync ３ステップ、ノーコードでデータパイプライン処理を作成、データ統合基盤を構築 SaaSやオンプレミスアプリケーション, データベース, ファイルなど400(Profile含む)を超えるデータソース 主要なデータレイク / データベース / データウェアハウス 同期先 データソース CData Sync レプリケー ション （複製）
48. 48 © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE CData Arc B2B 連携に必要なあらゆる種類のデータ連携ワークフローをノーコードで構築・自動化 ストレージ・ ファイル転送 プロトコル EDI ECサイト アプリ ケーション データ ベース ファイル 形式 API メッセージング CData Drivers (270+) Add More ... CData Arc Input Mapping Output オートメーション ドラッグ&ドロップ操作での ビジュアルフローデザイナー
49. Demo・CData Sync © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE
50. 50 CData Sync の特徴 | シンプルな設定 © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE ３ステップ、ノーコードでデータパイプライン処理を作成 1. データソースと接続 2. 同期先と接続 3. 複製ジョブの設定＆実行 •管理コンソールにログインし、400を 超えるクラウドアプリケーション、 データベース、データウェアハウスな どのデータソースを選択 •接続したいデータソースへの接続は通 常、データソースのWeb インター フェースへのログインだけで完了 •データをレプリケーションする同期 先 (データレイク・データベース・ データウェアハウス)を選択 •同期先への接続は通常、データソー スと同様Web インターフェースへのロ グインだけで完了 •同期ジョブの設定にてオブジェクト （テーブルや項目）、処理方式（洗い 替え or 差分など）や条件（一部のレ コードのみ）を指定 •作成したジョブの実行スケジュール （日次・月次など）を設定＆実行
51. 51 導入事例 | 菊正宗酒造株式会社 様 © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE 最新データに基づいた業務運営を支えるデータ同期の仕組みを構築 Before | 課題 •各クラウドサービスからデータを取得するにはそれぞれのAPI仕様 を理解した開発が必要となり敷居が高いと感じていた •各クラウドサービスから手動でCSVファイルをダウンロード&加工 して基幹システムに連携する方法も検討したが、手間が掛かりすぎ る点から避けたかった •スマレジの売上データを簡単に取得出来るツールを見つけることが 出来なかった After | CData製品を導入した効果 •スマレジの売上データについて、API接続に必要なトークン情報を セットするだけで簡単に取得することが出来た •スマレジでCSVファイルのダウンロードから売上データの発行まで の作業に、30分以上掛かっていたが1分以内に発行できるように なった •スマレジだけでなく社内で活用している他のクラウドサービスの データもCData Syncひとつでデータを取得でき画期的と感じた •ジョブのスケジュール機能で手間をかけずにデータ同期を自動化す ることが出来た https://www.cdata.com/jp/case-study/kikumasamune/
52. おわりに
53. 53 本日のセッションでお伝えしたいこと © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE HCL Domino REST API って実は結構簡単に試せる！ 動かせる！ 環境構築をしてREST API を触って連携のイメージを掴もう！ それでもスクラッチで実装するのは敷居が高い？ Domino エコシステムの中の便利なツールを知って、 楽ができるところは楽をしよう！ CData HCL Domino Driver も是非試してみてね！
54. Thank You