データサービスの利用開始

データサービス（ベータ版）を使用すると、カスタムAPIエンドポイントを使用してHTTPSリクエスト経由でTiDB Cloudデータにアクセスでき、HTTPSに対応したあらゆるアプリケーションやサービスとシームレスに統合できます。

ヒント：

TiDB Cloudは、TiDBクラスタ向けにChat2Query APIを提供します。有効化すると、 TiDB Cloudは自動的にChat2Queryという名前のシステムデータアプリと、データサービス内にChat2Dataエンドポイントを作成します。このエンドポイントを呼び出すことで、指示を与えることにより、AIにSQLステートメントを生成および実行させることができます。

詳細については、 Chat2Query API を使い始めましょう参照してください。

このドキュメントでは、データアプリの作成、開発、テスト、デプロイ、エンドポイントの呼び出しなど、 TiDB Cloud Data Service（ベータ版）を迅速に使い始める方法について説明します。データアプリとは、特定のアプリケーションのデータにアクセスするために使用できるエンドポイントの集合です。

始める前に

データアプリを作成する前に、AWS上にクラスターがTiDB Cloud Starter作成されていることを確認してください。クラスターがない場合は、手順TiDB Cloud StarterまたはEssential クラスタを作成します。に従って作成してください。

注記：

データサービスは、AWS でホストされているTiDB Cloud Starterクラスターでのみ利用可能です。TiDB TiDB Cloud Dedicatedクラスターでデータサービスを使用するには、 TiDB Cloudサポートお問い合わせください。

サンプルデータアプリから始めてみましょう

データサービスを使い始めるには、サンプルデータアプリを作成するのが最適です。プロジェクトにまだデータアプリがない場合は、データサービスページの画面上の指示に従ってサンプルデータアプリを作成し、このアプリを使ってデータサービスの機能を試してみてください。

1. TiDB Cloudコンソールでクリック左側のナビゲーションペインにある「データサービス」をクリックしてください。

2. データサービスページで、 「サンプルデータアプリの作成」をクリックします。ダイアログが表示されます。

3. ダイアログで、必要に応じてアプリ名を更新し、データアプリがアクセスするクラスターを選択してから、 [作成]をクリックします。

   作成プロセスは数秒で完了します。

   注記：

   現在のプロジェクトにクラスターが存在しない場合は、 「データソースのリンク」ドロップダウンリストの「新しいクラスタの作成」をクリックして、まずクラスターを作成できます。

4. サンプルデータアプリが自動的に作成されると、アプリ名、左側のペインにエンドポイントの一覧、中央のペインにエンドポイントのSQLステートメント、右側にサンプルデータアプリの使用方法に関する説明が表示されます。

5. 右側の指示に従ってエンドポイントを選択し、curlコマンドを使用してエンドポイントを呼び出してください。

独自のデータアプリを始めましょう

データサービスの利用を開始するには、独自のデータアプリを作成し、以下の手順に従って開発、テスト、デプロイ、エンドポイントの呼び出しを行うこともできます。

ステップ1. データアプリを作成する

データアプリを作成するには、以下の手順を実行してください。

1. TiDB Cloudコンソールでクリック左側のナビゲーションペインにある「データサービス」をクリックしてください。

2. プロジェクトのデータサービスページ目で、クリックします左側のペインでデータアプリを作成します。

   ヒント：

   これがプロジェクトで初めて作成するデータアプリの場合は、ページ中央の「データアプリを作成」をクリックしてください。

3. 「データアプリの作成」ダイアログで、名前と説明を入力し、データアプリがアクセスするクラスターを選択します。

   注記：

   デフォルトでは、データアプリの種類は標準データアプリです。Chat2Queryデータアプリを作成する場合は、このドキュメントではなく、 Chat2Query API を使い始めようを参照してください。

4. （オプション）データアプリのエンドポイントを、お好みのGitHubリポジトリとブランチに自動的にデプロイするには、 「GitHubに接続」を有効にしてから、以下の手順を実行してください。

   1. GitHubで「インストール」をクリックし、画面の指示に従って、 TiDB Cloud Data Serviceをアプリケーションとして対象のリポジトリにインストールしてください。

   2. TiDB Cloudコンソールに戻り、 「承認」をクリックしてGitHub上のアプリケーションへのアクセスを承認してください。

   3. データアプリの設定ファイルを保存するターゲットリポジトリ、ブランチ、およびディレクトリを指定してください。

   注記：

   • ディレクトリ名はスラッシュ（ / ）で始まる必要があります。例えば、 /mydataように指定します。指定したディレクトリが対象のリポジトリとブランチに存在しない場合は、自動的に作成されます。
   • リポジトリ、ブランチ、ディレクトリの組み合わせによって構成ファイルのパスが識別されます。このパスはデータアプリ間で一意である必要があります。指定したパスが既に他のデータアプリで使用されている場合は、新しいパスを指定する必要があります。そうしないと、現在のデータアプリ用にTiDB Cloudコンソールで構成されたエンドポイントによって、指定したパス内のファイルが上書きされます。

5. 「データアプリの作成」をクリックします。詳細ページデータサービス項目）が表示されます。

6. データアプリをGitHubに接続するように設定している場合は、指定したGitHubディレクトリを確認してください。1 データアプリの設定ファイル tidb-cloud-data-serviceによってディレクトリにコミットされていることが確認できれば、データアプリがGitHubに正常に接続されていることを意味します。

   新しいデータ アプリでは、自動同期とデプロイ、およびレビュー ドラフトがデフォルトで有効になっているため、 TiDB Cloudコンソールと GitHub 間でデータ アプリの変更を簡単に同期し、デプロイ前に変更を確認できます。GitHub 統合の詳細については、 GitHub を使用してデータ アプリの変更を自動的にデプロイ参照してください。

ステップ2. エンドポイントを開発する

エンドポイントとは、SQL文を実行するようにカスタマイズできるWeb APIのことです。

新しいエンドポイントを作成するには、新しく作成したデータアプリを見つけて、アプリ名の右側にある「+**エンドポイントの作成」**をクリックします。

プロパティを構成する

右側のペインで、 [プロパティ]タブをクリックし、エンドポイントのプロパティを設定します。例えば、次の項目を設定します。

• パス：ユーザーがエンドポイントにアクセスするために使用するパス。リクエストメソッドとパスの組み合わせは、データアプリ内で一意である必要があります。

• エンドポイント URL : (読み取り専用) URL は、対応するクラスターが配置されているリージョン、データ アプリのサービス URL、およびエンドポイントのパスに基づいて自動的に生成されます。たとえば、エンドポイントのパスが/my_endpoint/get_idの場合、エンドポイント URL はhttps://<region>.data.tidbcloud.com/api/v1beta/app/<App ID>/endpoint/my_endpoint/get_idになります。

• リクエストメソッド：エンドポイントのHTTPメソッド。2 GETデータの取得、 POSTはデータの作成または挿入、 PUTデータの更新または変更、 DELETEデータの削除に使用できます。

エンドポイントプロパティの詳細については、 プロパティを構成する参照してください。

SQL文を書く

エンドポイントの SQL ステートメントをカスタマイズできます。 SQLエディタこれは、データサービスページの中央のペインです。

1. クラスターを選択してください。

   注記：

   データ アプリにリンクされているクラスターのみがドロップダウン リストに表示されます。リンクされたクラスターを管理するには、 リンクされたクラスターを管理する参照してください。

   SQLエディタの上部にあるドロップダウンリストから、SQLステートメントを実行するクラスタを選択します。すると、右側のペインにある「スキーマ」タブで、そのクラスタに属するすべてのデータベースを表示できます。

2. SQL文を記述してください。

   データのクエリや変更を行う前に、まず SQL ステートメントでデータベースを指定する必要があります。例: USE database_name; 。

   SQLエディタでは、テーブル結合クエリ、複雑なクエリ、集計関数などのステートメントを記述できます。また、単に--の後に指示を入力するだけで、AIがSQLステートメントを自動生成することも可能です。

   注記：

   TiDB Cloudの AI 機能を試すには、PingCAP と Amazon Bedrock が研究とサービス改善のためにコード スニペットを使用することを許可する必要があります。詳細については、 AIによるSQLクエリ生成を有効または無効にする参照してください。

   パラメータを定義するには、SQL文に${ID}ような変数プレースホルダーとして挿入します。例えば、 SELECT * FROM table_name WHERE id = ${ID}ように入力します。その後、右側のペインにある「パラメータ」タブをクリックして、パラメータの定義とテスト値を変更します。

   注記：

   • パラメータ名は大文字と小文字を区別します。
   • このパラメータは、テーブル名または列名として使用することはできません。

   • 定義セクションでは、クライアントがエンドポイントを呼び出す際にパラメータが必須かどうか、データ型、およびパラメータのデフォルト値を指定できます。
   • 「テスト値」セクションでは、パラメーターのテスト値を設定できます。テスト値は、SQLステートメントの実行時やエンドポイントのテスト時に使用されます。テスト値を設定しない場合は、デフォルト値が使用されます。
   • 詳細については、 パラメータを設定する参照してください。

3. SQL文を実行します。

   SQL文にパラメータを挿入している場合は、右側のペインにある「パラメータ」タブで、パラメータにテスト値またはデフォルト値が設定されていることを確認してください。設定されていない場合、エラーが返されます。

   macOSの場合：

   • エディタにステートメントが1つしかない場合は、それを実行するには、 ⌘ + Enterを押すか、クリックします。 走る。

   • エディタに複数のステートメントがある場合、それらのステートメントを1つまたは複数順番に実行するには、カーソルを対象のステートメントの上に置くか、カーソルで対象のステートメントの行を選択し、 ⌘ + Enterキーを押すか、 [実行]をクリックします。

   • エディタ内のすべてのステートメントを順番に実行するには、 ⇧ + ⌘ + Enterキーを押すか、カーソルですべてのステートメントの行を選択して[実行]をクリックします。

   WindowsまたはLinuxの場合：

   • エディタにステートメントが 1 つしかない場合は、それを実行するには、 Ctrl + Enterキーを押すか、クリックします。 走る。

   • エディタに複数のステートメントがある場合、それらのステートメントを1つまたは複数順番に実行するには、カーソルを対象のステートメントの上に置くか、カーソルで対象のステートメントの行を選択し、 Ctrl + Enterキーを押すか、 [実行]をクリックします。

   • エディタ内のすべてのステートメントを順番に実行するには、 Shift + Ctrl + Enterキーを押すか、カーソルですべてのステートメントの行を選択して[実行]をクリックします。

   ステートメントを実行すると、ページ下部の「結果」タブにクエリ結果がすぐに表示されます。

ステップ3．エンドポイントのテスト（オプション）

エンドポイントを設定した後、デプロイ前にエンドポイントをテストして、期待どおりに動作するかどうかを確認できます。

エンドポイントをテストするには、右上隅の「テスト」をクリックするか、 F5キーを押してください。

すると、ページ下部の「HTTPレスポンス」タブでレスポンスを確認できます。レスポンスの詳細については、 エンドポイントの応答参照してください。

ステップ4. エンドポイントをデプロイ

エンドポイントをデプロイするには、以下の手順を実行してください。

1. エンドポイントの詳細ページで、右上隅にある「デプロイ」をクリックします。

2. デプロイを確定するには、 「デプロイ」をクリックしてください。エンドポイントが正常にデプロイされると、 「エンドポイントがデプロイされました」というメッセージが表示されます。

   デプロイ履歴を表示するには、左側のペインでデータアプリの名前をクリックし、右側のペインで「デプロイ」タブをクリックします。

ステップ5. エンドポイントを呼び出す

HTTPSリクエストを送信することでエンドポイントを呼び出すことができます。エンドポイントを呼び出す前に、まずデータアプリのAPIキーを取得する必要があります。

1. APIキーを作成する

1. データサービスページ目の左側のペインで、データアプリの名前をクリックすると、その詳細が表示されます。

2. 認証エリアで、 「APIキーの作成」をクリックします。

3. 「APIキーの作成」ダイアログボックスで、以下の操作を行います。

   1. （任意）APIキーの説明を入力してください。

   2. APIキーの役割を選択してください。

      このロールは、APIキーがデータアプリにリンクされたクラスターに対してデータの読み取りまたは書き込みを行えるかどうかを制御するために使用されます。ロールはReadOnlyまたはReadAndWriteから選択できます。

      • ReadOnly ：APIキーSHOW DESC SELECT USE EXPLAIN 。
      • ReadAndWrite ：APIキーによるデータの読み書きを許可します。このAPIキーを使用して、DMLステートメントやDDLステートメントなど、すべてのSQLステートメントを実行できます。

   3. （オプション）APIキーの希望するレート制限を設定します。

4. 「次へ」をクリックします。公開鍵と秘密鍵が表示されます。

   秘密鍵を安全な場所にコピーして保存したことを確認してください。このページを離れると、完全な秘密鍵を再度取得することはできません。

5. 「完了」をクリックしてください。

APIキーの詳細については、 データサービスのAPIキー参照してください。

2. コード例を取得する

TiDB Cloudは、エンドポイントを呼び出すのに役立つコード例を生成します。コード例を取得するには、以下の手順を実行してください。

1. データサービスページ目の左側のペインで、エンドポイントの名前をクリックし、右上隅の「...」 > 「コード例」をクリックします。 「コード例」ダイアログボックスが表示されます。

2. ダイアログボックスで、エンドポイントを呼び出すために使用するクラスターとデータベースを選択し、コード例をコピーします。

   curlコードの例を以下に示します。

   エンドポイントのドラフトバージョンを呼び出すには、 endpoint-type: draftヘッダーを追加する必要があります。

   curl --digest --user '<Public Key>:<Private Key>' \
     --request GET 'https://<region>.data.tidbcloud.com/api/v1beta/app/<App ID>/endpoint/<Endpoint Path>' \
     --header 'endpoint-type: draft'
   

   オンライン環境でコード例を確認する前に、まずエンドポイントをデプロイする必要があります。

   エンドポイントの最新オンラインバージョンを呼び出すには、次のコマンドを使用します。

   curl --digest --user '<Public Key>:<Private Key>' \
     --request GET 'https://<region>.data.tidbcloud.com/api/v1beta/app/<App ID>/endpoint/<Endpoint Path>'
   

   注記：

   • リージョンドメイン<region>.data.tidbcloud.comを要求することで、TiDBクラスタが配置されているリージョンのエンドポイントに直接アクセスできます。
   • あるいは、リージョンを指定せずにグローバルドメインdata.tidbcloud.comリクエストを送信することもできます。この場合、 TiDB Cloudはリクエストをターゲットリージョンに内部的にリダイレクトしますが、レイテンシーが増加する可能性があります。この方法を選択する場合は、エンドポイントを呼び出す際にcurlコマンドにオプション--location-trustedを追加してください。

3. コード例を使用する

コード例をアプリケーションに貼り付けて実行してください。そうすれば、エンドポイントからの応答を取得できます。

• <Public Key>と<Private Key>プレースホルダーを、ご自身のAPIキーに置き換えてください。
• エンドポイントにパラメータが含まれている場合は、エンドポイントを呼び出す際にパラメータ値を指定してください。

エンドポイントを呼び出した後、JSON形式のレスポンスを確認できます。以下に例を示します。

{
  "type": "sql_endpoint",
  "data": {
    "columns": [
      {
        "col": "id",
        "data_type": "BIGINT",
        "nullable": false
      },
      {
        "col": "type",
        "data_type": "VARCHAR",
        "nullable": false
      }
    ],
    "rows": [
      {
        "id": "20008295419",
        "type": "CreateEvent"
      }
    ],
    "result": {
      "code": 200,
      "message": "Query OK!",
      "start_ms": 1678965476709,
      "end_ms": 1678965476839,
      "latency": "130ms",
      "row_count": 1,
      "row_affect": 0,
      "limit": 50
    }
  }
}

対応の詳細については、 エンドポイントの応答参照してください。

もっと詳しく知る

• データサービス概要
• Chat2Query API を使い始めよう
• データアプリを管理する
• エンドポイントの管理