DataWorks:データソースからの API の作成 (API Gateway)

モードの比較

モードの選択

• ウィザードモードの使用：等価、あいまい一致、範囲フィルタリングなど、単一のデータテーブルに対する単純なクエリに使用します。このモードは、API 設定のための視覚的なノーコードインターフェイスを提供します。

• スクリプトモードの使用：複数テーブルの JOIN、ネストされたサブクエリ、集約、またはオプションパラメーターを持つ動的条件など、高度なクエリに使用します。

1. データソースとテーブルの選択

API をダブルクリックして編集ページを開きます。Table エリアで、Data Source Type、Data Source Name、Data Source Environment などのパラメーターを設定します。設定パラメーターはデータソースタイプによって異なります。具体的なパラメーターについては UI をご参照ください。

2. クエリロジックの定義

クエリロジックは、ウィザードモードとスクリプトモードで定義方法が異なります。

3. リクエストパラメーターの設定

API 編集ページの右側のペインで Request Parameters をクリックして、パラメーターを設定します。

4. レスポンスパラメーターとページネーションの設定

API 編集ページの右側のペインで Response Parameters をクリックして、パラメーター名、パラメータータイプ、サンプル値、説明を設定します。アドバンスト SQL モードでは、SQL スクリプトに基づいて、すべてのレスポンスパラメーターを手動で追加する必要があります。

Advanced Settings エリアで、Pagination for Return Results を有効にするかどうかを指定します：

• 無効：API はデフォルトで最大 2,000 レコードを返します。

• 有効：Resource Group for DataService Studio ページで、リソースグループタイプに基づいて 1 ページあたりの最大レコード数を設定できます。

ページネーションが有効な場合、システムは自動的に以下の共通パラメーターを追加します：

• 共通リクエストパラメーター：returnTotalNum (レコード総数を返すかどうか)、pageNum (現在のページ番号)、pageSize (1 ページあたりのレコード数)。

• 共通レスポンスパラメーター：pageNum、pageSize、totalNum (レコード総数)。

5. フィルターの設定 (オプション)

リクエストパラメーターを前処理したり、クエリ結果を後処理したりするには、右側のナビゲーションペインで Filter をクリックします。Use Pre-filter または Use Post-filter チェックボックスを選択します。次に、Function Type を選択し、関数を選択します。複数の関数を追加でき、追加された順に実行されます。フィルターの作成と使用方法の詳細については、「Aviator 関数の作成」および「Python 関数の作成」をご参照ください。

6. サービスリソースグループの設定

右側のナビゲーションペインで、Resource Group for DataService Studio をクリックして、API のリソースグループタイプを設定します。

Exclusive Resource Group for DataService Studio または Shared Resource Group for DataService Studio を使用できます。専用サービスリソースグループの場合、名前でターゲットリソースグループを選択できます。パブリックサービスリソースグループは、DataWorks によって自動的に維持されます。

環境構成 エリアでは、メモリ、タイムアウト、Maximum Number of Data Records for a Single Request を設定できます：

• タイムアウト：共有 API Gateway インスタンスの場合は 30,000 ms、専用 API Gateway インスタンスを使用する専用サービスリソースグループの場合は 90,000 ms を超えることはできません。

  説明

  API の応答時間は SQL の実行時間に依存します。タイムアウト値を十分に高く設定して、タイムアウトによるリクエストの失敗を防ぎます。

• 1 ページあたりの最大レコード数：パブリックサービスリソースグループの場合は最大 2,000、専用サービスリソースグループの場合は最大 10,000 です。API が返すことができる結果の総数に制限はありません。

例 1：ソート順の制御

var の値によってソート順が決まります。

select col01,col02
from table_name
<choose>
    <when test='var == 1'>
    order by col01
    </when>
    <when test='var == 2'>
    order by col02
    </when>
    <when test='var == 3'>
    order by col01,col02
    </when>
    <when test='var == 4'>
    order by col02,col01
    </when>
</choose>

リクエストパラメーター：var (タイプ：INT、必須)。レスポンスパラメーター：col01、col02。

例 2：異なるテーブルのクエリ

var の値によってクエリするテーブルが決まります。

select col01
from
<choose>
 <when test='var == 1'>
 table_name01
 </when>
 <when test='var == 2'>
 table_name02
 </when>
</choose>

例 3：動的な WHERE 句

クエリ条件は、list コレクションが空かどうかに基づいて動的に生成されます。list が null でない場合、area フィールドの値を含むクエリ条件が生成されます。

SELECT area_id, area, amount
FROM table_name
<where>
	<if test='list!=null'>
	area in
		<foreach collection="list" open="(" close=")" separator="," item="area">
		#{area}
		</foreach>
	</if>
</where>

リクエストパラメーター：list (タイプ：STRING_LIST、必須、例：Beijing,Hangzhou)。レスポンスパラメーター：area_id、area、amount。

ウィザードモードでのオプションパラメーター

ウィザードモードでオプションのパラメーターを実装するのは簡単です。Select Parameters エリアで uid と gender をリクエストパラメーターとして選択した後、右側の Request Parameters パネルに移動し、gender パラメーターの Required チェックボックスの選択を解除します。

• 選択済み：API を呼び出す際にパラメーターの値を指定する必要があります。そうしないと、パラメーター検証例外がスローされます。

• クリア：パラメーターに値を渡すかどうかを選択できます。値を渡さない場合、パラメーターはクエリ条件として含まれません。

呼び出し例：

• シナリオ 1：uid と gender の両方に値が渡されます。システムは次のクエリを実行します：

  SELECT uid, gender, age_range, zodiac
  FROM ods_user_info_d
  WHERE uid = 0016359810821
  AND gender = 'Female';

• シナリオ 2：uid には値が渡されますが、gender には値が渡されません。システムは次のクエリを実行します：

  SELECT uid, gender, age_range, zodiac
  FROM ods_user_info_d
  WHERE uid = 0016359810821;

スクリプトモードでのオプションパラメーター

アドバンスト SQL モードでは、MyBatis の <if> タグを使用して条件付きロジックを実装します：

SELECT uid, gender, age_range, zodiac
FROM ods_user_info_d
<where>
    <if test='gender!=null'>
    gender = ${gender}
    </if>
    and uid = ${uid}
</where>

• <where> タグは、WHERE キーワードを自動的に処理し、冗長な AND または OR プレフィックスを削除します。

• <if test='gender!=null'> タグは、gender パラメーターに null でない値を渡した場合にのみ、条件をクエリに追加します。

• SQL ステートメントを設定した後、右側のRequest Parameters パネルで uid パラメーターと gender パラメーターを手動で追加し、gender パラメーターのRequired チェックボックスの選択を解除します。

動作はウィザードモードと同じです：値が渡されると gender 条件が適用され、省略されると無視されます。

オプションパラメーターの設定