REST API による Db2アクセスのための事前準備

### 目的

Db2データベースはV11.5からRESTに対応して、RESTサービスの作成/実行が可能になっています。
REST利用開始までのセットアップがそれなりの手間だったため、備忘録としてメモを残します。


### 前提

以下の作業が済んでいることを前提とします。

* Db2 11.5 インストール
* インスタンス/データベース作成
* [IBM Cloud](https://cloud.ibm.com/) アカウント作成済であること

### 作業の流れ

手順の全体像は、こちらの Db2マニュアルに記載されます。
[Db2 11.5 「IBM Db2 REST サービスをダウンロードする」(下記のStep1.-4.)](https://www.ibm.com/docs/ja/db2/11.5?topic=endpoints-downloading-rest-service)
[Db2 11.5 「REST 機能のアクティブ化および初期化」(下記のStep5.-6.)](https://www.ibm.com/docs/ja/db2/11.5?topic=endpoints-activating-initializing-rest-capability)

Step1. IBM Cloud コマンド行ツールとプラグインのインストール
Step2. コンテナー・レジストリーへのログイン
Step3. Db2 RESTサービス・コンテナ・イメージをPull
Step4. Db2 RESTサービス・コンテナ実行
Step5. Db2 RESTサービス機能の初期化
Step6. Db2 RESTサービスのドキュメント確認

1つの製品マニュアルでは完結しないため、複数文書を読み合わせながら進めます。
下記手順それぞれの中で、参照した文書リンクを貼っていきます。

### 環境

Db2 REST サービスは、RESTサービス・コンテナを構成することで利用可能になります。
今回は、Db2が稼働するサーバとは別のサーバにRESTサービス・コンテナを立てる構成としています。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/468682/15b76e19-1f3e-6825-eb55-30ebe8ab5e87.png)

 * Db2 データベース稼働サーバ
     * RHEL 7.9
     * Db2 11.5.6

* Db2 RESTサービス・コンテナ稼働サーバ
     * WSL2/Ubuntu 22.04
     * podman version 3.4.4
     * Db2 Rest Service Container 
     * curl 7.81.0


### Step1. IBM Cloud コマンド行ツールとプラグインのインストール

#### Step1-1. IBM Cloud CLI のインストール
参考：https://cloud.ibm.com/docs/cli?topic=cli-getting-started

最新バージョンのIBM Cloud CLIをインストールします。
```
curl -fsSL https://clis.cloud.ibm.com/install/linux | sh
```

CLI が正常にインストールされたことを検証するには、help コマンドを実行します。
出力例：
```
kanako@IBM-PF2E8K5F:~$ ibmcloud help
名前:
  ibmcloud - IBM Cloud と対話するためのコマンド・ライン・ツール
詳しくは https://ibm.biz/cli-docs を参照してください

使用法:
  [environment variables] ibmcloud [global options] command [arguments...] [command options]

バージョン:
  2.10.0+e37e09e-2022-08-24T17:31:27+00:00

コマンド:
  account      アカウント、ユーザー、組織、およびスペースを管理します
  api          ターゲットの API エンドポイントを設定または表示します
  app          [非推奨] Cloud Foundry アプリケーションとアプリケーションに関連したドメインおよび経路を管理します。
  billing      使用量および請求先情報を取得します
(以下略)
```

#### Step1-2. CLI プラグイン cr(Container-registry) のインストール
参考：https://cloud.ibm.com/docs/cli?topic=cli-plug-ins

後続のStep2.でコマンド ibmcloud cr region-set global を実行する必要があるため、プラグインcrを導入しておきます。
プラグイン情報の取得：
```
kanako@IBM-PF2E8K5F:~$ ibmcloud plugin repo-plugins -r "IBM Cloud"
リポジトリー 'IBM Cloud' からプラグインを取得しています...

リポジトリー: IBM Cloud
状況             名前                                          バージョン                     説明
未インストール   container-registry                            0.1.579, 0.1.578, 0.1.571...   Manage IBM Cloud Container Registry content and configuration.
未インストール   container-service[kubernetes-service/ks]      1.0.439, 1.0.433, 1.0.431...   Manage IBM Cloud Kubernetes Service clusters
未インストール   analytics-engine                              1.0.186, 1.0.181, 1.0.177...   Manage Analytics Engine service
未インストール   cloud-functions[wsk/functions/fn]             1.0.59, 1.0.58, 1.0.56...      Manage Cloud Functions
未インストール   cloud-internet-services[cis]                  1.14.5, 1.14.4, 1.14.2...      Manage Cloud Internet Service
未インストール   dbaas-cli[dbaas]                              2.1.7, 2.1.6, 2.1.2...         Manage Hyper Protect DBaaS clusters
未インストール   cloud-databases[cdb]                          0.11.0, 0.10.10, 0.10.9...     Manage Cloud databases
未インストール   key-protect[kp]                               0.6.12, 0.6.11, 0.6.10...      Manage encryption keys on IBM Cloud
未インストール   doi[doi]                                      0.3.9, 0.3.8, 0.3.7...         Integrate with DevOps Insights service
未インストール   tke                                           1.3.0, 1.2.3, 1.1.4...         Manage the master key of Cloud HSMs from Hyper Protect Crypto service
未インストール   cloud-object-storage                          1.5.0, 1.4.0, 1.3.1...         Manage Cloud Object Storage service
未インストール   event-streams                                 2.3.2, 2.3.1, 2.3.0...         Manage Event Streams service
未インストール   power-iaas[pi]                                0.3.17, 0.3.13, 0.3.12...      Manage IBM Cloud Power Virtual Server service
未インストール   vpc-infrastructure[infrastructure-service]    5.1.0, 5.0.1, 5.0.0...         Manage Virtual Private Cloud infrastructure service
未インストール   schematics[sch]                               1.12.2, 1.12.1, 1.12.0...      Managing IBM Cloud resources with Terraform
未インストール   cloud-dns-services[dns]                       0.7.0, 0.6.2, 0.5.3...         Manage IBM Cloud Dns Service
未インストール   dl-cli                                        0.4.11, 0.4.10, 0.4.9...       Manage Direct Link
未インストール   watson                                        0.0.11, 0.0.10, 0.0.9...       Manage Watson services
未インストール   catalogs-management                           2.2.1, 2.2.0, 2.1.20...        Manage personal catalogs and offerings
未インストール   tg-cli[tg]                                    0.8.2, 0.7.1, 0.6.1...         Manage Transit Gateway service
未インストール   observe-service                               1.0.82, 1.0.61, 1.0.54...      Manage logging and monitoring configurations for IBM Cloud Kubernetes Service clusters
未インストール   code-engine                                   1.39.2, 1.39.1, 1.38.2...      Manage Code Engine components
未インストール   hpvs                                          1.4.19, 1.4.17, 1.4.15...      Manage Hyper Protect Virtual Server service
未インストール   push-notifications[push]                      1.0.5, 1.0.4, 1.0.3...         [Deprecated] Manage IBM Cloud Push Notifications service.
未インストール   secrets-manager[sm]                           0.1.21, 0.1.20, 0.1.19...      Manage IBM Cloud Secrets Manager secrets and secret groups.
未インストール   app-configuration[ac]                         1.0.10, 1.0.9, 1.0.8...        Interact with IBM Cloud App Configuration service instance
未インストール   monitoring                                    0.2.12, 0.2.9, 0.2.8...        Manage IBM Cloud monitoring
未インストール   logging                                       0.0.8, 0.0.7, 0.0.6...         Manage IBM Cloud logging  
未インストール   cloudant[cl]                                  0.0.5, 0.0.4, 0.0.3            Manage Cloudant service
未インストール   hpcs-cert-mgr[hpcs-cert-mgr]                  1.0.0                          Manage the client certificates for IBM Cloud Hyper Protect Crypto Services
未インストール   atracker[at]                                  0.2.17, 0.2.12, 0.1.13...      Manage IBM Cloud Activity Tracker
未インストール   analytics-engine-v3[ae-v3]                    1.0.9, 1.0.5, 1.0.0            Manage serverless Spark instances and run applications
未インストール   cra[cra]                                      1.0.1, 1.0.0, 0.1.22...        Integrate with Code Risk Analyzer
未インストール   event-notifications[en/event-notifications]   0.1.2, 0.1.1, 0.1.0...         IBM Cloud Event Notifications.
未インストール   dvaas[watson-query]                           1.0.2                          Manage data virtualization as a service
未インストール   hpnet                                         1.0.2, 1.0.1                   Manage Hyper Protect Secure Network
未インストール   qiskit-runtime[qr]                            0.1.5                          [Beta] Manage Qiskit Runtime
未インストール   hpcs                                          0.0.1                          Manage Hyper Protect Crypto Services Instances
未インストール   cbr                                           1.1.0, 1.0.0                   Manage Context Based Restrictions
未インストール   privileged-access-gateway[pag]                1.2.2, 1.2.1                   [Experimental] Manage Privilege Access Gateway

ibmcloud plugin update PLUGIN_NAME -r REPO_NAME を使用して、リポジトリーからプラグインを更新します。
ibmcloud plugin update --all -r REPO_NAME を使用して、リポジトリーからすべての使用可能なプラグインをアップグレードします。

kanako@IBM-PF2E8K5F:~$
```

プラグイン 'container-registry'をインストール
```
kanako@IBM-PF2E8K5F:~$ ibmcloud plugin install container-registry -r "IBM Cloud"
リポジトリー 'IBM Cloud' から 'container-registry' を検索しています...
プラグイン 'container-registry 0.1.579' がリポジトリー 'IBM Cloud' 内で見つかりました
バイナリー・ファイルをダウンロードしようとしています...
 11.25 MiB / 11.25 MiB [====================================================================================] 100.00% 1s
11800576 バイトがダウンロードされました
バイナリーをインストールしています...
OK
プラグイン 'container-registry 0.1.579' は /home/kanako/.bluemix/plugins/container-registry に正常にインストールされました。 'ibmcloud plugin show container-registry' を使用して詳細を表示してください。
kanako@IBM-PF2E8K5F:~$

```

#### Step1-3. Podmanのインストール
後続のStep2で登場する「ibmcloud cr login」コマンドの実行には、dockerもしくはpodmanが必要となります。
dockerはコスト面の懸念があるため、[こちら](https://www.server-world.info/query?os=Ubuntu_22.04&p=podman&f=1)を参考にさせていただきつつpodmanを導入します。

```
kanako@IBM-PF2E8K5F:~$ sudo apt -y install podman
[sudo] kanako のパスワード:
パッケージリストを読み込んでいます... 完了
依存関係ツリーを作成しています... 完了
状態情報を読み取っています... 完了
(中略)
アップグレード: 0 個、新規インストール: 32 個、削除: 0 個、保留: 0 個。
26.2 MB のアーカイブを取得する必要があります。
この操作後に追加で 115 MB のディスク容量が消費されます。
(中略)
Scanning processes...
Scanning processor microcode...
Scanning linux images...

Failed to retrieve available kernel versions.

Failed to check for processor microcode upgrades.

No services need to be restarted.

No containers need to be restarted.

No user sessions are running outdated binaries.

No VM guests are running outdated hypervisor (qemu) binaries on this host.
kanako@IBM-PF2E8K5F:~$
```

導入されたこと(と、バージョン)を確認します。
```
kanako@IBM-PF2E8K5F:~$ podman --version
podman version 3.4.4
kanako@IBM-PF2E8K5F:~$
```

### Step2. コンテナー・レジストリーにログイン

#### Step2-1. ibmcloud login
下記の情報を参考にAPIKEYを生成し、ibmcloudコマンドでログインします。
取得したAPIKEYはローカルファイル(mykey.json)として保持しておきます。

https://qiita.com/nishikyon/items/fa8b951267efbe911fe7
https://qiita.com/testnin2/items/3ff57e6c92eacd664ff3

Db2マニュアルに従い、リージョン選択はスキップしてログインします。

```
kanako@IBM-PF2E8K5F:~$ ibmcloud login --apikey @mykey.json
API エンドポイント: https://cloud.ibm.com
認証中です...
OK

ターゲットのアカウント IBM - ISE Cloud (1fc8373f538a408187ffedbe62e5796a) <-> 1707641


リージョンを選択します (または Enter キーを押してスキップします):
1. au-syd
2. in-che
3. jp-osa
4. jp-tok
5. kr-seo
6. eu-de
7. eu-fr2
8. eu-gb
9. ca-tor
10. us-south
11. us-south-test
12. us-east
13. br-sao
数値を入力してください>        ←-- Enter を押してスキップ


API エンドポイント:      https://cloud.ibm.com
Region:
ユーザー:                KUTSUMI@jp.ibm.com
アカウント:              IBM - ISE Cloud (1fc8373f538a408187ffedbe62e5796a) <-> 1707641
リソース・グループ:      リソース・グループがターゲットになっていません。'ibmcloud target -g RESOURCE_GROUP' を使用して ください
CF API エンドポイント:
組織:
スペース:
kanako@IBM-PF2E8K5F:~$
```

#### Step2-2. ibmcloud cr region-set global

```
kanako@IBM-PF2E8K5F:~$ ibmcloud cr region-set global
地域は「global」に設定されました。地域は「icr.io」です。

OK
kanako@IBM-PF2E8K5F:~$

```


#### Step2-3. ibmcloud cr login

```
kanako@IBM-PF2E8K5F:~$ ibmcloud cr login
'podman' を 'icr.io' にログインしています ...
「icr.io」にログインしました。

OK
kanako@IBM-PF2E8K5F:~$

```

### Step3. Db2 RESTサービス・コンテナ・イメージをPull
podman pull コマンドでコンテナイメージをpullします。
```
kanako@IBM-PF2E8K5F:~$ podman pull icr.io/obs/hdm/db2rest:latest-amd64
Trying to pull icr.io/obs/hdm/db2rest:latest-amd64...
Getting image source signatures
Copying blob 00f071514b11 done
Copying blob 0d725b91398e done
Copying blob 030fe302b577 done
Copying blob 3d60ce6dc219 done
Copying blob 1e09a5ee0038 done
Copying blob e9b8a2ffc7d6 done
Copying blob 75c1404812e9 done
Copying blob 535f562837f4 done
Copying blob 334ced49f4e8 done
Copying config 3549fc40c4 done
Writing manifest to image destination
Storing signatures
3549fc40c4a5a9dc42bb6745b07fe7836417730003ab4fab8024df18e6071f86
kanako@IBM-PF2E8K5F:~$
```

### Step4. Db2 RESTサービス・コンテナ実行
今回は気づかなかったのですが、サービス・コンテナ開始のタイミングで選択可能なオプションがいくつか存在します。
docker(podman) run オプションで指定するものですので、コンテナ開始前に検討しておきたいところです。

#### 例1) SQL 直接実行の無効化
参考：https://www.ibm.com/docs/ja/db2/11.5?topic=endpoints-disabling-direct-sql-execution
>Db2 REST では、サービスの作成および実行に加え、/v1/services/execsql エンドポイントを使用して SQL を直接実行できます。 コマンド行から IBM Db2 REST サービス・コンテナーを開始するときに、このエンドポイントの使用を無効にできます。
-e DB2REST_EXECSQL_DISABLED=true

#### 例2) HTTPS を使用しない IBM Db2 REST サーバーの実行
参考：https://www.ibm.com/docs/ja/db2/11.5?topic=endpoints-running-rest-without-https
>外部アクセスのリスクが低い環境では、HTTP のみを使用して IBM® Db2® REST サーバーを実行できます。
注: HTTPS を無効にすると、 IBM Db2 REST サービスのセキュリティーに影響するため、アクセスが制御される分離環境にサーバーがある環境でのみ実行してください。
-e DB2REST_USE_HTTP=true

Db2 RESTサービス・コンテナ実行：
```
kanako@IBM-PF2E8K5F:~$ podman run -it --net=host -e LICENSE=view --name=db2rest icr.io/obs/hdm/db2rest:latest-amd64

Opening License Agreement...


Use the keys [k] and [j] to scroll up and down
Use the key [q] to exit and proceed to prompt

Do you accept the License Agreement? [y/n] y　　　　←--「y」を選択
Proceeding to install...

Generating a RSA private key
................................................+++++
......................................................+++++
writing new private key to '/opt/ibm/dbrest/auth/dbrest.key'
-----
Starting the Db2 REST server...
Starting server with https
SERVER STATUS: ACTIVE
####################################################################################
###  IBM Db2 REST container was deployed successfully                            ###
####################################################################################

* To return to the host after viewing and accepting the license, press
  Ctrl+p followed by Ctrl+q.

* To return to the host after viewing the logs with
  [ docker | oc | kubectl -n <NS> ] logs <rest container name>,
  press Ctrl+c.
* To get a command line prompt, issue the following command from the host:
  [ docker | oc | kubectl -n <NS> ] exec -it <rest container name> bash
####################################################################################

 → ACTIVE ということで問題なく稼働している
　→ Ctrl - c で元のコンソールに戻る
```

### Step5. Db2 RESTサービス機能の初期化

#### 前提(権限)

今回は簡易的な検証で、インスタンスオーナー db2inst1 で実施しますので考慮の必要はありませんが、
メタデータのセットアップには、以下の権限が必要です。

 * 管理者権限。
 * 許可 ID の SYSPROC.AUTH_LIST_GROUPS_FOR_AUTHID、 SYSPROC.AUTH_LIST_ROLES_FOR_AUTHID、および SYSPROC.AUTH_LIST_AUTHORITIES_FOR_AUTHID 表関数に対する 実行特権。
 * メタデータ表を含むスキーマのプロシージャー権限に対する CREATE TABLE、CREATE PROCEDURE、および GRANT EXECUTE 特権。
 * メタデータ表に対する GRANT SELECT 特権。

参考：https://www.ibm.com/docs/ja/db2/11.5?topic=endpoints-required-privileges

#### Step5-1. アクティブ化および初期化処理
参考：https://www.ibm.com/docs/ja/db2/11.5?topic=endpoints-activating-initializing-rest-capability

上記マニュアルを参考に、REST機能をアクティブ化および初期化します。
コンテナに配置されたコマンドを3つ実行するか、もしくはREST API「setup_metadata」を実行するか、どちらかの方法を選択できます。
今回は、Db2 RESTサービス・コンテナを稼働するサーバにログインし、コマンド3つを実行しています。

コマンド構文：
```
podman exec db2rest /opt/ibm/dbrest/scripts/db2rest-stop.sh
podman exec db2rest /opt/ibm/dbrest/scripts/db2rest-setup.sh DBホスト名 DB名 ポート番号 SSL(TLS有無) メタデータ格納用テーブルのスキーマ メタデータ作成ユーザID メタデータ作成ユーザパスワード
podman exec db2rest /opt/ibm/dbrest/scripts/db2rest-start.sh

```

実行ログ：
```
kanako@IBM-PF2E8K5F:~$ podman exec db2rest /opt/ibm/dbrest/scripts/db2rest-stop.sh
Stopping the Db2 REST server...
SERVER STATUS: INACTIVE
kanako@IBM-PF2E8K5F:~$ podman exec db2rest /opt/ibm/dbrest/scripts/db2rest-setup.sh toriringo testdb2 50300 N db2rest db2inst1 パスワード文字列

Creating REST Services metadata...
REST Services metadata created in schema db2rest.
kanako@IBM-PF2E8K5F:~$ podman exec db2rest /opt/ibm/dbrest/scripts/db2rest-start.sh
Starting the Db2 REST server...
Starting server with https
SERVER STATUS: ACTIVE
kanako@IBM-PF2E8K5F:~$

```

#### Step5-2. メタデータ表の存在確認
Step5-1.が成功すると、今後作成するRESTサービスについてのメタデータが格納されるためのRESTSERVICE表が作成されます。

```
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/468682/4e6dc780-b501-0713-e396-d44592ce4b13.png)
[db2inst1@4c4fd18c3faf ~]$ db2 list tables for schema db2rest

Table/View                      Schema          Type  Creation time
------------------------------- --------------- ----- --------------------------
RESTSERVICE                     DB2REST         T     2022-09-06-09.37.57.357031

  1 record(s) selected.

```
この段階では、メタデータは格納されていません。
```
[db2inst1@4c4fd18c3faf ~]$ db2 "select * from db2rest.RESTSERVICE"

NAME                                                                                                                                                                                                                                                            VERSION                                                                                                                                                                                                                                                         DESCRIPTION                                                                                                                                                                                                                                                     PROCSCHEMA                                                                                                                       PROCNAME                                                                                                                         ISQUERY SERVICE_CREATOR                                                                                                               SERVICE_UPDATER                                                                                                               LAST_MODIFIED
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -------------------------------------------------------------------------------------------------------------------------------- -------------------------------------------------------------------------------------------------------------------------------- ------- ----------------------------------------------------------------------------------------------------------------------------- ----------------------------------------------------------------------------------------------------------------------------- --------------------------

  0 record(s) selected.

[db2inst1@4c4fd18c3faf ~]$

```



### Step6. Db2 RESTサービスのドキュメント確認

Db2 RESTサービス・コンテナを立てると、RESTのドキュメントを参照できるようになり、
どんな操作が可能であるか、確認できます。
(webで見られる [Db2製品マニュアル](https://www.ibm.com/docs/ja/db2/11.5) とはまた別にドキュメントが提供されています)

__REST ドキュメントURL：__
https://\<db2restservice_container_host>:50050//docs
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/468682/f1b4cfeb-b51a-001c-ed0b-c738fe9adca9.png)



これで、Db2 RESTサービスの作成ができるようになりました。
RESTサービス作成/実行のメモはこちらに残します → [Link](https://qiita.com/mi-kana/items/3d6636c13b3085eb709f)