TiDB Cloud
TiDB Self-Managed
Learning Center
お問い合わせ
このページは英語版のページを機械翻訳しています。原文はこちらからご覧ください。

エンドポイントの管理

Data Service (ベータ版) のエンドポイントは、SQL 文を実行するためにカスタマイズできる Web API です。SQL 文のパラメータ（ WHERE句で使用する値など）を指定できます。クライアントがエンドポイントを呼び出し、リクエスト 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)など) を選択しPUT (Update) POST (Create)

      選択した操作ごとに、 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. エンドポイントを開発するの手順に従って新しいエンドポイントを構成します。

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

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

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

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

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

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

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

    ヒント：

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

  4. [保存]をクリックします。

    注記：

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

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

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

    注記：

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

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

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

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

注記：

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

プロパティを構成する

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

基本的なプロパティ

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

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

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

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

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

    注記：

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

      有効なパス: /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リクエストによって返されたレスポンスをキャッシュできます。

  • Time-to-live(s) : このプロパティは、Cache Responseが有効な場合にのみ使用できます。キャッシュされたレスポンスの Time-to-live (TTL) 期間を秒単位で指定できます。TTL 期間中に同じリクエストをGET再度送信した場合、Data Service はターゲットデータベースからデータを再度取得するのではなく、キャッシュされたレスポンスを直接返します。これにより、クエリのパフォーマンスが向上します。

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

    注記：

    バッチ操作が有効なエンドポイントは、リクエストボディとして配列形式とオブジェクト形式の両方をサポートしています[{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文にパラメータを挿入した場合は、右側のペインの「パラメータ」タブでパラメータのテスト値またはデフォルト値が設定されていることを確認してください。設定されていない場合はエラーが返されます。

    • macOS
    • Windows/Linux

    macOSの場合:

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

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

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

    Windows または Linux の場合:

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

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

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

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

    注記：

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

パラメータを設定する

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

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

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

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

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

    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. 名前を変更するエンドポイントを見つけて、 [...] > [名前の変更] をクリックし、エンドポイントの新しい名前を入力します。

注記：

定義済みのシステム エンドポイントでは名前の変更はサポートされません。

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

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

ヒント：

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

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

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

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

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

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

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

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

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

    ヒント：

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

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

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

注記：

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

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

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

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

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

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

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

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

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

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

ヒント：

データアプリをPostmanにインポートしている場合は、Postmanからデータアプリのエンドポイントを呼び出すこともできます。詳細については、 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. 削除を確認するには、 [削除]をクリックします。

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