重要

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

エンドポイントの管理

Data Service (ベータ) のエンドポイントは、SQL ステートメントを実行するようにカスタマイズできる Web API です。 WHERE句で使用される値など、SQL ステートメントのパラメータを指定できます。クライアントがエンドポイントを呼び出し、リクエスト URL 内のパラメータの値を指定すると、エンドポイントは指定されたパラメータを使用して SQL ステートメントを実行し、結果を HTTP 応答の一部として返します。

このドキュメントでは、 TiDB Cloudコンソールのデータアプリでエンドポイントを管理する方法について説明します。

あなたが始める前に

エンドポイントを作成する前に、次のことを確認してください。
- クラスターとデータアプリが作成されました。詳細については、データアプリを作成するを参照してください。
- エンドポイントが操作するデータベース、テーブル、列はターゲットクラスターにすでに存在します。
エンドポイントを呼び出す前に、データアプリで API キーを作成していることを確認してください。詳細については、 APIキーを作成するを参照してください。

エンドポイントを作成する

Data Service では、エンドポイントを自動的に生成することも、手動でエンドポイントを作成することもできます。

ヒント：
Chat2Query (ベータ版) では、SQL ファイルからエンドポイントを作成することもできます。詳細については、 SQL ファイルからエンドポイントを生成するを参照してください。

エンドポイントを自動的に生成する

TiDB Cloud Data Service では、次のように 1 つまたは複数のエンドポイントを一度に自動的に生成できます。

プロジェクトのデータサービスページに移動します。
左側のペインでターゲットのデータアプリを見つけ、アプリ名の右側にある[+]をクリックし、 [エンドポイントの自動生成]をクリックします。エンドポイント生成のダイアログが表示されます。
ダイアログで次の操作を行います。
1. 生成するエンドポイントのターゲットクラスター、データベース、テーブルを選択します。
  注記：
  [テーブル]ドロップダウンリストには、システムテーブルと列定義のないテーブルを除く、少なくとも 1 つの列を持つユーザー定義のテーブルのみが含まれます。
2. 生成するエンドポイントに対して HTTP オペレーション ( GET Retrieve 、 POST Create 、 PUT Updateなど) を少なくとも 1 つ選択します。
  選択した各操作に対して、 TiDB Cloudデータサービスは対応するエンドポイントを生成します。バッチ操作 ( POST Batch Createなど) を選択した場合、生成されたエンドポイントを使用して、1 つのリクエストで複数の行を操作できます。
3. (オプション) 操作のタイムアウトとタグを構成します。生成されたすべてのエンドポイントは、構成されたプロパティを自動的に継承し、後で必要に応じて変更できます。
4. (オプション)エンドポイントの自動展開オプション (デフォルトでは無効) は、生成されたエンドポイントの直接展開を有効にするかどうかを制御します。これを有効にすると、ドラフトレビュープロセスがスキップされ、生成されたエンドポイントは手動でのレビューや承認を必要とせずにすぐにデプロイされます。
「生成」をクリックします。
生成されたエンドポイントは、エンドポイントリストの先頭に表示されます。
新しいエンドポイントの生成されたエンドポイント名、SQL ステートメント、プロパティ、およびパラメーターを確認します。
- エンドポイント名: 生成されるエンドポイント名は選択したテーブルの名前であり、名前の前にリクエストメソッド ( GET 、 POST 、およびPUTなど) が表示されます。たとえば、選択したテーブル名がsample-tableで、選択した操作がPOST Createの場合、生成されたエンドポイントはPOST sample-tableと表示されます。
  - バッチ操作が選択されている場合、 TiDB Cloud Data Service は生成されたエンドポイントの名前に_batchを追加します。たとえば、選択したテーブル名がsample-tableで、選択した操作がPOST Batch Createの場合、生成されたエンドポイントはPOST sample-table_batchと表示されます。
  - 同じリクエストメソッドとエンドポイント名を持つエンドポイントがすでに存在する場合、 TiDB Cloud Data Service は生成されたエンドポイントの名前に_copyを追加します。たとえば、 sample-table_copy 。
- SQL ステートメント: TiDB Cloud Data Service は、テーブル列の仕様と選択されたエンドポイント操作に従って、生成されたエンドポイントの SQL ステートメントを自動的に書き込みます。エンドポイント名をクリックすると、ページの中央セクションにその SQL ステートメントが表示されます。
- エンドポイントプロパティ: TiDB Cloud Data Service は、選択に従ってエンドポイントパス、リクエストメソッド、タイムアウト、およびタグを自動的に構成します。ページの右側のペインにプロパティが表示されます。
- エンドポイントパラメーター: TiDB Cloud Data Service は、生成されたエンドポイントのパラメーターを自動的に構成します。パラメータはページの右側のペインにあります。
生成されたエンドポイントの名前、SQL ステートメント、プロパティ、パラメーターなどの詳細を変更する場合は、エンドポイントを開発するに記載されている手順を参照してください。

エンドポイントを手動で作成する

エンドポイントを手動で作成するには、次の手順を実行します。

プロジェクトのデータサービスページに移動します。
左側のペインでターゲットのデータアプリを見つけ、アプリ名の右側にある[+]をクリックし、 [エンドポイントの作成]をクリックします。
必要に応じてデフォルト名を更新します。新しく作成されたエンドポイントがエンドポイントリストの先頭に追加されます。
エンドポイントを開発するの手順に従って、新しいエンドポイントを構成します。

エンドポイントを開発する

エンドポイントごとに、TiDB クラスター上で実行する SQL ステートメントを作成したり、SQL ステートメントのパラメーターを定義したり、名前とバージョンを管理したりできます。

注記：
自動同期とデプロイを有効にしてデータアプリを GitHub に接続している場合は、GitHub を使用してエンドポイント構成を更新することもできます。 GitHub で行った変更はすべて、 TiDB Cloud Data Service に自動的にデプロイされます。詳細については、 GitHub を使用して自動的にデプロイを参照してください。

プロパティの構成

エンドポイントの詳細ページの右側のペインで、 「プロパティ」タブをクリックして、エンドポイントのプロパティを表示および構成できます。

基本特性

Path : ユーザーがエンドポイントにアクセスするために使用するパス。
- リクエストメソッドとパスの組み合わせは、データアプリ内で一意である必要があります。
- パスに使用できるのは、文字、数字、アンダースコア ( _ )、およびスラッシュ ( / ) のみです。パスはスラッシュ ( / ) で始まり、文字、数字、またはアンダースコア ( _ ) で終わる必要があります。たとえば、 /my_endpoint/get_id 。
- パスの長さは 64 文字未満である必要があります。
エンドポイント 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 : このメソッドは、 SELECTステートメントなどのデータのクエリまたは取得に使用します。
- POST : このメソッドを使用して、 INSERTステートメントなどのデータを挿入または作成します。
- PUT : このメソッドは、 UPDATEステートメントなどのデータを更新または変更するために使用します。
- DELETE : このメソッドは、 DELETEステートメントなどのデータを削除するために使用します。
説明(オプション): エンドポイントの説明。

高度なプロパティ

Timeout(ms) : エンドポイントのタイムアウト (ミリ秒単位)。
Max Rows : エンドポイントが操作または返すことができる最大行数。
タグ: エンドポイントのグループを識別するために使用されるタグ。
Pagination : このプロパティは、リクエストメソッドがGETで、エンドポイントの最後の SQL ステートメントがSELECT操作である場合にのみ使用できます。ページネーションが有効な場合、エンドポイントを呼び出すときにクエリパラメーターとしてpageとpage_size ( https://<region>.data.tidbcloud.com/api/v1beta/app/<App ID>/endpoint/my_endpoint/get_id?page=<Page Number>&page_size=<Page Size>など) を指定することで、結果をページネーションできます。詳細については、エンドポイントを呼び出す参照してください。
注記：
- リクエストにpageおよびpage_sizeパラメータを含めない場合、デフォルトの動作では、単一ページのMax Rowsプロパティで指定された最大行数が返されます。
- page_size Max Rowsプロパティ以下である必要があります。それ以外の場合は、エラーが返されます。
キャッシュレスポンス: このプロパティは、リクエストメソッドがGETの場合にのみ使用できます。キャッシュレスポンスが有効になっている場合、 TiDB Cloudデータサービスは、指定された有効期間 (TTL) 期間内にGETのリクエストによって返されたレスポンスをキャッシュできます。
Time-to-Live (s) : このプロパティは、キャッシュ応答が有効な場合にのみ使用できます。これを使用して、キャッシュされた応答の存続時間 (TTL) 期間を秒単位で指定できます。 TTL 期間中に同じGETリクエストを再度実行すると、Data Service はターゲットデータベースからデータを再度フェッチするのではなく、キャッシュされた応答を直接返します。これにより、クエリのパフォーマンスが向上します。
バッチ操作: このプロパティは、リクエストメソッドがPOST 、またはDELETEの場合にのみ表示されますPUTバッチ操作を有効にすると、1 つのリクエストで複数の行を操作できます。たとえば、エンドポイントを呼び出すときに、curl コマンドの--data-rawオプションにデータオブジェクトの配列を追加することで、単一のPOSTリクエストに複数行のデータを挿入できます。

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

エンドポイントの詳細ページの SQL エディターで、エンドポイントの SQL ステートメントを作成して実行できます。 --に続けて指示を入力するだけで、AI に SQL ステートメントを自動的に生成させることもできます。

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

パラメータを設定する

エンドポイントの詳細ページの右側のペインで、 「パラメータ」タブをクリックして、エンドポイントで使用されるパラメータを表示および管理できます。

「定義」セクションでは、パラメータの次のプロパティを表示および管理できます。

パラメータ名: 名前には文字、数字、アンダースコア ( _ ) のみを含めることができ、文字またはアンダースコア ( _ ) で始める必要があります。 pageとpage_sizeはパラメータ名として使用しないでください。これらはリクエスト結果のページネーション用に予約されています。
Required : リクエストでパラメータが必須かどうかを指定します。デフォルトの構成は不要に設定されています。
Type : パラメータのデータ型を指定します。サポートされている値はSTRING 、 NUMBER 、 INTEGER 、およびBOOLEANです。 STRING型パラメータを使用する場合は、引用符 ( 'または" ) を追加する必要はありません。たとえば、 foo STRINGタイプに対して有効であり、 "foo"として処理されますが、 "foo"は"\"foo\""として処理されます。
デフォルト値: パラメータのデフォルト値を指定します。
- 値がパラメータの型に変換できることを確認してください。それ以外の場合、エンドポイントはエラーを返します。
- パラメーターのテスト値を設定しない場合、エンドポイントのテスト時にデフォルト値が使用されます。

「テスト値」セクションでは、テストパラメータを表示および設定できます。これらの値は、エンドポイントをテストするときにパラメーター値として使用されます。値がパラメータの型に変換できることを確認してください。それ以外の場合、エンドポイントはエラーを返します。

バージョンの管理

エンドポイントの詳細ページの右側のペインで、 「デプロイメント」タブをクリックして、エンドポイントのデプロイされたバージョンを表示および管理できます。

[展開]タブでは、ドラフトバージョンを展開したり、オンラインバージョンを展開解除したりできます。

名前の変更

エンドポイントの名前を変更するには、次の手順を実行します。

プロジェクトのデータサービスページに移動します。
左側のペインで、ターゲットデータアプリの名前をクリックして、そのエンドポイントを表示します。
名前を変更するエンドポイントを見つけて、 [...] > [名前の変更] をクリックし、エンドポイントの新しい名前を入力します。

エンドポイントをテストする

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

ヒント：
データアプリを Postman にインポートした場合は、Postman でデータアプリのエンドポイントをテストすることもできます。詳細については、 Postman でデータアプリを実行するを参照してください。

プロジェクトのデータサービスページに移動します。
左側のペインで、ターゲットデータアプリの名前をクリックして、そのエンドポイントを表示します。
テストするエンドポイントの名前をクリックして、その詳細を表示します。
(オプション) エンドポイントにパラメータが含まれている場合は、テスト前にテスト値を設定する必要があります。
1. エンドポイントの詳細ページの右側のペインで、 「Params」タブをクリックします。
2. 「テスト値」セクションを展開し、パラメータのテスト値を設定します。
  パラメータのテスト値を設定しない場合は、デフォルト値が使用されます。
右上隅の「テスト」をクリックします。
ヒント：
あるいは、 F5 キーを押してエンドポイントをテストすることもできます。

エンドポイントをテストした後、ページの下部に応答が JSON として表示されます。 JSON 応答の詳細については、エンドポイントの応答を参照してください。

エンドポイントをデプロイ

注記：
自動同期とデプロイメントを有効にしてデータアプリを GitHub に接続している場合、GitHub で行ったデータアプリの変更はすべてTiDB Cloud Data Service に自動的にデプロイされます。詳細については、 GitHub を使用して自動的にデプロイを参照してください。

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

プロジェクトのデータサービスページに移動します。
左側のペインで、ターゲットデータアプリの名前をクリックして、そのエンドポイントを表示します。
デプロイするエンドポイントを見つけ、エンドポイント名をクリックして詳細を表示し、右上隅にある[デプロイ]をクリックします。
データアプリで[ドラフトの確認]が有効になっている場合は、行った変更を確認するためのダイアログが表示されます。レビューに基づいて変更を破棄するかどうかを選択できます。
「デプロイ」をクリックしてデプロイメントを確認します。エンドポイントが正常にデプロイされると、「エンドポイントがデプロイされました」というプロンプトが表示されます。
エンドポイントの詳細ページの右側のペインで、 「デプロイメント」タブをクリックすると、デプロイされた履歴を表示できます。

エンドポイントを呼び出す

エンドポイントを呼び出すには、エンドポイントの未デプロイのドラフトバージョンまたはデプロイされたオンラインバージョンのいずれかに HTTPS リクエストを送信できます。

ヒント：
データアプリを Postman にインポートした場合は、Postman でデータアプリのエンドポイントを呼び出すこともできます。詳細については、 Postman でデータアプリを実行するを参照してください。

前提条件

エンドポイントを呼び出す前に、API キーを作成する必要があります。詳細については、 APIキーを作成するを参照してください。

リクエスト

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

プロジェクトのデータサービスページに移動します。
左側のペインで、ターゲットデータアプリの名前をクリックして、そのエンドポイントを表示します。
呼び出したいエンドポイントを見つけて、 [...] > [コード例]をクリックします。 [コード例]ダイアログボックスが表示されます。
ヒント：
または、エンドポイント名をクリックして詳細を表示し、右上隅の[...] > [コード例]をクリックすることもできます。

ダイアログボックスで、エンドポイントの呼び出しに使用する環境と認証方法を選択し、コード例をコピーします。

注記：
コード例は、エンドポイントのプロパティとパラメーターに基づいて生成されます。
現在、 TiDB Cloudデータサービスは、curl コードサンプルのみを提供しています。

環境: 必要に応じて、テスト環境またはオンライン環境を選択します。オンライン環境は、エンドポイントを展開した後にのみ使用できます。
認証方法: [基本認証]または[ダイジェスト認証]を選択します。
- 基本認証では、 API キーを based64 でエンコードされたテキストとして送信します。
- ダイジェスト認証では、 API キーを暗号化された形式で送信するため、より安全です。
基本認証と比較して、ダイジェスト認証のcurlコードには追加の--digestのオプションが含まれています。

以下は、バッチ操作を有効にし、ダイジェスト認証を使用するPOSTリクエストのカールコードスニペットの例です。

Test Environment
Online Environment

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

curl --digest --user '<Public Key>:<Private Key>' \
  --request POST 'https://<region>.data.tidbcloud.com/api/v1beta/app/<App ID>/endpoint/<Endpoint Path>' \
  --header 'content-type: application/json'\
  --header 'endpoint-type: draft'
  --data-raw '[{
    "age": "${age}",
    "career": "${career}"
}]'

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

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

curl --digest --user '<Public Key>:<Private Key>' \
  --request POST 'https://<region>.data.tidbcloud.com/api/v1beta/app/<App ID>/endpoint/<Endpoint Path>'
  --header 'content-type: application/json'\
  --data-raw '[{
    "age": "${age}",
    "career": "${career}"
}]'

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

コード例をアプリケーションに貼り付け、必要に応じて例を編集して、実行します。
- <Public Key>と<Private Key>プレースホルダーを API キーに置き換える必要があります。詳細については、 APIキーを管理するを参照してください。
- エンドポイントのリクエストメソッドがGETで、エンドポイントのページネーションが有効になっている場合は、 page=<Page Number>とpage_size=<Page Size>の値を目的の値で更新することで、結果をページネーションできます。たとえば、1 ページあたり 10 項目の 2 ページ目を取得するには、 page=2とpage_size=10を使用します。
- エンドポイントのリクエストメソッドがPOSTまたはPUTの場合は、操作するデータの行に応じて--data-rawオプションを入力します。
  - バッチ操作が有効になっているエンドポイントの場合、 --data-rawオプションはデータオブジェクトの配列を受け入れるため、1 つのエンドポイントを使用して複数行のデータを操作できます。
  - バッチ操作が有効になっていないエンドポイントの場合、 --data-rawオプションは 1 つのデータオブジェクトのみを受け入れます。
- エンドポイントのリクエストメソッドがDELETEで、エンドポイントのバッチ操作が有効になっている場合は、curl コマンドで削除する複数の行をカンマ ( , ) で区切ることができます ( /endpoint/<Endpoint Path>?id=${id1},${id2},${id3}など)。
- エンドポイントにパラメーターが含まれている場合は、エンドポイントを呼び出すときにパラメーター値を指定します。

応答

エンドポイントを呼び出した後、JSON 形式で応答を確認できます。詳細については、データサービスのレスポンスコードとステータスコードを参照してください。

エンドポイントのデプロイを解除する

注記：
自動同期とデプロイが有効になっているデータアプリを GitHub に接続しましたがある場合、このデータアプリのエンドポイントのデプロイを解除すると、GitHub 上のこのエンドポイントの構成も削除されます。

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

プロジェクトのデータサービスページに移動します。
左側のペインで、ターゲットデータアプリの名前をクリックして、そのエンドポイントを表示します。
デプロイを解除するエンドポイントを見つけて、 [...] > [アンデプロイ]をクリックします。
「アンデプロイ」をクリックしてアンデプロイを確認します。

エンドポイントを削除する

注記：
エンドポイントを削除する前に、エンドポイントがオンラインでないことを確認してください。そうしないと、エンドポイントを削除できません。エンドポイントのデプロイを解除するには、エンドポイントのデプロイを解除するを参照してください。

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

プロジェクトのデータサービスページに移動します。
左側のペインで、ターゲットデータアプリの名前をクリックして、そのエンドポイントを表示します。
削除するエンドポイントの名前をクリックし、右上隅にある[...] > [削除]をクリックします。
「削除」をクリックして削除を確認します。