すべてのプロダクト
Search

このプロダクト

    Dataphin:直接接続によるクエリ API の作成

    ドキュメントセンター

    Dataphin:直接接続によるクエリ API の作成

    最終更新日:Apr 09, 2026

    このトピックでは、SQL を使用して直接接続モードでデータソースからデータを直接クエリする API を作成する方法について説明します。

    制限事項

    • API を呼び出す際、データソースがページネーションをサポートし、操作タイプが LIST の場合、ページングクエリ機能が有効になっているかどうかに関わらず、PageStart および PageSize パラメーターを使用して結果をページ分割できます。

    • 高度な SQL モードで API を作成し、SQL スクリプトで `LIMIT` 句を使用して返される行数を制限する場合、API 呼び出しの OrderByList パラメーターは `LIMIT` 句によって返されたデータのみをソートします。したがって、`LIMIT` は OrderByList よりも優先度が高くなります。たとえば、上位 10 件のレコードを phone_no でソートし、その後 paper_no で再ソートすることができます。

      SELECT * FROM (
  select paper_no,phone_no,vip_no from aaaa order by phone_no limit 1,10
  ) T0 -- これは API 内の SQL スクリプトです。
ORDER BY paper_no ASC -- これは呼び出し時に OrderByList が追加された場合の実行ステートメントです。

    • 基本的な SQL スクリプトで `LIMIT` 句を使用する場合、ページングクエリ機能はサポートされません。

    • 直接接続モードでの API 作成、行レベルの権限、およびページングクエリをサポートするデータソースのリストについては、「データサービスがサポートするデータソース」をご参照ください。

    権限

    プロジェクト管理者および必要なサービス権限を持つ開発者は、API を作成できます。

    非同期呼び出しのワークフロー

    次の図は、非同期データクエリのライフサイクルを示しています。ジョブ ID の取得、ジョブステータスの確認、結果の取得、クエリジョブのクローズというワークフローを示しています。

    • 非同期クエリワークフロー：

      • GetJobStatus：API 呼び出しの実行ステータスを取得します。

      • GetJobResult：リクエスト結果を返します。この操作は、ジョブステータスが「成功」の場合にのみ成功します。クエリ結果は順次のみ取得できます。

      • GetJobExecutionLog：API の実行ログを取得します。

      • CloseJob：リクエストを完了し、データベース接続やキャッシュなど、ジョブが占有していたすべてのリソースを解放します。ジョブステータスが「失敗」の場合でも、リソースを解放するためにこの操作を呼び出してください。

    • 非同期クエリキャンセルワークフロー：

      CancelJob：クエリリクエストをキャンセルします。データベースクエリが実行中の場合は、同期的にキャンセルされます。データベースクエリが開始されていないか、すでに完了している場合は、キャンセルできません。

    ステップ 1: API 作成方法の選択

    1. Dataphin ホームページのトップメニューバーで、[サービス] > [API 開発] を選択します。

    2. 左上のコーナーでプロジェクトを選択します。左側のナビゲーションウィンドウで、[API サービス] をクリックします。[API] ページで、[+ 新規 API] をクリックします。

    3. [新規 API] ダイアログボックスで、[直接接続モード] を選択します。

    ステップ 2: API パラメーターの設定

    1. [新規 API] ページで、API の基本情報とパラメーターを設定します。

      API の基本情報

      パラメーター

      説明

      API 名

      API の名前を入力します。名前は、次の要件を満たす必要があります。

      • 漢字、英字、数字、アンダースコア (_) を含めることができます。

      • 長さは 4～100 文字である必要があります。

      • 漢字または英字で始まる必要があります。

      • グローバルで一意である必要があります。

      操作タイプ

      • GET：サーバーから特定のリソースをリクエストします。

      • LIST：サーバーからリソースのコレクションをリクエストします。

      データ更新頻度

      API によって返されるデータの更新頻度を定義し、コンシューマーにデータの適時性を通知します。サポートされている頻度は、[日次]、[時間単位]、[分単位]、および [カスタム] です。[カスタム] を選択した場合は、最大 128 文字の説明を入力できます。

      API グループ

      API のグループを選択します。新しいグループを作成するには、「サービスグループの作成」をご参照ください。

      説明

      API の簡単な説明を入力します。最大 128 文字まで入力できます。

      プロトコル

      API のプロトコルです。[HTTP] と [HTTPS] がサポートされています。

      • HTTP：HyperText Transfer Protocol (HTTP) は、最も広く使用されているネットワークプロトコルです。

      • HTTPS：ゲートウェイが Alibaba Cloud API Gateway インスタンス (専用または共有) として設定されている場合は、HTTPS を選択できます。呼び出しの失敗を避けるために、独立ドメイン名の SSL 証明書が有効であることを確認してください。SSL 証明書は、[プラットフォーム管理ネットワーク設定] を選択し、[ネットワーク設定] ページに移動して設定できます。

      呼び出しモード

      クライアントとサーバー間の通信モードです。同期呼び出しまたは非同期呼び出しを選択できます。デフォルトは同期呼び出しです。

      • 同期呼び出し：クライアントがリクエストを送信した後、別のリクエストを送信する前にサーバーの応答を待ちます。複雑なクエリの場合、これにより応答時間が長くなり、サーバー接続を占有し、サーバーの負荷が増加する可能性があります。このモードは、高いリアルタイム性能と短い処理時間を必要とするシナリオに適しています。

      • 非同期呼び出し：クライアントがリクエストを送信した後、応答を待たずに他の操作を実行できます。サーバーは処理が完了した後にクライアントに通知します。これにより、バッチでデータをフェッチする際のデータベースクエリ結果の重複を減らすことができます。このモードは、バッチ処理など、高いリアルタイム性能を必要としない長時間実行されるプロセスに適しています。

      実行タイムアウト

      この設定は、呼び出しモードが非同期呼び出しの場合に利用できます。許容される最大の SQL 実行時間を指定します。デフォルト値は 60 秒です。1 から 7,200 (2 時間) までの任意の整数に設定できます。

      タイムアウト

      API 呼び出しの最大持続時間です。同期呼び出しの場合、デフォルト値は 3 秒で、有効値は 3～60 秒です。非同期呼び出しの場合、デフォルト値は 600 秒で、有効値は 3～7,200 秒 (2 時間) です。

      API 呼び出しが指定されたタイムアウトを超えると、エラーが返されます。これにより、例外を特定して処理できます。例外の表示方法の詳細については、「O&M およびモニタリング API の表示と管理」をご参照ください。

      最大応答エントリ数

      この設定は、操作タイプが LIST の場合に利用できます。API が返すことができるエントリの最大数を定義し、最大 10,000 です。1 から 10,000 までの任意の整数に設定できます。

      キャッシュ設定

      この設定は、呼び出しモードが同期呼び出しの場合に利用できます。キャッシュを [有効化] または [無効化] できます。有効化した場合、[キャッシュ期間] を設定する必要があります。デフォルト値は 300 秒です。60 から 1,000,000 秒 (約 277.78 時間) までの任意の整数に設定できます。

      バージョン

      API のバージョンを入力します。各構成にはバージョンがあり、以前のものと比較できます。バージョンはこの API に対して一意である必要があります。バージョンは、次の要件を満たす必要があります。

      • 最大 64 文字までです。

      • 大文字と小文字の英字、数字、アンダースコア (_)、ピリオド (.)、ハイフン (-) を含めることができます。

      応答タイプ

      デフォルトは JSON です。

      SQL を返す

      API 応答に実際に実行された SQL ステートメントを含めるかどうかを制御します。

      • はい (有効)：API 応答には、データベースによって実行された物理 SQL ステートメントが含まれます。

      • いいえ (無効)：API 応答には、元の SQL スクリプトが含まれます。

      API リクエストおよび戻りパラメーターの設定

      [リクエストパラメーター] と [戻りパラメーター] を設定するには、まず入力および出力パラメーターのソーステーブルを特定し、API SQL スクリプトを記述し、パラメーターを解析してから、それらの基本情報を設定する必要があります。

      1. [API パラメーター設定] セクションで、入力および出力パラメーターのソーステーブルを特定し、[参照サンプル] に基づいて API SQL スクリプトを記述します。

        image

        パラメーター

        説明

        モード

        データソースの環境を選択します。[基本] と [開発-本番] がサポートされています。

        • 基本モードでは、すべての開発、送信、および公開操作は本番データベースから読み取ります。

        • 開発-本番モードでは、開発および送信操作は開発データベースから読み取り、公開操作は本番データベースから読み取ります。

        データソース

        タイプに基づいてデータソースを選択します。非同期呼び出しモードをサポートするデータソースのリストについては、「データサービスがサポートするデータソース」をご参照ください。

        説明

        MySQL 5.1.43、5.6、5.7、および 8.0 がサポートされています。

        クエリ高速化

        このパラメーターは、データソースが MaxCompute の場合に利用可能です。この機能を有効にすると、MaxCompute クエリアクセラレーション (MCQA) を使用してクエリを高速化し、実行時間を秒単位に短縮します。各 MCQA テナントにはジョブと同時実行数の上限があるため、高速化が失敗する可能性があります。実行エラーの解決方法については、「クエリアクセラレーション (MCQA)」をご参照ください。

        SQL モード

        [基本 SQL] または [高度な SQL] を選択できます。

        • 基本 SQL：基本的な SQL 構文を使用してクエリロジックを記述します。ロジックの例については、「参照サンプル」をご参照ください。

        • 高度な SQL：MyBatis タグをサポートする SQL 構文を使用してクエリロジックを記述します。現在サポートされているタグには、if、choose、when、otherwise、trim、foreach、および where があります。ロジックの例については、「参照サンプル」をご参照ください。

        結果のページネーション

        この設定は、呼び出しモードが同期呼び出しで、操作タイプが List の場合に利用できます。この機能を有効にする場合は、安定したクエリ結果を確保し、ページネーション結果での重複または欠落したエントリを防ぐために、ソートフィールドを指定する必要があります。この機能を無効にすると、ページネーションパラメーター (PageStart および PageSize) は API デバッグまたはテストページに表示されません。[パラメーターを非表示] チェックボックスをオフにすると表示されます。

        ソート優先度

        • [SQL モード] が [基本 SQL] に設定されている場合、ソート優先度を選択できます。オプションには、SQL スクリプトと OrderByList リクエストパラメーターがあります。

          • SQL スクリプト：SQL スクリプトがソート順を指定している場合、OrderByList リクエストパラメーターは無視されます。

          • OrderByList リクエストパラメーター：API をテストまたはデバッグする際、SQL スクリプトで定義されたソート順と OrderByList 共通リクエストパラメーターの両方が有効になります。OrderByList パラメーターは、API で定義されたソート設定よりも優先度が高くなります。

        • [SQL モード] が [高度な SQL] に設定されている場合、API をテストまたはデバッグする際、SQL スクリプトで定義されたソート順と OrderByList 共通リクエストパラメーターの両方が有効になります。OrderByList パラメーターは、API で定義されたソート設定よりも優先度が高くなります。

        説明

        次のデータソースではソート優先度を設定できません：HBase 0.9.4/1.1.x/2.x、TDengine、および SAP HANA。

        API SQL スクリプト編集

        スクリプトは SQL 編集標準に従う必要があります。詳細については、「API SQL スクリプト編集ガイド」をご参照ください。

        参照サンプル

        以下は、Dataphin が戻りパラメーターとリクエストパラメーターを解析するために使用できる SQL スクリプトテンプレートです。

        • Get/List 基本 SQL サンプル：

          -- 例 1: 条件に基づいて単一のレコードをクエリします。「id」パラメーターが必須でなく、渡されない場合、条件は自動的に無視されます。
SELECT id,name FROM tablename WHERE id = ${id}

-- 例 2: IN 条件でバッチクエリを実行します。id_list パラメーターはカンマ区切りです。
SELECT id,name FROM tablename WHERE id in (${id_list})

-- 例 3: LIKE を使用してあいまい一致を行い、集計関数にセマンティックエイリアスを使用します。
SELECT MAX(a) AS max_a, SUM(a) AS sum_a, MIN(a) AS min_a, COUNT(*) AS count_all FROM tableName WHERE name LIKE ${name_pattern}

-- 例 4: テーブルエイリアスを使用してクエリします。
SELECT  t.name as name FROM tablename t WHERE id=${id_card}

-- 例 5: 式で計算を行い、複数の条件でクエリします。
SELECT (a+b) as sum_ab, (b+c) as sum_bc FROM tablename WHERE id=${id_card} and b>=${num} and c<=${num1}

-- 例 6: CASE ステートメントを使用してグループ化し、カウントします。
SELECT category, SUM(CASE WHEN name LIKE ${name_pattern} THEN 1 ELSE 0 END) AS proj_score FROM table WHERE id=${id} GROUP BY category

        • Get/List 高度な SQL サンプル：

          -- サポートされている MyBatis タグには、if、choose、when、otherwise、trim、foreach、where があります。
-- タグ内の SQL パラメーターは、$ または # 記号で識別できます。以下の例を参照してください。

-- 例 1: <where> と <if> を使用して条件でフィルタリングします。
SELECT id, name, age 
FROM tableName
<where>
  <if test="name != null and name != ''">
    AND age &gt; #{age}
  </if>
  <if test="name == null">
    AND age &lt; #{age}
  </if>
</where>
  
-- 例 2: 相互排他的な条件に <choose> を使用します。
SELECT id, name, age 
FROM tableName
<where>
  <choose>
    <when test="name != null and name != ''">
      AND age &gt; #{age}
    </when>
    <when test="age != null">
      AND age &lt; #{maxAge}
    </when>
    <otherwise>
      AND status = 'active'
    </otherwise>
  </choose>
</where>

-- 例 3: IN クエリに <foreach> を使用します。
SELECT id, name 
FROM tableName
<where>
  id IN
  <foreach item="item" index="index" collection="idList" open="(" separator="," close=")">
    #{item}
  </foreach>
</where>

-- 例 4: カスタムプレフィックスに <trim> を使用します (<where> の代わりとして)。
SELECT id, name, age 
FROM ${tableName}
<trim prefix="WHERE" prefixOverrides="AND | OR ">
  <if test="name != null">
    AND name LIKE #{namePattern}
  </if>
  <if test="minAge != null">
    AND age &gt;= #{minAge}
  </if>
  <if test="status != null">
    AND status = #{status}
  </if>
</trim>

-- 例 5: 動的フィールド (var_cols) でクエリします。
SELECT category,${var_cols_metrics} FROM tableName WHERE id = ${id} GROUP BY category

        フォーマット

        表示用に SQL ステートメントをフォーマットします。基本 SQL のみがサポートされています。

        フィールド参照

        [フィールド参照] パネルには、選択したデータテーブルのすべてのフィールドが表示されます。

        • コピー：テーブル名、すべてのテーブルフィールド、または単一のフィールドをコピーできます。

        • クイック挿入：[クイック挿入] をクリックして、操作タイプに基づいて SQL スクリプトステートメントを挿入します。スクリプトステートメントの詳細については、「API の SQL スクリプトを迅速にインポートする」をご参照ください。

        • 異常なフィールドには警告アイコン image が表示されます。フィールドが属するサービスユニットが本番環境に公開されており、まだ存在することを確認してください。

      2. [パラメーターの解析] をクリックします。Dataphin は API SQL スクリプトから入力および出力パラメーターを自動的に解析し、[リクエストパラメーター] および [戻りパラメーター] セクションに追加します。SQL モードが高度な SQL の場合、[手動設定を維持] を選択できます。SQL スクリプトを変更して再度パラメーターを解析すると、システムはすでに入力したパラメーター情報を保持します。不要なパラメーター情報は手動で削除する必要があります。これは、パラメーターを手動で設定する必要がある複雑な SQL ステートメントに役立ちます。

        説明

        • SQL モードが高度な SQL の場合、var_cols で始まるパラメーターは動的パラメーターです。これらのパラメーターを使用して、SQL ステートメントが返すフィールドを動的に指定できます。サポートされているすべてのフィールドを戻りパラメーターに追加できます。API を呼び出す際、クエリしたいフィールドを動的パラメーターで渡します。フィールドを渡さない場合、戻りパラメーターのこれらのフィールドの値は null になります。

        • SQL モードが基本 SQL で、オプションのパラメーターが提供されない場合、システムは対応するフィルター条件を無視するように SQL を自動的に書き換えます。パラメーター値のタイプが between の場合、パラメーターは必須です。

        • 高度な SQL ステートメントは複雑になる可能性があり、SQL コンパイラによって解析されたパラメーターが完全または正確でない場合があります。SQL ステートメントに基づいてリクエストおよび戻りパラメーターを追加または削除できます。

        パラメーター

        説明

        リクエストパラメーター

        パラメーター名

        必須。パラメーターの公開名です。これは SQL から解析され、変更できません。

        パラメータータイプ

        必須。パラメーターにバインドされたフィールドのデータの型を選択します。サポートされているタイプには、DOUBLE、FLOAT、STRING、DATE(yyyy-MM-dd HH:mm:ss)、BOOLEAN、INT、LONG、SHORT、BYTE、BIGDECIMAL、および BINARY があります。

        ソースフィールドのデータの型がこのリストにない場合は、STRING を選択することを推奨します。

        パラメーター値タイプ

        必須。パラメーターの値タイプを選択します。単一値と複数値がサポートされています。

        • 単一値：このパラメータータイプの場合、入力パラメーターは単一の値として解析され、適用可能な演算子は =、like、>=、<=、>、<、!=、between です。

        • 複数値：入力パラメーターはカンマ (,) で区切られた複数の値に解析され、適用可能な演算子は in です。

        パラメーター処理

        演算子が LIKE の場合にこれを設定します。処理オプションを選択しない場合は、入力値にワイルドカードを手動で含める必要があります。サポートされているオプションには、[あいまい一致] (%keyword%)、[右側一致] (%keyword)、および [左側一致] (keyword%) があります。

        例

        開発者がその使用法を理解するのに役立つ、リクエストまたは戻りパラメーター値の例です。最大長：1,000 文字。

        説明

        リクエストまたは戻りパラメーターの簡単な説明です。最大長：1,000 文字。

        必須

        API を呼び出す際にリクエストパラメーターが必須かどうかを指定します。

        • いいえ：パラメーターがステートメントに含まれていなくても API 呼び出しを実行できます。

        • はい：このパラメーターが含まれていない場合、API 呼び出しは失敗します。

        たとえば、リクエストパラメーターが id (必須) で、戻りパラメーターが name の場合、次のステートメントを実行すると異なる結果が生成されます。

        • 「name」フィールドから対応するデータを返します：select name from tableA where id=5;。

        • SQL ステートメントの実行に失敗します：select name from tableA;。

        操作

        • リクエストパラメーターのパラメータータイプ、パラメーター値タイプ、およびパラメーター処理 (LIKE 演算子のみ) を一括で変更できます。また、パラメーターを一括で削除することもできます (高度な SQL モードのみ)。

        • [高度な SQL] モードが選択されている場合、[リクエストパラメーターの追加] をクリックしてパラメーターを手動で追加できます。

        戻りパラメーター

        パラメーター名

        必須。パラメーターの公開名です。これは SQL から解析され、変更できません。

        パラメータータイプ

        必須。パラメーターにバインドされたフィールドのデータの型を選択します。サポートされているタイプには、DOUBLE、FLOAT、STRING、DATE(yyyy-MM-dd HH:mm:ss)、BOOLEAN、INT、LONG、SHORT、BYTE、BIGDECIMAL、および BINARY があります。

        ソースフィールドのデータの型がこのリストにない場合は、String を選択することを推奨します。

        例

        開発者がその使用法を理解するのに役立つ、リクエストまたは戻りパラメーター値の例です。最大長：1,000 文字。

        説明

        リクエストまたは戻りパラメーターの簡単な説明です。最大長：1,000 文字。

        操作

        • 戻りパラメーターのパラメータータイプを一括で変更し、パラメーターを一括で削除できます (高度な SQL モードのみ)。

        • [高度な SQL] モードが選択されている場合、[戻りパラメーターの追加] ボタンをクリックしてパラメーターを手動で追加できます。

      3. [SQL トライアル実行] をクリックします。[リクエストパラメーター入力] ダイアログボックスで、[パラメータータイプ]、[パラメーター値タイプ]、[パラメーター処理] を選択し、[トライアル実行入力値] を入力して、[確認] をクリックします。

        • 実行ログ：トライアル実行中に実行された実際の SQL ステートメントを表示します。

        • トライアル実行入力値：バインドされたフィールドの値を指定する必要があります。フィールド値は [データプレビュー] パネルで確認できます。

        • 一括操作：リクエストパラメーターのパラメータータイプ、パラメーター値タイプ、およびパラメーター処理 (LIKE 演算子のみ) を一括で変更できます。また、パラメーターを一括で削除することもできます (高度な SQL モードのみ)。

      4. [パラメーターサンプル値の入力] をクリックします。システムは、最後に成功したトライアル実行のサンプル値でリクエストおよび戻りパラメーターを入力します。サンプル値がすでに存在する場合、上書きされません。値を変更できます。

      5. このオプションは、SQL モードが [高度な SQL] で、成功したトライアル実行が完了している場合にのみ利用できます。[戻りパラメーターの入力]/[トライアル実行結果からインポート] をクリックします。[パラメーターの入力] ダイアログボックスで、追加方法と同名のパラメーターの処理方法を設定します。

        • 追加方法：インポートされたパラメーターを追加する戦略です。新しいパラメーターを追加するか、既存のすべてのパラメーターを置き換えるかを選択できます。

          • 新しいパラメーターを追加：戻りパラメーターリストに既存のパラメーターを保持し、トライアル実行結果から解析された新しい一意の名前のパラメーターを追加します。

          • 既存のすべてのパラメーターを置換：戻りパラメーターリストのすべてのパラメーターを、トライアル実行結果から解析されたパラメーターに置き換えます。

        • 同名パラメーターの処理：この設定は、新しいパラメーターを追加することを選択した場合に利用できます。重複するパラメーター名の処理戦略を定義します。

          • 変更しない：元のパラメーター情報を変更せずに保持します。

          • 置換：トライアル実行結果のパラメーターが既存のパラメーターと同じ名前を持つ場合、既存のパラメーターのタイプとサンプル値はトライアル実行の情報で更新されます。トライアル実行結果の値が空の場合、置換は行われません。

        [リクエストパラメーターのサンプル値を同期的に入力] を選択すると、リクエストパラメーターリストのサンプル値がパラメーター入力設定に従って置き換えられます。

      6. このオプションは、SQL モードが [基本 SQL] の場合にのみ利用できます。[パラメーターの解析] をクリックすると、システムはデータソーステーブルに関連付けられた行レベルの権限情報を自動的に解析します。これには、行レベルの権限名、説明、制御フィールド、データソース環境、関連テーブル、および関連フィールドが含まれます。また、次の操作も実行できます。

        • [有効化] または [無効化] 行レベルの権限：行レベルの権限がアクティブであるかどうか、および API の表示、比較、デバッグ、またはテスト時に行レベルの権限リストが表示されるかどうかを制御します。

        • [行レベルの権限の作成]：この操作には、行レベルの権限を作成する権限が必要です。これをクリックすると、[管理センター] > [権限管理] ページに移動し、行レベルの権限を作成します。

          説明

          • この機能を使用するには、行レベルの権限の付加価値サービスを購入する必要があります。

          • 返されるデータは、ユーザーの権限によって異なります。

          • モードが [基本] の場合、本番環境に関連付けられたデータソーステーブルの行レベルの権限が表示されます。モードが [開発-本番] の場合、開発環境と本番環境の両方のテーブルの行レベルの権限が表示されます。

    2. [送信] をクリックします。システムは、API によって参照されるフィールドが指定されたデータソースに存在することを検証します。検証が成功すると、API が作成されます。

    次のステップ

    • API を作成した後、それをテストし、アプリケーションが呼び出せるようにデータサービスマーケットプレイスに公開する必要があります。詳細については、「API のテストと公開」をご参照ください。

    • API の削除、バージョン管理、所有権の転送などの操作を実行するには、「API の表示と管理」をご参照ください。