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

Slide 1

Slide 1 text

Slide 2

Slide 2 text

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/

Slide 3

Slide 3 text

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+

Slide 4

Slide 4 text

本日のお話

Slide 5

Slide 5 text

Slide 6

Slide 6 text

Slide 7

Slide 7 text

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

9 本日のセッションでお伝えしたいこと © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE HCL Domino REST API って実は結構簡単に試せる！動かせる！環境構築をしてREST API を触って連携のイメージを掴もう！それでもスクラッチで実装するのは敷居が高い？ Domino エコシステムの中の便利なツールを知って、楽ができるところは楽をしよう！

Slide 10

Slide 10 text

HCL Domino REST API とは？

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

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 による柔軟なクエリをサポート。

Slide 13

Slide 13 text

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

Slide 14

Slide 14 text

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 の体験に焦点を充てるため、その部分は割愛

Slide 15

Slide 15 text

HCL Domino REST API 環境を構築して実際に試してみよう！

Slide 16

Slide 16 text

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/」から入手

Slide 17

Slide 17 text

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」にそれぞれ変更

Slide 18

Slide 18 text

Slide 19

Slide 19 text

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やサーバー名・ドメイン名を指定

Slide 20

Slide 20 text

Slide 21

Slide 21 text

Slide 22

Slide 22 text

Slide 23

Slide 23 text

HCL Domino REST API スキーマ・スコープ構成

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

Slide 26

Slide 26 text

Slide 27

Slide 27 text

Slide 28

Slide 28 text

Slide 29

Slide 29 text

Slide 30

Slide 30 text

Slide 31

Slide 31 text

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

Slide 32

Slide 32 text

HCL Domino REST API を Postman から触ってみる

Slide 33

Slide 33 text

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

Slide 34

Slide 34 text

Slide 35

Slide 35 text

Slide 36

Slide 36 text

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" } 取得したトークンは変数に登録しておく

Slide 37

Slide 37 text

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

Slide 38

Slide 38 text

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

Slide 39

Slide 39 text

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

Slide 40

Slide 40 text

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" }

Slide 41

Slide 41 text

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!" }

Slide 42

Slide 42 text

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

Slide 43

Slide 43 text

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" }

Slide 44

Slide 44 text

CData HCL Domino Driver とは？

Slide 45

Slide 45 text

Slide 46

Slide 46 text

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

Slide 47

Slide 47 text

47 © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE CData Sync ３ステップ、ノーコードでデータパイプライン処理を作成、データ統合基盤を構築 SaaSやオンプレミスアプリケーション, データベース, ファイルなど400(Profile含む)を超えるデータソース主要なデータレイク / データベース / データウェアハウス同期先データソース CData Sync レプリケーション（複製）

Slide 48

Slide 48 text

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 オートメーションドラッグ&ドロップ操作でのビジュアルフローデザイナー

Slide 49

Slide 49 text

Slide 50

Slide 50 text

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

Slide 51

Slide 51 text

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/

Slide 52

Slide 52 text

おわりに

Slide 53

Slide 53 text

53 本日のセッションでお伝えしたいこと © 2024 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE HCL Domino REST API って実は結構簡単に試せる！動かせる！環境構築をしてREST API を触って連携のイメージを掴もう！それでもスクラッチで実装するのは敷居が高い？ Domino エコシステムの中の便利なツールを知って、楽ができるところは楽をしよう！ CData HCL Domino Driver も是非試してみてね！

Slide 54

Slide 54 text

Thank You