TiDB Cloud
TiDB Self-Managed
Learning Center
お問い合わせ

データサービスを始める

データ サービス (ベータ版) を使用すると、カスタム API エンドポイントを使用して HTTPS リクエスト経由でTiDB Cloudデータにアクセスし、HTTPS と互換性のある任意のアプリケーションまたはサービスとシームレスに統合できます。

ヒント：

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

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

このドキュメントでは、データ アプリを作成し、エンドポイントを開発、テスト、デプロイ、および呼び出すことで、 TiDB Cloud Data Service (ベータ版) をすぐに使い始める方法を紹介します。データ アプリは、特定のアプリケーションのデータにアクセスするために使用できるエンドポイントのコレクションです。

始める前に

データ アプリを作成する前に、クラスターTiDB Cloudサーバーレスを作成していることを確認してください。クラスターがない場合は、 TiDB Cloud Serverless クラスターを作成するの手順に従って作成してください。

サンプルデータアプリを使い始める

サンプル データ アプリを作成することは、データ サービスの使用を開始するのに最適な方法です。プロジェクトにまだデータ アプリがない場合は、データ サービスページの画面上の指示に従ってサンプル データ アプリを作成し、このアプリを使用してデータ サービスの機能を調べることができます。

  1. TiDB Cloudコンソールで、左側のナビゲーション ペインでデータ サービスを選択します。

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

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

    作成プロセスには数秒かかります。

    注記：

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

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

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

独自のデータアプリを使い始める

Data Service の使用を開始するには、独自のデータ アプリを作成し、次の手順に従ってエンドポイントを開発、テスト、デプロイ、および呼び出すこともできます。

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

データ アプリを作成するには、次の手順を実行します。

  1. TiDB Cloudコンソールで、左側のナビゲーション ペインでデータ サービスを選択します。

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

    ヒント：

    これがプロジェクトの最初のデータ アプリである場合は、ページの中央にある[データ アプリの作成]をクリックします。

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

    注記：

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

  4. (オプション) データ アプリのエンドポイントを優先 GitHub リポジトリとブランチに自動的にデプロイするには、 GitHub に接続を有効にして、次の操作を行います。

    1. 「GitHub にインストール」をクリックし、画面の指示に従って、 TiDB Cloud Data Service をアプリケーションとしてターゲット リポジトリにインストールします。

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

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

    注記：

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

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

  6. データ アプリを GitHub に接続するように構成している場合は、指定した GitHub ディレクトリを確認してください。 データアプリ構成ファイルが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 メソッドGET使用してデータを取得し、 POST使用してデータを作成または挿入し、 PUT使用してデータを更新または変更し、 DELETE使用してデータを削除します。

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

SQL文を書く

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

  1. クラスターを選択します。

    注記：

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

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

  2. SQL ステートメントを記述します。

    データをクエリまたは変更する前に、まず SQL ステートメントでデータベースを指定する必要があります。たとえば、 USE database_name;です。

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

    注記：

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

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

    注記：

    • パラメータ名では大文字と小文字が区別されます。
    • パラメータはテーブル名または列名として使用できません。
    • 定義セクションでは、クライアントがエンドポイントを呼び出すときにパラメーターが必須かどうか、パラメーターのデータ型、およびデフォルト値を指定できます。
    • テスト値セクションでは、パラメータのテスト値を設定できます。テスト値は、SQL ステートメントを実行するとき、またはエンドポイントをテストするときに使用されます。テスト値を設定しない場合は、デフォルト値が使用されます。
    • 詳細についてはパラメータを設定する参照してください。

  3. SQL ステートメントを実行します。

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

    • macOS
    • Windows/Linux

    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 キーはSELECT 、 SHOW 、 USE 、 DESC 、 EXPLAINステートメントなどのデータのみを読み取ることができます。
      • ReadAndWrite : API キーによるデータの読み取りと書き込みを許可します。この API キーを使用して、DML ステートメントや DDL ステートメントなどのすべての SQL ステートメントを実行できます。

    3. (オプション) API キーに必要なレート制限を設定します。

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

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

  5. 「完了」をクリックします。

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

2. コード例を取得する

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

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

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

    curl コードの例は次のとおりです。

    • Test Environment
    • Online Environment

    エンドポイントのドラフト バージョンを呼び出すには、 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
    }
  }
}

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

もっと詳しく知る

このページは役に立ちましたか？