TiDB CloudのAPIを利用する

## はじめに

TiDB CloudにはAPIが提供されており、クラスタの操作をはじめとして各種操作がAPI経由で行えるようになっています。
本記事ではAPIの紹介と簡単な利用方法について説明します。

## TiDB Cloud API

https://docs.pingcap.com/tidbcloud/api/v1beta#section/Get-Started

TiDB Cloud API (OpenAPI) は [OpenAPI]() 形式のAPIで、現在ProjectやClusterの操作を行う `v1beta` APIと、IAMや請求機能を提供する `v1beta1` が提供されています。

どちらも利用にはAPIキーを発行する必要があります。まずは、curlを使った簡単な使い方を見ていきます。（環境はMacOSを使っていますが、bashとcurlが利用できるなら他の環境でも操作は同じです）

### APIキーの発行

APIキーはTiDB Cloudコンソールから発行します。TiDB Cloudの`Organization Settings > API Key` から、APIキーを発行してください。

取得したAPIキーを環境変数に入れておきましょう。

```bash
export TIDB_PUB=<PUBLIC KEY>
export TIDB_PRIV=<PRIVATE KEY>
```

### APIの呼び出し

APIドキュメントには、curl呼び出しのサンプルがあります。
ここではもっとも簡単な、プロジェクトの一覧を取得するサンプルを実行してみます。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/12495/53f42769-9e0c-fcb1-5bd6-4cbbfac1fce0.png" width="50%">


これはGetメソッドで、引数も特に不要なため単に実行するだけです。

```bash
> curl --digest \
  --user "$TIDB_PUB:$TIDB_PRIV" \
  --request GET \
  --url 'https://api.tidbcloud.com/api/v1beta/projects?page=1&page_size=10'
{"items":[{"id":"XXXXXXXX","orgId":"XXXXXX","name":"Group6","clusterCount":0,"userCount":1,"createTimestamp":"1723510314","awsCmekEnabled":false},{"id":"YYYYYYYY","orgId":"YYYYYYY","name":"Group5","clusterCount":0,"userCount":1,"createTimestamp":"17...
```

正しく実行されました。JSONオブジェクトが返ってきます。

### クラスタの操作

このようにシンプルなAPIは良いのですが、クラスタの操作は若干複雑になっています。
クラスタを作成するためには

- ProjectIDの取得
- Serverless / Dedicatedの指定
- クラウドプロバイダの指定
- クラスタスペックの指定

が必要になります。クラスタで設定できるスペックはクラウドプロバイダやリージョンによって若干の差異があるためです。

最も簡単なサーバレスクラスタを立ち上げる例を見てみます。サーバレスはAWS固定、スペックも指定の必要がないため、ProjectIDを指定すれば可能です。ProjectIDは、先ほど実行したプロジェクトの一覧から確認することができます。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/12495/c10a87a1-3176-8f99-bdf7-54335e2f8b8a.png" width="50%">


```bash
curl --digest \
  --user "$TIDB_PUB:$TIDB_PRIV" \
  --request POST \
  --url https://api.tidbcloud.com/api/v1beta/projects/XXXXXXXX/clusters \
  --header 'content-type: application/json' \
  --data '{"name":"Cluster0","cluster_type":"DEVELOPER","cloud_provider":"AWS","region":"ap-northeast-1","config":{"root_password":"<password>"}}'
```

:::note warn
rootユーザーパスワードの設定が必要なことに注意します
:::

## Pythonから利用する

上記のような例では比較的簡単でしたが、もっと複雑な処理をさせたいときにcurlを連続で呼び出すシェルを書くのはしんどいです。

Pythonでは、TiDB Cloud APIをラップした [`tidbcloudy`](https://github.com/Oreoxmt/tidbcloudy)というライブラリが提供されています。これを使うと、Pythonから簡単にAPIを利用することができます。

`tidbcloudy`を使って、プロジェクト中のすべてのクラスタを削除する例を見てみます。

```python
import os
import sys

import tidbcloudy

if len(sys.argv) != 2:
    print("USAGE: python delete_cluster.py [project_name]")
    exit()

# env variables
tidb_pub = os.environ.get('TIDB_PUB')
tidb_priv = os.environ.get('TIDB_PRIV')

project_name = sys.argv[1]

api = tidbcloudy.TiDBCloud(public_key=tidb_pub, private_key=tidb_priv)
project = next(filter(lambda p:p.name == project_name ,api.iter_projects()))

for c in project.iter_clusters():
    print(c)
    c.delete()
```

このようになります。`iter_clusters()` でプロジェクト中のクラスタのジェネレーターが使えるのがいいですね。

Python以外にも、go言語用のラッパーが作成されています。

https://github.com/c4pt0r/go-tidbcloud-sdk-v1

## おわりに

TiDB Cloudは他にも TiDB Cloud CLI や terraform などで自動化を行うことができますが、どちらも内部ではこのAPIを利用しています。APIを直接利用する方法を知っておくと自動化の幅が広がると思うので、ぜひ試してみてください。