DataWorks:スクリプトモードでのAPIの作成

1. テーブルの選択

API をダブルクリックして編集ページを開きます。Table セクションで、Data Source Type、Data Source Name、Data Source Environment などのパラメーターを設定します。

必要なパラメーターは、データソースのタイプによって異なります。詳細については、UI をご参照ください。

2. SQL クエリの記述

Edit Query SQL セクションで、SQL クエリ ステートメントを入力します。

• Basic SQL モードを選択した場合、基本的な SQL 構文のみがサポートされます。

  SELECT
  name,
  addr AS address,
  SUM(num) as total_num
  FROM
  table_name
  WHERE
  user_id =${uid}

  説明

  SELECT 句のフィールドは API のレスポンスパラメーターを定義します。WHERE 句のパラメーターは API のリクエストパラメーターを定義します。${} 形式でリクエストパラメーターを識別します。

  SQL ステートメントを記述する際は、次のルールに従ってください：

  • 同じデータソース内での単一テーブルクエリ、複数テーブル結合クエリ、およびネストされたクエリがサポートされています。

  • 以下はサポートされていません：

    • 複数の SQL ステートメント。

    • コメント。

    • INSERT、UPDATE、DELETE などの非 SELECT ステートメント。

    • SELECT * ステートメント。クエリする列を明示的に指定する必要があります。

    • ${param} 変数を引用符で囲まないでください。たとえば、'${id}' や 'abc${xyz}123' はサポートされていません。これを行うには、concat('abc', ${xyz}, '123') 関数を使用します。

    • オプションのパラメーター。

  • SELECT 句の列名がテーブル名 (例: t.name) で修飾されている場合、レスポンスパラメーターにエイリアス (例: t.name as name) を指定する必要があります。

  • 集計関数 (min、max、sum、count など) を使用する場合、レスポンスパラメーターのエイリアスを指定する必要があります。例： sum(num) as total_num。

  • SQL ステートメント内の ${param} 変数は、文字列内のものも含め、リクエストパラメーターに置き換えられます。${param} 変数の前にバックスラッシュ (\) がある場合、それはリテラル文字列として扱われます。

• Advanced SQL モードを選択した場合、MyBatis タグがサポートされます。

  SELECT id, name, create_name
  FROM t_parameter
  <where>
  <if test="'list!=null'">
      id in (
          <foreach collection="list" open="(" close=")" separator="," item="id_num">
              ${id_num}
          </foreach>
      )
  </if>
  </where>

  高度な SQL でサポートされている MyBatis タグは、if、choose、when、otherwise、trim、foreach、および where です。これらのタグを使用して、null 値のチェック、複数値の走査、動的テーブルクエリ、動的ソート、集計などの複雑なクエリロジックを実装できます。一般的なシナリオのコードサンプルについては、「高度な SQL (MyBatis 構文) の例」をご参照ください。

  MyBatis タグで特殊文字を使用する場合は、これらの文字をエスケープする必要があります。次の表に、一般的なエスケープ文字を示します。

  特殊文字	エスケープ文字	説明
  >	>	より大きい
  >=	>=	以上
  <	&lt;	より小さい
  <=	&lt;=	以下
  &	&amp;	AND
  '	&apos;	単一引用符
  "	&quot;	二重引用符

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

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

Advanced SQL モードを使用する場合、SQL スクリプトからすべてのリクエストパラメーターを手動でリストに追加します。これにより、API ドキュメントに、必要なパラメーターが正確に反映されます。

4. レスポンスパラメーターの設定

API 編集ページの右側のナビゲーションペインで、Response Parameters をクリックし、パラメーターを設定します。

1. レスポンスパラメーターを設定します。

   Advanced SQL モードを使用する場合、SQL スクリプトからすべてのレスポンスパラメーターを手動でリストに追加します。これにより、API ドキュメントに、返されるデータが正確に反映されます。

   パラメーター	説明
   [Parameter Name]	レスポンスパラメーターの名前。名前の長さは最大 64 文字で、英字で始まり、英字、数字、アンダースコア (_)、ハイフン (-) を含めることができます。
   [Parameter Type]	サポートされているデータ型は、STRING、INT、LONG、FLOAT、[Double]、[Boolean]です。
   [Sample Value]	レスポンスパラメーターのサンプル値。
   [Description]	レスポンスパラメーターの簡単な説明。

2. Advanced Settings セクションで、Pagination for Return Results を有効にするかどうかを指定します。

   • Pagination for Return Results を有効にしない場合、API はデフォルトで最大 2,000 レコードを返します。

   • API が 2,000 件以上の結果を返す可能性がある場合は、Pagination for Return Results を有効にします。有効にした後、右側のナビゲーションペインの Resource Group for DataService Studio ページに移動して、リソースグループのタイプに基づいて 1 ページあたりの最大エントリ数を設定できます。

   説明

   API 編集ページの Response Parameters タブで Pagination for Return Results が有効になっており、Edit Query SQL セクションで LIMIT 句を含む SQL ステートメントを使用する場合、LIMIT 句は無視され、返される結果の数は Pagination for Return Results の設定によって決まります。

   ページネーションを有効にすると、次の共通パラメーターが自動的に追加されます：

   • 共通リクエストパラメーター：

     • returnTotalNum: 1 回のリクエストでデータレコードの総数を返すかどうかを指定します。

     • pageNum: 現在のページ番号。

     • pageSize: 1 ページあたりのエントリ数。

   • 共通レスポンスパラメーター：

     • pageNum: 現在のページ番号。

     • pageSize: 1 ページあたりのエントリ数。

     • totalNum: レコードの総数。

   説明

   API にリクエストパラメーターがない場合もありますが、その場合は Pagination for Return Results を有効にする必要があります。

5. フィルターの設定

リクエストパラメーターを前処理したり、クエリ結果を後処理したりする必要がある場合は、API 編集ページの右側のナビゲーションペインで Filter をクリックします。必要に応じて Use Pre-filter または Use Post-filter を選択します。Function Type を選択し、プレフィルターまたはポストフィルターのドロップダウンリストから 1 つ以上の関数を選択します。関数は追加された順に実行されます。設定が完了したら、Preview Responses Returned by API Operation をクリックして、結果が期待どおりかどうかを確認できます。フィルターの作成と使用方法の詳細については、「Aviator 関数の作成」および「Python 関数の作成」をご参照ください。

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

1. API 編集ページの右側のナビゲーションペインで、Resource Group for DataService Studio をクリックします。リソースグループタイプ セクションで、API を呼び出すときに使用するリソースグループのタイプを設定します。

   Exclusive Resource Group for DataService Studio または Shared Resource Group for DataService Studio を選択できます。Exclusive Resource Group for DataService Studio の場合、リストから対象のリソースグループ名を選択できます。Shared Resource Group for DataService Studio は DataWorks によって自動的に管理され、名前で選択することはできません。

   説明

   • 対象のリソースグループ名がリストにない場合は、[リソースグループ] ページに移動し、リソースグループを見つけて、Operation 列の ホームスペースの変更 をクリックします。

   • 対象のリソースグループがリストにあるが選択できない場合は、[リソースグループ] ページに移動し、リソースグループを見つけて、Operation 列で > クォータ管理 をクリックします。データサービス 用に、現在占有されているCU (従量課金リソースグループの場合) または CU保証 (サブスクリプションリソースグループの場合) を手動で設定します。

2. 環境構成 エリアで、メモリ、タイムアウト、および Maximum Number of Data Records for a Single Request を設定できます。

   • 最大タイムアウトは、選択した DataWorks サービスリソースグループと API Gateway インスタンスのタイプによって異なります：

     • 共有 API Gateway インスタンス：DataService Studio の共有リソースグループの場合は最大 30,000 ms、DataService Studio 専用リソースグループの場合は最大 30,000 ms。

     • 専用 API Gateway インスタンス：DataService Studio の共有リソースグループの場合は最大 30,000 ms、DataService Studio 専用リソースグループの場合は最大 90,000 ms。

     説明

     API のレスポンスタイムは、その SQL 実行時間に依存します。リクエストの失敗を防ぐために、API の タイムアウト を予想される実行時間より大きい値に設定してください。

   • 1 ページあたりの最大エントリ数は、選択したサービスリソースグループのタイプによって異なります：

     • DataService Studio の共有リソースグループを選択した場合、ページネーションが有効な場合の 1 ページあたりの最大データレコード数は 2,000 です。

     • DataService Studio 専用リソースグループを選択した場合、ページネーションが有効な場合の 1 ページあたりの最大データレコード数は 10,000 です。

     説明

     API が返すことができる結果の総数に上限はありません。

7. 保存と送信

ツールバーの 保存アイコンをクリックします。API を保存すると、選択したリソースグループがテストに使用されます。