すべてのプロダクト
Search

このプロダクト

    Dataphin:直接接続モードでのクエリ API の作成

    ドキュメントセンター

    Dataphin:直接接続モードでのクエリ API の作成

    最終更新日:Jan 14, 2026

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

    制限事項

    • 行レベルの権限機能は、購入後に利用可能になります。

    • API を呼び出す際、データソースがページングをサポートし、操作タイプが List の場合、ページングクエリ機能が無効であっても、ページングには PageStart および PageSize パラメーターを使用する必要があります。

    • 高度な SQL モードで API を作成する際、SQL スクリプトで LIMIT を使用してクエリ結果の数を制限すると、API 呼び出しの OrderByList パラメーターは LIMIT によって返されたデータのみをソートします。これは、LIMIT が OrderByList よりも優先度が高いことを意味します。例：phone_no で上位 10 件のレコードをソートし、その結果を 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 モードで API を作成する際、SQL スクリプトで LIMIT を使用してクエリ結果の数を制限すると、ページングクエリはサポートされません。

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

    権限

    プロジェクト管理者と開発者は API を作成できます。

    非同期呼び出しフロー

    以下のフローチャートは、非同期データクエリのライフサイクルを示しています。このライフサイクルには、ジョブ ID、ステータス、結果の取得、およびクエリジョブのクローズが含まれます。

    • 非同期クエリフロー：

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

      • GetJobResult：リクエストの結果を返します。この操作は、ジョブのステータスが Success の場合にのみ正常に呼び出すことができます。それ以外の場合、呼び出しは失敗します。クエリ結果はシーケンシャルにのみ取得できます。

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

      • CloseJob：リクエストを完了し、データベース接続やキャッシュなど、ジョブが占有しているすべてのリソースを解放します。ジョブのステータスが Failed であっても、リソースを解放するためにこの操作を呼び出す必要があります。

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

      CancelJob：クエリリクエストをキャンセルします。データベースのクエリリクエストが実行中の場合、それもキャンセルされます。この操作は、まだ開始されていない、またはすでに完了したクエリをキャンセルすることはできません。

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

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

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

    3. API の作成 ダイアログボックスで、直接接続 - SQL モード を選択します。

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

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

      API の基本情報

      パラメーター

      説明

      API 名

      API の名前を入力します。名前は次のルールに従う必要があります：

      • 漢字、英字、数字、アンダースコア (_) を使用できます。

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

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

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

      操作タイプ

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

      • LIST：サーバーからリソースの一部をリクエストします。

      データ更新頻度

      API が返すデータの更新頻度を定義します。これにより、呼び出し元はデータの適時性を理解できます。サポートされている頻度は、日次、時間単位、分単位、および カスタム です。カスタムを選択した場合は、最大 128 文字で入力します。

      API グループ

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

      説明

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

      プロトコル

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

      • HTTP：広く使用されているネットワークプロトコルです。

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

      呼び出しモード

      クライアントとサーバー間の通信で、データの取得や処理に使用されます。同期呼び出しまたは非同期呼び出しを選択します。デフォルトは同期呼び出しです。

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

      • 非同期呼び出し：クライアントがリクエストを送信した後、サーバーの応答を待たずに他のリクエストを送信し続けることができます。サーバーは処理が完了した後にクライアントに通知します。バッチでデータを取得する場合、これによりデータベースのクエリ結果の重複を減らすことができます。データ取得には DataService Studio API を使用します。このモードは、バッチ処理など、処理時間が長く、リアルタイム要件が低いシナリオに適しています。

      実行タイムアウト

      このパラメーターは、呼び出しモードが非同期呼び出しの場合に利用できます。SQL の実行時間を監視するために使用されます。デフォルトは 60 秒です。1 から 7200 (2 時間) までの整数に設定します。

      タイムアウト

      API 呼び出しの最大時間を監視するために使用されます。同期呼び出しの場合、デフォルトは 3 秒です。3 から 60 までの整数に設定します。非同期呼び出しの場合、デフォルトは 600 秒です。3 から 7200 (2 時間) までの整数に設定します。

      API 呼び出しが指定されたタイムアウト時間を超えると、エラーが報告されます。これにより、API 呼び出しの例外を迅速に特定し、処理することができます。例外の表示方法の詳細については、「サービス監視 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 のリクエストパラメーターとレスポンスパラメーターを設定する際には、まず入力パラメーターと出力パラメーターのソーステーブルを決定する必要があります。その後、API の SQL 文を記述し、リクエストパラメーターとレスポンスパラメーターを解析し、それらの基本情報を設定します。

      1. API パラメーター設定セクションで、入力パラメーターと出力パラメーターのソーステーブルを決定します。参考例に基づいて API SQL スクリプトを記述します。

        image

        パラメーター

        説明

        モード

        データソース環境を選択します。[Basic] および [Dev-Prod] に対応しています。

        • 基本モードでは、開発、送信、公開中に本番データベースが読み取られます。

        • 開発-本番モードでは、開発と送信中に開発データベースが読み取られ、公開後に本番データベースが読み取られます。

        データソース

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

        説明

        MySQL はバージョン 5.1.43、5.6/5.7、および 8 をサポートしています。

        クエリアクセラレーション

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

        SQL モード

        基本 SQL または 高度な SQL を選択します。

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

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

        結果のページング

        呼び出しモードが同期呼び出しで、操作タイプが 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 スクリプトエディター

        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: <foreach> を使用した IN クエリ。
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 スクリプト用の SQL を迅速にインポート」をご参照ください。

        • 異常なフィールドはアラート image アイコンでマークされます。フィールドのサービスユニットが本番環境に公開されているか、またはサービスユニットが存在するかどうかを確認してください。

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

        説明

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

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

        • 高度な 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 呼び出しの SQL 文を実行できます。

        • はい を選択：このパラメーターが含まれていない場合、API 呼び出しの SQL 文を実行できません。

        たとえば、リクエストパラメーターが `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 テスト実行中に実際に実行された SQL 文を表示します。

        • テスト入力値：バインドされたフィールドの値を入力します。データプレビュー パネルでフィールドの値を確認できます。

        • バッチ操作：リクエストパラメーターに対してバッチ操作を実行できます。これらの操作には、パラメータータイプ、パラメーター値タイプ、パラメーター処理 (オペレーターが LIKE の場合のみ) の変更、またはパラメーターの削除 (高度な SQL モードのみ) が含まれます。

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

      5. このステップは、SQL モードが高度な SQLで、テスト実行レコードが存在する場合にのみ利用できます。レスポンスパラメーターの入力 / テスト実行結果からインポート をクリックします。パラメーターの入力 ダイアログボックスで、パラメーターの追加方法と重複するパラメーター名の処理方法を設定します。

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

          • 新しいパラメーターを追加：レスポンスパラメーターリスト内の既存のパラメーターを保持し、現在のテスト実行から解析されたパラメーターを追加します。新しいパラメーターは名前の一意性に基づいて追加されます。

          • 既存のすべてのパラメーターを置換：レスポンスパラメーターリスト内の既存のすべてのパラメーターを、テスト実行から解析されたパラメーターで置き換えます。

        • 重複パラメーターの処理：このオプションは、追加方法として [新しいパラメーターを追加] を選択した場合にのみ利用できます。これは、重複するパラメーター名の処理ポリシーです。既存のパラメーターを保持するか、置き換えるかを選択できます。

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

          • 置換：テスト実行結果のパラメーター名がリスト内のパラメーター名と同じ場合、既存のパラメーター情報は、現在のテスト実行から解析されたパラメータータイプとサンプル値で更新されます。テスト実行結果の値が空の場合、既存のパラメーターは置き換えられません。

        リクエストパラメーターのサンプル値を同期 を選択した場合、リクエストパラメーターリストのサンプル値は、入力パラメーターの設定に基づいて置き換えられます。

      6. 関連付けられた行レベルの権限は、SQL モードが基本 SQLの場合にのみ表示されます。パラメーターの解析 ボタンをクリックします。システムは、データソーステーブルに関連付けられた行レベルの権限情報を自動的に解析します。この情報には、行レベルの権限名、説明、コントロールフィールド、データソース環境、関連テーブル、および外部キーフィールドが含まれます。また、次の操作も実行できます：

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

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

          説明

          • この API によって返されるデータ範囲は、行レベルの権限によって制御されます。異なる行レベルの権限は、異なるデータ結果をもたらします。

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

    2. 送信 をクリックします。システムは、API によって参照されるフィールドがデータソースに存在するかどうかを確認します。チェックが成功すると、API が作成されます。

    次のステップ

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

    • API の削除、バージョンの管理、または所有権の移管については、「API の表示と管理」をご参照ください。