Db2 Warehouse on Cloud の REST API コマンド例

はじめに

Db2 Warehoue on Cloud (Db2WoC) はBIレポーティングやデータ分析向けのリレーショナル・データベースで、IBM CloudおよびAWSにおいてフルマネージド・サービスとして提供されています。
https://cloud.ibm.com/catalog/services/db2-warehouse

兄貴分の Db2 on Cloud はトランザクション処理向けのリレーショナル・データベースで、こちらはIBM Cloudにてフルマネージド・サービスとして提供されています。
https://cloud.ibm.com/catalog/services/db2

本記事ではDb2WoCを対象として、curlコマンドを使った REST API の使い方を紹介します。

私は REST API のマニュアルを見た上で、設定値にダブルクォーテーション記号を含めてコマンドを実行しました。コマンドが意図通りに動作せず、不要なダブルクォーテーション記号が付いていることが原因とわかりましたが、原因特定まで手間を要しました。

ということで、REST APIコマンドの例とエラーの例を紹介することが本記事の目的です。

前提事項

1. Db2 Warehoue on Cloud のデータベース・ユーザーIDとパスワードが必要です。
2. Linux環境、curlコマンド、jqコマンドが必要です。

参考資料

• マニュアル: Db2 Warehouse on Cloud REST API
• Qiita: Db2 Warehouse on CloudのREST APIを使用したデータロード (python & curl)
• Qiita: jq コマンドを使う日常のご紹介

例1: Db2WoCにアクセスするためのトークン取得

REST APIマニュアルから構文を引用します。

curl -X POST \
  https://{HOSTNAME}/dbapi/v4/auth/tokens \
  -H 'content-type: application/json' \
  -d '{"userid":"<ADD STRING VALUE>","password":"<ADD STRING VALUE>"}'

実行例は次のようになります。ここでトークンをxでマスキングして、かつ短く表示していますが、実際の文字数は916文字でした。

$ curl -X POST https://db2w-xxxxxxx.ap-north.db2w.cloud.ibm.com/dbapi/v4/auth/tokens -H 'content-type: application/json' -d '{"userid":"bluadmin","password":"xxxxxxxxxxxxxxxx"}'

{"userid":"bluadmin","token":"xxxxxxxxxxxxxxxxxxxx"}

長いトークンを環境変数に設定すると便利です。以後、環境変数 TOKEN を使って実行します。

$ TOKEN=$(curl -X POST https://db2w-xxxxxxx.ap-north.db2w.cloud.ibm.com/dbapi/v4/auth/tokens -H 'content-type: application/json' -d '{"userid":"bluadmin","password":"xxxxxxxxxxxxxxxx"}' | jq -r '.token')

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  1012    0   948  100    64   2243    151 --:--:-- --:--:-- --:--:--  2398

$ echo $TOKEN
xxxxxxxxxxxxxxxxxxxx

上の jqコマンドはJSON用の文字列編集コマンドです。オプション -r を指定することにより、トークンに付いているダブルクォーテーション記号を取り除きます。そうしないと、後で説明する HWCSEC0003E エラーが生じます。

例2: バックアップ一覧を取得

REST APIマニュアルから構文を引用します。

curl -X GET \
  https://{HOSTNAME}/dbapi/v4/backups \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {AUTH_TOKEN}' \
  -H 'content-type: application/json'

実行例はこのようになります。

$ curl -X GET https://db2w-xxxxxxx.ap-north.db2w.cloud.ibm.com/dbapi/v4/backups -H 'accept: application/json' -H 'authorization: Bearer '$TOKEN -H 'content-type: application/json'

{"backups":[{"id":"20230326123131","type":"Snapshot","status":"completed","created_at":"2023-03-26T12:31:31Z","size":21474836480,"tables":-1,"duration":120},{"id":"20230327123130","type":"Snapshot","status":"completed","created_at":"2023-03-27T12:31:30Z","size":21474836480,"tables":-1,"duration":129},{"id":"20230328090852","type":"Snapshot","status":"completed","created_at":"2023-03-28T09:08:52Z","size":18253611008,"tables":-1,"duration":68},{"id":"20230328114612","type":"Snapshot","status":"completed","created_at":"2023-03-28T11:46:12Z","size":15032385536,"tables":-1,"duration":76},{"id":"20230328180030","type":"Snapshot","status":"completed","created_at":"2023-03-28T18:00:30Z","size":17179869184,"tables":-1,"duration":111},{"id":"20230329180030","type":"Snapshot","status":"completed","created_at":"2023-03-29T18:00:30Z","size":19327352832,"tables":-1,"duration":136},{"id":"20230330180030","type":"Snapshot","status":"completed","created_at":"2023-03-30T18:00:30Z","size":21474836480,"tables":-1,"duration":151}
]}

例3: スキーマ一覧を取得

REST APIマニュアルから構文を引用します。

curl -X GET \
  https://{HOSTNAME}/dbapi/v4/schemas \
  -H 'authorization: Bearer {AUTH_TOKEN}' \
  -H 'content-type: application/json'

実行例はこのようになります。

$ curl -X GET https://db2w-xxxxxxx.ap-north.db2w.cloud.ibm.com/dbapi/v4/schemas -H 'authorization: Bearer '$TOKEN -H 'content-type: application/json'

{"count":39,"resources":[{"definertype":"U","name":"xxxxxxxx"},{"definertype":"U","name":"xxxxxxxx"},{"definertype":"S","name":"AUDIT"},中略,{"definertype":"S","name":"SYSCAT"},{"definertype":"S","name":"SYSFUN"},{"definertype":"S","name":"SYSGEO"},{"definertype":"S","name":"SYSIBM"},{"definertype":"S","name":"SYSIBMADM"},{"definertype":"S","name":"SYSIBMINTERNAL"},{"definertype":"S","name":"SYSIBMTS"},{"definertype":"S","name":"SYSPROC"},{"definertype":"S","name":"SYSPUBLIC"},{"definertype":"S","name":"SYSSTAT"},{"definertype":"S","name":"SYSTOOLS"}]}

エラー例: HWCSEC0003E: Invalid authentication token

トークンが間違っているときこのエラーが生じました。私の場合はトークンにダブルクォーテーション記号を付けていたことが原因でした。

$ curl -X GET https://db2w-xxxxxxx.ap-north.db2w.cloud.ibm.com/dbapi/v4/users -H 'authorization: Bearer "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"' -H 'content-type: application/json'

{"trace":"5bb8defce7a55b3fe453373c5f18b791","errors":[{"code":"authentication_failure","message":"HWCSEC0003E: Invalid authentication token","target":{"type":"","name":""},"more_info":""}]}

エラー例: HWCSEC0001E: User name or password is invalid

Windows10または11のコマンドプロンプトで実行すると、正しいユーザー名とパスワードを入力しているにもかかわらずこのエラーが起きます。なお下の1番目のコマンドはバージョンを示すことが目的でREST API実行と直接関係しません。

Microsoft Windows [Version 10.0.22621.1555]
(c) Microsoft Corporation. All rights reserved.
> curl --version
curl 8.0.1 (Windows) libcurl/8.0.1 Schannel WinIDN
Release-Date: 2023-03-20
Protocols: dict file ftp ftps http https imap imaps pop3 pop3s smtp smtps telnet tftp
Features: AsynchDNS HSTS HTTPS-proxy IDN IPv6 Kerberos Largefile NTLM SPNEGO SSL SSPI threadsafe Unicode UnixSockets

> curl -X POST https://db2w-xxxxxxx.ap-north.db2w.cloud.ibm.com/dbapi/v4/auth/tokens -H 'content-type: application/json' -d '{"userid":"bluadmin","password":"xxxxxxxxxxxxxxxx"}'
{"trace":"6e752bc8bb9629054a7f6e879a52242b","errors":[{"code":"invalid_parameters","message":"HWCSEC0001E: User name or password is invalid.","target":{"type":"","name":""},"more_info":""}]}curl: (6) Could not resolve host: application

同じWindowsマシンに導入したCygwinを使ってこのエラーを回避しました。Cygwin64 Terminalを起動してコマンドを実行します。なお下の1番目と2番目のコマンドはバージョンを示すことが目的でREST API実行と直接関係しません。

$ cygcheck -c cygwin
Cygwin Package Information
Package              Version        Status
cygwin               3.4.6-1        OK

$ curl --version
curl 8.0.1 (Windows) libcurl/8.0.1 Schannel WinIDN
Release-Date: 2023-03-20
Protocols: dict file ftp ftps http https imap imaps pop3 pop3s smtp smtps telnet tftp
Features: AsynchDNS HSTS HTTPS-proxy IDN IPv6 Kerberos Largefile NTLM SPNEGO SSL SSPI threadsafe Unicode UnixSockets

$ curl -X POST https://db2w-xxxxxxx.ap-north.db2w.cloud.ibm.com/dbapi/v4/auth/tokens -H 'content-type: application/json' -d '{"userid":"bluadmin","password":"xxxxxxxxxxxxxxxx"}'
{"userid":"bluadmin","token":"xxxxxxxxxxxxxxxx"}