重要

このページは英語版のページを機械翻訳しています。原文はこちらからご覧ください。

データサービスを始めてみる

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

ヒント：
TiDB Cloud は、 TiDB クラスター用の Chat2Query API を提供します。有効にすると、 TiDB Cloud はChat2Queryと呼ばれるシステムデータアプリと Data Service に Chat2Data エンドポイントを自動的に作成します。このエンドポイントを呼び出して、AI に指示を提供して SQL ステートメントを生成および実行させることができます。
詳細については、 Chat2Query API を使ってみるを参照してください。

このドキュメントでは、データアプリの作成、開発、テスト、デプロイ、エンドポイントの呼び出しによって、 TiDB Cloud Data Service (ベータ) をすぐに開始する方法を紹介します。

あなたが始める前に

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

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

データアプリは、特定のアプリケーションのデータにアクセスするために使用できるエンドポイントのコレクションです。データアプリを作成するには、次の手順を実行します。

TiDB Cloudコンソールで、をクリックします。左側のナビゲーションペインのデータサービス。
[データサービス]ページで、 [データアプリの作成]をクリックします。
[データアプリの作成]ダイアログで、名前と説明を入力し、データアプリがアクセスするクラスターを選択します。
(オプション) データアプリのエンドポイントを優先する GitHub リポジトリとブランチに自動的にデプロイするには、 [GitHub に接続]を有効にして、次の手順を実行します。
1. [GitHub にインストール] をクリックし、画面上の指示に従ってTiDB Cloud Data Serviceをアプリケーションとしてターゲットリポジトリにインストールします。
2. 「承認」をクリックして、GitHub 上のアプリケーションへのアクセスを承認します。
3. データアプリの構成ファイルを保存するターゲットリポジトリ、ブランチ、ディレクトリを指定します。
注記：
- ディレクトリはスラッシュ ( / ) で始まる必要があります。たとえば、 /mydata 。指定したディレクトリがターゲットリポジトリおよびブランチに存在しない場合は、自動的に作成されます。
- リポジトリ、ブランチ、ディレクトリの組み合わせによって構成ファイルのパスが識別されます。このパスはデータアプリ間で一意である必要があります。指定したパスがすでに別のデータアプリで使用されている場合は、代わりに新しいパスを指定する必要があります。そうしないと、現在のデータアプリのTiDB Cloudコンソールで構成されたエンドポイントによって、指定したパス内のファイルが上書きされます。
[データアプリの作成]をクリックします。 データサービス詳細ページが表示されます。
データアプリを GitHub に接続するように構成している場合は、指定した GitHub ディレクトリを確認してください。データアプリ構成ファイル tidb-cloud-data-serviceまでにディレクトリにコミットされていることがわかります。これは、データアプリが GitHub に正常に接続されていることを意味します。
新しいデータアプリでは、自動同期とデプロイメントおよびドラフトのレビューがデフォルトで有効になっているため、 TiDB Cloudコンソールと GitHub の間でデータアプリの変更を簡単に同期し、デプロイ前に変更をレビューできます。 GitHub 統合の詳細については、データアプリの変更を GitHub で自動的にデプロイを参照してください。

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

エンドポイントは、SQL ステートメントを実行するためにカスタマイズできる Web API です。

データアプリを作成すると、デフォルトのuntitled endpoint自動的に作成されます。デフォルトのエンドポイントを使用してTiDB Cloudクラスターにアクセスできます。

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

プロパティの構成

右側のペインで、 「プロパティ」タブをクリックし、次のようなエンドポイントのプロパティを設定します。

Path : ユーザーがエンドポイントにアクセスするために使用するパス。リクエストメソッドとパスの組み合わせは、データアプリ内で一意である必要があります。
エンドポイント 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 ステートメントをカスタマイズできます。

クラスターを選択します。
注記：
データアプリにリンクされているクラスターのみがドロップダウンリストに表示されます。リンクされたクラスターを管理するには、リンクされたクラスターを管理するを参照してください。
SQL エディターの上部で、SQL ステートメントを実行するクラスターをドロップダウンリストから選択します。その後、右側のペインの[スキーマ]タブで、このクラスターのすべてのデータベースを表示できます。
SQL ステートメントを作成します。
データをクエリまたは変更する前に、まず SQL ステートメントでデータベースを指定する必要があります。たとえば、 USE database_name; 。
SQL エディターでは、テーブル結合クエリ、複雑なクエリ、集計関数のステートメントを作成できます。 --に続けて指示を入力するだけで、AI に SQL ステートメントを自動的に生成させることもできます。
パラメーターを定義するには、SQL ステートメントに${ID}のような変数プレースホルダーとして挿入します。たとえば、 SELECT * FROM table_name WHERE id = ${ID} 。次に、右側のペインの「Params」タブをクリックして、パラメータ定義とテスト値を変更できます。
注記：
- パラメータ名では大文字と小文字が区別されます。
- このパラメーターをテーブル名または列名として使用することはできません。
- 「定義」セクションでは、クライアントがエンドポイントを呼び出すときにパラメーターが必要かどうか、データ型 ( STRING 、 NUMBER 、 INTEGER 、またはBOOLEAN )、パラメーターのデフォルト値を指定できます。 STRINGタイプのパラメータを使用する場合は、引用符 ( 'または" ) を追加する必要はありません。たとえば、 foo STRINGタイプに対して有効であり、 "foo"として処理されますが、 "foo"は"\"foo\""として処理されます。
- 「テスト値」セクションでは、パラメーターのテスト値を設定できます。テスト値は、SQL ステートメントを実行するとき、またはエンドポイントをテストするときに使用されます。テスト値を設定しない場合は、デフォルト値が使用されます。
- 詳細については、パラメータを設定するを参照してください。
SQL ステートメントを実行します。
SQL ステートメントにパラメータを挿入した場合は、右側のペインの[パラメータ]タブでパラメータのテスト値またはデフォルト値を設定していることを確認してください。それ以外の場合は、エラーが返されます。
SQL ステートメントを実行するには、カーソルで SQL の行を選択し、 「実行」 > 「カーソル位置で実行」をクリックします。
SQL エディターですべての SQL ステートメントを実行するには、 「実行」をクリックします。この場合、最後の SQL 結果のみが返されます。
ステートメントを実行すると、ページ下部の[結果]タブにクエリ結果がすぐに表示されます。

ステップ 3. エンドポイントをテストする (オプション)

エンドポイントを構成した後、展開する前にエンドポイントをテストして、期待どおりに動作するかどうかを確認できます。

エンドポイントをテストするには、右上隅の「テスト」をクリックするか、 F5を押します。

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

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

エンドポイントをデプロイするには、次の手順を実行します。

エンドポイントの詳細ページで、右上隅にある「デプロイ」をクリックします。
「デプロイ」をクリックしてデプロイメントを確認します。エンドポイントが正常にデプロイされると、「エンドポイントがデプロイされました」というプロンプトが表示されます。
エンドポイントの詳細ページの右側のペインで、 「デプロイメント」タブをクリックすると、デプロイされた履歴を表示できます。

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

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

1. APIキーを作成する

データサービスページの左側のペインで、データアプリの名前をクリックして詳細を表示します。
「認証」領域で、 「API キーの作成」をクリックします。
[API キーの作成]ダイアログボックスで、説明を入力し、API キーのロールを選択します。
このロールは、API キーがデータアプリにリンクされたクラスターに対してデータの読み取りまたは書き込みを行えるかどうかを制御するために使用されます。 ReadOnlyまたはReadAndWrite役割を選択できます。
- ReadOnly : API キーはSELECT 、 SHOW 、 USE 、 DESC 、 EXPLAINステートメントなどのデータの読み取りのみを許可します。
- ReadAndWrite : API キーによるデータの読み取りと書き込みを許可します。この API キーを使用して、DML ステートメントや DDL ステートメントなどのすべての SQL ステートメントを実行できます。
「次へ」をクリックします。公開鍵と秘密鍵が表示されます。
秘密キーをコピーして安全な場所に保存したことを確認してください。このページを離れると、完全な秘密キーを再度取得することはできなくなります。
「完了」をクリックします。

2. コード例を取得する

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

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

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

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はリクエストを内部的にターゲットリージョンにリダイレクトしますが、これにより追加のレイテンシーが発生する可能性があります。この方法を選択した場合は、エンドポイントを呼び出すときに必ず--location-trustedオプションをcurl コマンドに追加してください。

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
    }
  }
}

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

データサービスを始めてみる

あなたが始める前に

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

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

プロパティの構成

SQL ステートメントを作成する

ステップ 3. エンドポイントをテストする (オプション)

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

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

1. APIキーを作成する

2. コード例を取得する

3. コード例を使用する

もっと詳しく知る

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

データサービスを始めてみる

あなたが始める前に

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

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

プロパティの構成

SQL ステートメントを作成する

ステップ 3. エンドポイントをテストする (オプション)

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

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

1. APIキーを作成する

2. コード例を取得する

3. コード例を使用する

もっと詳しく知る

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

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