$30 off During Our Annual Pro Sale. View Details »

HCL Domino REST API の活用ポイントとCData Domino Driver...

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

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

CData Software Japan

June 13, 2024
Tweet

More Decks by CData Software Japan

Other Decks in Technology

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. 6 これでもっとDomino の世界を楽しくできるぜ! © 2024 CData Software Inc. — CONFIDENTIAL

    – DO NOT DUPLICATE OR DISTRIBUTE FUN WITH DOMINO! DOMINOならでき る!DOMINOだか らできる!
  5. 8 実は以前から問い合わせはもらっていたが・・・ © 2024 CData Software Inc. — CONFIDENTIAL –

    DO NOT DUPLICATE OR DISTRIBUTE 外部連携はしたいけど、 そもそもREST API って どうやって使うの? REST API でどんなこと ができるの? 自社の環境にどうやって 適用させたらいいの? とりあえず別な環境で手 軽に試すことはできない の? まだまだHCL Domino REST API そのものに関する 認知やナレッジが広がっていないかも・・・?
  6. 9 本日のセッションでお伝えしたいこと © 2024 CData Software Inc. — CONFIDENTIAL –

    DO NOT DUPLICATE OR DISTRIBUTE HCL Domino REST API って実は結構簡単に試せる! 動かせる! 環境構築をしてREST API を触って連携のイメージを掴もう! それでもスクラッチで実装するのは敷居が高い? Domino エコシステムの中の便利なツールを知って、 楽ができるところは楽をしよう!
  7. 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
  8. 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 による柔軟なクエリをサ ポート。
  9. 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
  10. 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 の体験に焦点を充てるため、その部分は割愛
  11. 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/」から入手
  12. 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」にそれぞれ変更
  13. 18 環境構築③:Docker Image のロード © 2024 CData Software Inc. —

    CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE > docker load -i [name_of_tar_file].tar
  14. 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や サーバー名・ドメイン名を指定
  15. 20 環境構築⑤:コンテナを構築 © 2024 CData Software Inc. — CONFIDENTIAL –

    DO NOT DUPLICATE OR DISTRIBUTE > docker-compose up これだけで環境構築が完了!
  16. 21 REST API 管理画面にアクセスしてみよう © 2024 CData Software Inc. —

    CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE localhost:8880 でREST API 管理 画面にアクセスが可能
  17. 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」追加済み
  18. 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
  19. 25 スキーマ・スコープ構成①:管理画面へのアクセス © 2024 CData Software Inc. — CONFIDENTIAL –

    DO NOT DUPLICATE OR DISTRIBUTE REST API 管理画面の 「Configuration」を使って スキーマやスコープを構成
  20. 26 スキーマ・スコープ構成②:スキーマの追加 © 2024 CData Software Inc. — CONFIDENTIAL –

    DO NOT DUPLICATE OR DISTRIBUTE 対象とするNotes アプリを選択し て、スキーマとして登録する
  21. 27 スキーマ・スコープ構成③:フォーム要素の追加 © 2024 CData Software Inc. — CONFIDENTIAL –

    DO NOT DUPLICATE OR DISTRIBUTE API 公開するForm を選択 API 公開するフィールドを選択 読み取り・書き込みの許可なども 設定
  22. 28 スキーマ・スコープ構成④:ビュー要素の追加 © 2024 CData Software Inc. — CONFIDENTIAL –

    DO NOT DUPLICATE OR DISTRIBUTE API 公開するView を選択 エイリアスの設定も可能
  23. 30 スキーマ・スコープ構成⑤:スコープの追加 © 2024 CData Software Inc. — CONFIDENTIAL –

    DO NOT DUPLICATE OR DISTRIBUTE スコープの対象とするスキーマを 選択して、スコープを作成
  24. 31 スキーマ・スコープ構成⑥:OAuth アプリ追加(今回は未使用) © 2024 CData Software Inc. — CONFIDENTIAL

    – DO NOT DUPLICATE OR DISTRIBUTE Callback URL などと合わせて 先ほど構成したスコープを指定 • OAuth アプリケーションとして複 数のScopeを束ねたアプリケー ションを登録し、外部サービスか らの認証・認可プロセスも実装し て利用することも可能。 • ただAPI の利用としてOAuth アプ リの追加は必須ではない。 • 簡易的な内部利用だけであれば、 スコープだけでも十分かも。
  25. 33 Postman とは? © 2024 CData Software Inc. — CONFIDENTIAL

    – DO NOT DUPLICATE OR DISTRIBUTE • Postman はAPI 開発のためのコラ ボレーション・テストツール。 • UI ベースで様々なAPI を検証した り、API 開発を迅速に行うための 機能が多く含まれている。 • OpenAPI Spec などを取り込んで API リクエストをまとめて手軽に 検証することも可能。 https://www.postman.com/
  26. 34 Open API Spec をPostman へ取り込み © 2024 CData Software

    Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE ここからOpen API Spec がダウ ンロード可能 ちなみにAPI ドキュメントからも API の検証は可能 Postman にインポートして API 検証を手軽に実施可能
  27. 35 Postman の初期設定 © 2024 CData Software Inc. — CONFIDENTIAL

    – DO NOT DUPLICATE OR DISTRIBUTE よく入力するURLやユーザーID・PW などは変数として登録しておくと便利
  28. 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" } 取得したトークンは 変数に登録しておく
  29. 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
  30. 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
  31. 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
  32. 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" }
  33. 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!" }
  34. 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
  35. 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" }
  36. 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
  37. 47 © 2024 CData Software Inc. — CONFIDENTIAL – DO

    NOT DUPLICATE OR DISTRIBUTE CData Sync 3ステップ、ノーコードでデータパイプライン処理を作成、データ統合基盤を構築 SaaSやオンプレミスアプリケーション, データベース, ファイルなど400(Profile含む)を超えるデータソース 主要なデータレイク / データベース / データウェアハウス 同期先 データソース CData Sync レプリケー ション (複製)
  38. 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 オートメーション ドラッグ&ドロップ操作での ビジュアルフローデザイナー
  39. 50 CData Sync の特徴 | シンプルな設定 © 2024 CData Software

    Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE 3ステップ、ノーコードでデータパイプライン処理を作成 1. データソースと接続 2. 同期先と接続 3. 複製ジョブの設定&実行 •管理コンソールにログインし、400を 超えるクラウドアプリケーション、 データベース、データウェアハウスな どのデータソースを選択 •接続したいデータソースへの接続は通 常、データソースのWeb インター フェースへのログインだけで完了 •データをレプリケーションする同期 先 (データレイク・データベース・ データウェアハウス)を選択 •同期先への接続は通常、データソー スと同様Web インターフェースへのロ グインだけで完了 •同期ジョブの設定にてオブジェクト (テーブルや項目)、処理方式(洗い 替え or 差分など)や条件(一部のレ コードのみ)を指定 •作成したジョブの実行スケジュール (日次・月次など)を設定&実行
  40. 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/
  41. 53 本日のセッションでお伝えしたいこと © 2024 CData Software Inc. — CONFIDENTIAL –

    DO NOT DUPLICATE OR DISTRIBUTE HCL Domino REST API って実は結構簡単に試せる! 動かせる! 環境構築をしてREST API を触って連携のイメージを掴もう! それでもスクラッチで実装するのは敷居が高い? Domino エコシステムの中の便利なツールを知って、 楽ができるところは楽をしよう! CData HCL Domino Driver も是非試してみてね!