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

エンドポイントの管理

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

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

あなたが始める前に

  • エンドポイントを作成する前に、次の点を確認してください。

    • クラスターとデータ アプリを作成しました。詳細については、 データアプリを作成する参照してください。
    • エンドポイントが操作するデータベース、テーブル、および列は、ターゲット クラスターにすでに存在しています。

  • エンドポイントを呼び出す前に、データアプリで API キーを作成していることを確認してください。詳細については、 APIキーを作成するを参照してください。

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

Data Service では、エンドポイントを自動的に生成したり、エンドポイントを手動で作成したり、定義済みのシステム エンドポイントを追加したりできます。

ヒント：

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

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

TiDB Cloudデータ サービスでは、次のようにして 1 つまたは複数のエンドポイントを一度に自動的に生成できます。

  1. プロジェクトのデータサービスページに移動します。

  2. 左側のペインで、対象のデータ アプリを見つけ、アプリ名の右側にある+をクリックして、エンドポイントの自動生成をクリックします。エンドポイント生成のダイアログが表示されます。

  3. ダイアログで、次の操作を行います。

    1. 生成するエンドポイントのターゲット クラスター、データベース、およびテーブルを選択します。

      注記：

      テーブルドロップダウン リストには、システム テーブルと列定義のないテーブルを除き、少なくとも 1 つの列を持つユーザー定義テーブルのみが含まれます。

    2. 生成するエンドポイントに対して、少なくとも 1 つの HTTP 操作 ( GET (Retrieve) 、 POST (Create) 、 PUT (Update)など) を選択します。

      選択した操作ごとに、 TiDB Cloud Data Service は対応するエンドポイントを生成します。バッチ操作 ( POST (Batch Create)など) を選択した場合、生成されたエンドポイントを使用すると、1 回のリクエストで複数の行を操作できます。

      選択したテーブルにベクトルデータ型含まれている場合は、ベクトル検索操作オプションを有効にしてベクトル距離関数を選択し、選択した距離関数に基づいてベクトル距離を自動的に計算するベクトル検索エンドポイントを生成できます。サポートされているベクトル距離関数次のとおりです。

      • VEC_L2_DISTANCE (デフォルト): 2 つのベクトル間の L2 距離 (ユークリッド距離) を計算します。
      • VEC_COSINE_DISTANCE : 2 つのベクトル間のコサイン距離を計算します。
      • VEC_NEGATIVE_INNER_PRODUCT : 2 つのベクトル間の内積の負の値を使用して距離を計算します。
      • VEC_L1_DISTANCE : 2 つのベクトル間の L1 距離 (マンハッタン距離) を計算します。

    3. (オプション) 操作のタイムアウトとタグを構成します。生成されたすべてのエンドポイントは、構成されたプロパティを自動的に継承します。これらのプロパティは、後で必要に応じて変更できます。

    4. (オプション)自動デプロイ エンドポイントオプション (デフォルトでは無効) は、生成されたエンドポイントの直接デプロイを有効にするかどうかを制御します。有効にすると、ドラフト レビュー プロセスがスキップされ、生成されたエンドポイントは、手動によるレビューや承認なしですぐにデプロイされます。

  4. [生成]をクリックします。

    生成されたエンドポイントは、エンドポイント リストの上部に表示されます。

  5. 新しいエンドポイントの生成されたエンドポイント名、SQL ステートメント、プロパティ、およびパラメータを確認します。

    • エンドポイント名: 生成されたエンドポイント名は/<name of the selected table>形式になり、リクエスト メソッド ( GET 、 POST 、 PUTなど) がエンドポイント名の前に表示されます。たとえば、選択したテーブル名がsample_tableで、選択した操作がPOST (Create)の場合、生成されたエンドポイントはPOST /sample_tableとして表示されます。

      • バッチ操作を選択した場合、 TiDB Cloud Data Service は生成されたエンドポイントの名前に/bulk追加します。たとえば、選択したテーブル名が/sample_tableで、選択した操作がPOST (Batch Create)の場合、生成されたエンドポイントはPOST /sample_table/bulkとして表示されます。
      • POST (Vector Similarity Search)を選択した場合、 TiDB Cloud Data Service は生成されたエンドポイントの名前に/vector_search追加します。たとえば、選択したテーブル名が/sample_tableで、選択した操作がPOST (Vector Similarity Search)の場合、生成されたエンドポイントはPOST /sample_table/vector_searchとして表示されます。
      • 同じリクエスト メソッドとエンドポイント名を持つエンドポイントがすでに存在する場合、 TiDB Cloud Data Service は生成されたエンドポイントの名前に_dump_<random letters>追加します。たとえば、 /sample_table_dump_EUKRfl 。

    • SQL ステートメント: TiDB Cloud Data Service は、テーブル列の仕様と選択されたエンドポイント操作に従って、生成されたエンドポイントの SQL ステートメントを自動的に書き込みます。エンドポイント名をクリックすると、ページの中央のセクションにその SQL ステートメントが表示されます。

    • エンドポイント プロパティ: TiDB Cloud Data Service は、選択内容に応じてエンドポイント パス、リクエスト メソッド、タイムアウト、タグを自動的に構成します。プロパティはページの右側のペインにあります。

    • エンドポイント パラメータ: TiDB Cloud Data Service は、生成されたエンドポイントのパラメータを自動的に構成します。パラメータはページの右側のペインにあります。

  6. 生成されたエンドポイントの詳細（名前、SQL ステートメント、プロパティ、パラメータなど）を変更する場合は、 エンドポイントを開発するに記載されている手順を参照してください。

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

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

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

定義済みのシステムエンドポイントを追加する

データ サービスは、データ アプリに直接追加できる定義済みのシステム エンドポイントを含むエンドポイント ライブラリを提供するため、エンドポイント開発の労力が軽減されます。現在、ライブラリには/system/queryエンドポイントのみが含まれており、定義済みのsqlパラメータでステートメントを渡すだけで、任意の SQL ステートメントを実行できます。

定義済みのシステム エンドポイントをデータ アプリに追加するには、次の手順を実行します。

  1. プロジェクトのデータサービスページに移動します。

  2. 左側のペインで、対象のデータ アプリを見つけて、アプリ名の右側にある+をクリックし、エンドポイント ライブラリの管理をクリックします。

    エンドポイント ライブラリ管理のダイアログが表示されます。現在、ダイアログにはクエリの実行(つまり、 /system/queryエンドポイント) のみが提供されています。

  3. データ アプリに/system/queryエンドポイントを追加するには、 [クエリの実行]スイッチを[追加済み]に切り替えます。

    ヒント：

    追加された定義済みエンドポイントをデータ アプリから削除するには、 [クエリの実行]スイッチを[削除済み]に切り替えます。

  4. 「保存」をクリックします。

    注記：

    • [保存] をクリックすると、追加または削除されたエンドポイントがすぐに本番にデプロイされ、追加されたエンドポイントはすぐにアクセス可能になり、削除されたエンドポイントはすぐにアクセスできなくなります。
    • 現在のアプリに同じパスとメソッドを持つ未定義のエンドポイントが既に存在する場合、システム エンドポイントの作成は失敗します。

    追加されたシステム提供のエンドポイントは、エンドポイント リストの上部に表示されます。

  5. 新しいエンドポイントのエンドポイント名、SQL ステートメント、プロパティ、およびパラメータを確認します。

    注記：

    /system/queryエンドポイントは強力で多用途ですが、潜在的に破壊的になる可能性があります。慎重に使用し、予期しない結果を防ぐためにクエリが安全で十分に検討されていることを確認してください。

    • エンドポイント名: エンドポイント名とパスは/system/query 、リクエストメソッドはPOSTです。
    • SQL ステートメント: /system/queryエンドポイントには SQL ステートメントは付属していません。ページの中央のセクションに SQL エディターがあり、SQL エディターで必要な SQL ステートメントを記述できます。3 エンドポイントの SQL エディターで記述され/system/query SQL ステートメントは SQL エディターに保存されるため、次回さらに開発してテストできますが、エンドポイント構成には保存されないことに注意してください。
    • エンドポイント プロパティ: ページの右側のペインの[プロパティ]タブにエンドポイント プロパティがあります。他のカスタム エンドポイントとは異なり、システム エンドポイントではtimeoutとmax rowsプロパティのみをカスタマイズできます。
    • エンドポイント パラメータ: ページの右側のペインの[パラメータ]タブでエンドポイント パラメータを見つけることができます。3 /system/queryエンドポイントのパラメータは自動的に構成され、変更することはできません。

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

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

注記：

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

プロパティを構成する

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

基本的なプロパティ

  • パス: ユーザーがエンドポイントにアクセスするために使用するパス。

    • パスの長さは 64 文字未満にする必要があります。

    • リクエスト メソッドとパスの組み合わせは、データ アプリ内で一意である必要があります。

    • パスには、文字、数字、アンダースコア ( _ )、スラッシュ ( / )、および中括弧で囲まれたパラメータ ( {var}など) のみを使用できます。各パスはスラッシュ ( / ) で始まり、文字、数字、またはアンダースコア ( _ ) で終わる必要があります。たとえば、 /my_endpoint/get_id 。

    • { }で囲まれたパラメータには、文字、数字、アンダースコア（ _ ）のみを使用できます。 { }で囲まれた各パラメータは、文字またはアンダースコア（ _ ）で始まる必要があります。

    注記：

    • パスでは、各パラメータは別々のレベルにある必要があり、プレフィックスやサフィックスはサポートされません。

      有効なパス: /var/{var}と/{var}

      無効なパス: /var{var}と/{var}var

    • 次の例のように、同じメソッドとプレフィックスを持つパスは競合する可能性があります。

      GET /var/{var1}

      GET /var/{var2}

      GET /var/123両方に一致するため、これら 2 つのパスは互いに競合します。

    • パラメータ付きのパスは、パラメータなしのパスよりも優先順位が低くなります。例:

      GET /var/{var1}

      GET /var/123

      GET /var/123優先されるため、これら 2 つのパスは競合しません。

    • パスパラメータはSQLで直接使用できます。詳細については、 パラメータを設定する参照してください。

  • エンドポイント 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ステートメントなどのデータを削除するには、このメソッドを使用します。

  • 説明(オプション): エンドポイントの説明。

高度なプロパティ

  • タイムアウト(ms) : エンドポイントのタイムアウト(ミリ秒)。

  • 最大行数: エンドポイントが操作または返すことができる行の最大数。

  • タグ: エンドポイントのグループを識別するために使用されるタグ。

  • ページネーション: このプロパティは、リクエスト メソッドが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パラメータを含めない場合、デフォルトの動作では、1 ページのMax Rowsプロパティで指定された最大行数が返されます。
    • page_size Max Rowsプロパティ以下である必要があります。それ以外の場合は、エラーが返されます。

  • キャッシュ レスポンス: このプロパティは、リクエスト メソッドがGET場合にのみ使用できます。キャッシュ レスポンスを有効にすると、 TiDB Cloud Data Service は、指定された有効期間 (TTL) 内にGETのリクエストによって返されたレスポンスをキャッシュできます。

  • 有効期間: このプロパティは、キャッシュ レスポンスが有効な場合にのみ使用できます。これを使用して、キャッシュされたレスポンスの有効期間 (TTL) を秒単位で指定できます。TTL 期間中に同じGETつのリクエストを再度行うと、データ サービスはターゲット データベースからデータを再度取得するのではなく、キャッシュされたレスポンスを直接返すため、クエリのパフォーマンスが向上します。

  • バッチ操作: このプロパティは、リクエスト メソッドがPOSTまたはPUTの場合にのみ表示されます。バッチ操作を有効にすると、1 つのリクエストで複数の行を操作できます。たとえば、14 の場合、curl コマンドの--data-rawオプションでオブジェクトのitemsフィールドにデータ オブジェクトの配列を配置することで、1 つのPOSTリクエストでエンドポイントを呼び出す行のデータを挿入できます。

    注記：

    バッチ操作が有効になっているエンドポイントは、リクエスト本文の配列形式とオブジェクト形式の両方をサポートします: [{dataObject1}, {dataObject2}]と{items: [{dataObject1}, {dataObject2}]} 。他のシステムとの互換性を高めるために、オブジェクト形式{items: [{dataObject1}, {dataObject2}]}を使用することをお勧めします。

SQL文を書く

エンドポイントの詳細ページの SQL エディターでは、エンドポイントの SQL ステートメントを記述して実行できます。また、単に--と入力して指示を入力するだけで、AI によって SQL ステートメントが自動的に生成されるようにすることもできます。

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

    注記：

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

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

  2. エンドポイントの種類に応じて、次のいずれかを実行してデータベースを選択します。

    • 定義済みシステム エンドポイント: SQL エディターの上部にあるドロップダウン リストからターゲット データベースを選択します。
    • その他のエンドポイント: SQL エディターでターゲット データベースを指定する SQL ステートメントを記述します。たとえば、 USE database_name; 。

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

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

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

    配列パラメータを定義すると、パラメータは SQL 文で複数のコンマ区切り値に自動的に変換されます。SQL 文が有効であることを確認するには、一部の SQL 文 ( INなど) でパラメータを括弧 ( () ) で囲む必要があります。たとえば、テスト値1,2,3で配列パラメータIDを定義する場合は、 SELECT * FROM table_name WHERE id IN (${ID})使用してデータを照会します。

    注記：

    • パラメータ名では大文字と小文字が区別されます。
    • パラメータはテーブル名または列名として使用できません。

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

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

    • macOS
    • Windows/Linux

    macOSの場合:

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

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

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

    Windows または Linux の場合:

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

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

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

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

    注記：

    返される結果のサイズ制限は 8 MiB です。

パラメータを設定する

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

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

  • パラメータ名: 名前には文字、数字、アンダースコア ( _ ) のみを含めることができ、文字またはアンダースコア ( _ ) で始まる必要があります。 pageとpage_size 、リクエスト結果のページ区切り用に予約されているため、パラメータ名として使用しないでください。

  • 必須: リクエストでパラメータが必須かどうかを指定します。パス パラメータの場合、構成は必須であり、変更できません。その他のパラメータの場合、デフォルトの構成は必須ではありません。

  • タイプ: パラメータのデータ型を指定します。パスパラメータの場合、 STRINGとINTEGERのみがサポートされます。その他のパラメータの場合、 STRING 、 NUMBER 、 INTEGER 、 BOOLEAN 、およびARRAYがサポートされます。

    STRING型のパラメータを使用する場合は、引用符 ( 'または" ) を追加する必要はありません。たとえば、 foo STRING型に有効であり、 "foo"として処理されますが、 "foo" "\"foo\""として処理されます。

  • 列挙値: (オプション) パラメータの有効な値を指定します。パラメータ タイプがSTRING 、 INTEGER 、またはNUMBERの場合にのみ使用できます。

    • このフィールドを空のままにすると、パラメータは指定されたタイプの任意の値になります。
    • 複数の有効な値を指定するには、カンマ ( , ) で区切ります。たとえば、パラメータ タイプをSTRINGに設定し、このフィールドをfoo, barに指定した場合、パラメータ値はfooまたはbarのみになります。

  • ItemType : ARRAY型パラメータの項目タイプを指定します。

  • デフォルト値: パラメータのデフォルト値を指定します。

    • ARRAY型の場合、複数の値をカンマ（ , ）で区切る必要があります。
    • 値がパラメータの型に変換できることを確認してください。変換できない場合、エンドポイントはエラーを返します。
    • パラメータにテスト値を設定しない場合は、エンドポイントをテストするときにデフォルト値が使用されます。

  • 場所: パラメータの場所を示します。このプロパティは変更できません。

    • パスパラメータの場合、このプロパティはPathです。
    • その他のパラメータについては、リクエストメソッドがGETまたはDELETE場合、このプロパティはQueryなります。リクエストメソッドがPOSTまたはPUTの場合、このプロパティはBodyになります。

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

名前を変更

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

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

注記：

定義済みのシステム エンドポイントは名前の変更をサポートしていません。

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

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

ヒント：

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

  1. プロジェクトのデータサービスページに移動します。

  2. 左側のペインで、ターゲット データ アプリの名前をクリックして、そのエンドポイントを表示します。

  3. テストするエンドポイントの名前をクリックして、その詳細を表示します。

  4. (オプション) エンドポイントにパラメータが含まれている場合は、テストの前にテスト値を設定する必要があります。

    1. エンドポイントの詳細ページの右側のペインで、 [Params]タブをクリックします。

    2. テスト値セクションを展開し、パラメータのテスト値を設定します。

      パラメータにテスト値を設定しない場合は、デフォルト値が使用されます。

  5. 右上隅の「テスト」をクリックします。

    ヒント：

    あるいは、 F5 キーを押してエンドポイントをテストすることもできます。

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

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

注記：

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

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

  1. プロジェクトのデータサービスページに移動します。

  2. 左側のペインで、ターゲット データ アプリの名前をクリックして、そのエンドポイントを表示します。

  3. デプロイするエンドポイントを見つけ、エンドポイント名をクリックして詳細を表示し、右上隅の[デプロイ]をクリックします。

  4. データ アプリで下書きの確認が有効になっている場合は、変更内容を確認するためのダイアログが表示されます。確認に基づいて変更内容を破棄するかどうかを選択できます。

  5. デプロイを確認するには、 [デプロイ]をクリックします。エンドポイントが正常にデプロイされると、[エンドポイント**がデプロイされました] という**プロンプトが表示されます。

    エンドポイントの詳細ページの右側のペインで、 [デプロイメント]タブをクリックすると、デプロイされた履歴を表示できます。

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

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

ヒント：

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

前提条件

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

リクエスト

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

  1. プロジェクトのデータサービスページに移動します。

  2. 左側のペインで、ターゲット データ アプリの名前をクリックして、そのエンドポイントを表示します。

  3. 呼び出すエンドポイントを見つけて、 [... ] > [コード例]をクリックします。 [コード例]ダイアログ ボックスが表示されます。

    ヒント：

    または、エンドポイント名をクリックして詳細を表示し、右上隅の[...] > [コード例]をクリックすることもできます。

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

    注記：

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

    • 環境: 必要に応じて、テスト環境またはオンライン環境を選択します。オンライン環境は、エンドポイントをデプロイした後にのみ使用できます。

    • 認証方法:基本認証またはダイジェスト認証を選択します。

      • 基本認証では、 API キーが based64 でエンコードされたテキストとして送信されます。
      • ダイジェスト認証では、 API キーが暗号化された形式で送信されるため、より安全です。

      基本認証と比較して、ダイジェスト認証の curl コードには--digest追加オプションが含まれています。

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

    • 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 '{
  "items": [
    {
      "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 '{
  "items": [
    {
      "age": "${age}",
      "career": "${career}"
    }
  ]
}'

    注記：

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

  5. コード例をアプリケーションに貼り付け、必要に応じて例を編集して実行します。

    • <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オプションは、データ オブジェクトの配列を含むitemsフィールドを持つオブジェクトを受け入れるため、1 つのエンドポイントを使用して複数行のデータを操作できます。
      • バッチ操作が有効になっていないエンドポイントの場合、 --data-rawオプションは 1 つのデータ オブジェクトのみを受け入れます。

    • エンドポイントにパラメータが含まれている場合は、エンドポイントを呼び出すときにパラメータ値を指定します。

応答

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

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

注記：

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

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

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

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

注記：

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

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

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

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