[TiDB] Data Serviceチュートリアル

この記事は[TiDB Advent Calendar 2023](https://qiita.com/advent-calendar/2023/tidb)の7日目です。

## TiDB CloudのData Service機能について

TiDB CloudはTiDBをクラウド上で提供するマネージドデータベースなのですが、単にデータベースを提供するだけではなく、クラウド上にあることを生かした機能拡張も提供しています。その一つが今日ご紹介する[Data Service](https://docs.pingcap.com/ja/tidbcloud/data-service-overview)です。
Data Serviceは、SQLを使ってRESTエンドポイントを作成するローコードプラットフォームです。また、APIの定義は[OpenAPI](https://www.openapis.org/)形式となっており、[Github](https://github.com/)と連携してCDも可能となっています。

## チュートリアル内容

このチュートリアルでは、TiDB Serverlessのクラスタを起動して、CSVファイルからデータベースを作成し、そのデータを取得、更新できるAPIを公開します。公式Blogの[Effortlessly Transform CSV into a REST API with TiDB Cloud Data Services](https://www.pingcap.com/blog/backend-management-csv-rest-api-tidb-cloud-data-service/)をベースにしています。
サクサク進めば10分程度で完了すると思います。

画面の流れを[storylane](https://pingcap-japan.storylane.io/share/nkd3hdxo7y9f)でも公開しています。実際の操作の流れが分かるので、是非ご覧ください。

![demo.gif](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/12495/ef978a3f-ccfe-4741-5c19-2758e681942a.gif)


## 1. TiDB Serverlessクラスタの起動

TiDB cloudのサインアップがまだの方は、サインアップを行います。コンソールのUIに慣れるには[こちらのチュートリアル](https://docs.pingcap.com/ja/tidbcloud/tidb-cloud-quickstart)を見ながら進めていただくのが良いと思います。

今回のチュートリアルのためにクラスタを一つ立ち上げます。`Clusters`メニューから、`Create Cluster`ボタンを押し、クラスタを作成します。リージョンはどこでも構いません。また、今回のチュートリアル範囲は無料帯で可能ですので、`Spending Limit`も $0.0 のままで問題ありません。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/12495/8dfc48c5-4a40-eacb-0929-7f2dbac64e26.png)


## 2. CSVファイルの読み込み

作成したクラスタに、CSVファイルを読み込みます。テーブル定義もCSVファイルをベースに作ってしまいます。

### 2.1 ファイルの取得

対象となるCSVファイルを用意します。今回は上記Blogにある[サンプル従業員テーブル](https://docs.google.com/spreadsheets/d/1VMsjtrfwcw1-jlvmZ8ZfPEPla5SU5yzWu9pOuDEFPB8/edit?__hstc=86493575.132f4f7227146eb1ab7ae6f90da50137.1669946924197.1701419487324.1701477529610.829&__hssc=86493575.3.1701477529610&__hsfp=388741734#gid=0)を利用します。CSV形式でダウンロードしてください。

### 2.2 Import画面と設定

先ほど作成したクラスタを開き、左側のメニューの`Data`の`Import`を選択します。出てきた画面のDrag&Dropエリアに先ほどダウンロードしたファイルをアップロードします。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/12495/9aecbadf-3f3d-cdbe-757f-b4177ba783c5.png)

正常に読み込まれた後、データベースとテーブルを指定します。データベースはデフォルトの`test`、テーブル名は任意ですがここでは`Employee`としておきます。

`Preview`を押しプレビューに進みます。デフォルトでCSVのヘッダがカラム名にマップされていると思います。
ここで`empid`をプライマリーキーにしておきます。`empid`の行のPrimary Keyにチェックを入れておきます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/12495/866171e8-63b4-4ef0-ba17-b95dde8f25b0.png)


ここまで出来たら`Start Import`を押して、インポート開始です。

### 2.3 確認

インポート自体はすぐに終わると思います。終わったらそのまま右下の `Explore your data with Chat2Query` ボタンを押します。Web IDEに遷移すると最初の10件を表示するSELECT文が出来ているので、その行にカーソルを合わせてCtrl+Enterを押すと実行されます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/12495/9ba09710-ab0c-363b-9c24-e6853da37080.png)


画面下部に取得したレコードが表示されているのを確認します。

## 3. APIの作成

データベースの準備ができたので、APIを作成していきます。Data Serviceはクラスタ毎のサービスではなく、TiDB Cloudの組織単位のサービスです。そのため、トップレベルメニューの`Clusters`の下に`Data Service`があります。

### 3.1 DataAppの作成

`Data Service`メニューからData Serviceの画面を開きます。`Create DataApp` を押してDataAppを作成します。DataAppはこれから作成する一連のAPIをまとめるグループです。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/12495/ba557954-f897-2294-4cd2-8ce0f08bb5f9.png)


`DataApp Name`をEmployee Management、`Link Data Source`で作成したクラスタを選択します。`DataApp Type`はデフォルトのままにしておきます。

`Create`を押すとDataAppが作成されます。

### 3.2 自動生成によるAPIエンドポイント作成

作成されたDataAppの右側にある`+`を押すと表示される選択肢から、`Autogenerate Endpoint`を選択します。
表示されたダイアログで下記を設定します。

* `Cluster` `Database` `Table` - インポートしたデータが保存されているテーブルを指定します。
* `Auto-Depoloy Endpoint` - on に設定

それ以外はデフォルトのままで問題ありません。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/12495/67a47b85-ceb3-21d6-f6b6-87471dbb7920.png)

`Generate` を押して少し待つと、DataAppの下にGET/POSTなどのエンドポイントが出来ます。

APIの定義を見てみましょう。GETやPOSTなどのメソッドを選択すると、右側に元となるSQLが表示されます。
この定義を変更すると、APIが更新したり返したりする内容を変更できます。また、パラメーターも設定でき、
`${empid}`のような形式で指定することでSQLでその値を利用できます。
パラメーターの詳細はSQLエディタの右側のペインで指定します。今回はその部分の説明は割愛しますが、色々試してみていただければ分かると思います。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/12495/f36c023c-adee-b5b0-4280-bedf6c4594de.png)


### 3.3 APIキーの取得

DataAppをクリックして、右側の画面の`Authentication`セクションから`Create API Key`ボタンを押します。キーの名称は任意で構いませんが、`Role`は更新もあるのでReadAndWriteとします。
`Create`を押した後のPublic KeyとPrivate Keyをエディタなどにコピーしておきます。

## 4. 作成したAPIの確認

これでAPIの準備ができました。実際に動かして確認してみます。

### 4.1 APIドキュメント

DataApp画面の右上上部の`View API Docs`ボタンを押します。SwaggerのUIが開き、それぞれのAPI仕様が確認出来ます。試しにGETのレスポンスを確認すると、`columns`,`rows`の属性を持ち、メタデータと結果の両方を返すことが分かります。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/12495/4a897c1f-358e-f09e-f5ec-d78ed34205e7.png)


### 4.2 APIを叩いてみる

実際にSwagger UIからAPIを叩くには認証する必要があります。`Authorize`ボタンを押すとBasic認証の画面が出てきます。ここの`User Name`にAPI KeyのPublic Keyを、`Password`にPrivate Keyを入力すると認証できます。

認証後はExecuteをすると実際にAPIを実行した結果が返ります。試しにempidに1001を指定して実行すると、実際のデータが返るのが確認できます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/12495/c102648a-dc28-7e01-40b5-41e33e991acf.png)


## 5. おわりに

今回はCSVファイルを公開するAPIでしたが、同様に任意のデータベースを様々なSQLを使って公開することができます。
また、Github Actionと連携させたり、ChatGPTsと連携することも可能です。これらの利用法はまた別の記事で紹介していきます。皆さんも試して見てください。