DataService Studio では、コードレス UI またはコードエディタを使用して API を作成できます。コードエディタを使用して API を作成する場合、API の SQL 文をカスタマイズできます。コードエディタでは、テーブル結合クエリ、複雑なクエリ、および集計関数を使用して、パーソナライズされたクエリ要件を満たすことができます。このトピックでは、コードエディタを使用して API を作成する方法について説明します。
前提条件
[データソース] ページでデータソースが構成されていること。詳細については、「データソースを追加する」をご参照ください。
DataService Studio 用にリソースグループが作成されていること。本番環境では、サーバーレスリソースグループを使用することをお勧めします。詳細については、「準備」をご参照ください。
DataService Studio ページに移動する
DataWorks コンソール にログオンします。上部のナビゲーションバーで、目的のリージョンを選択します。左側のナビゲーションウィンドウで、 を選択します。表示されたページで、ドロップダウンリストから目的のワークスペースを選択し、[dataservice Studio に移動] をクリックします。
API を生成する
[サービス開発] ウィンドウで、
アイコンにポインタを移動し、 を選択します。ビジネスプロセスを選択し、[API] を右クリックして、 を選択することもできます。
[API を生成] ダイアログボックスで、パラメータを構成します。
パラメータ
説明
[API モード]
API を作成するために使用されるモード。有効な値: [ウィザードモード] および [スクリプトモード]。この例では、[スクリプトモード] を選択します。
[SQL モード]
SQL モード。有効な値:
[基本 SQL]: 基本的な SQL 文を使用してクエリロジックを実装します。このモードは、以前のバージョンと同じ SQL 機能を提供します。
[高度な SQL]: MyBatis タグ付きの SQL 文を使用してクエリロジックを実装します。このモードでは、if、choose、when、otherwise、trim、foreach、where などのタグタイプがサポートされています。
[API 名]
API の名前。名前は 4 ～ 50 文字で、文字、数字、アンダースコア(_) を使用できます。名前は文字で始める必要があります。
[API パス]
API のパス (例: /user)。
[プロトコル]
API で使用されるプロトコル。有効な値: [HTTP] および [HTTPS]。
HTTPS を使用して API を呼び出す場合は、API が API Gateway に公開された後、API Gateway コンソールで、API が属する API グループに独立ドメイン名をバインドする必要があります。また、API Gateway コンソールで SSL 証明書をアップロードする必要があります。詳細については、「API 操作で HTTPS を有効にする」をご参照ください。
[リクエストメソッド]
リクエストメソッド。有効な値: [GET] および [POST]。
説明[GET] を [リクエストメソッド] パラメーターに選択した場合、[位置] パラメーターには [QUERY] のみを選択できます。[POST] をリクエストメソッドパラメーターに選択した場合、[位置] パラメーターには [QUERY] または [BODY] を選択できます。
[レスポンスタイプ]
API から返されるデータの形式。値を [JSON] に設定します。
[表示範囲]
API が表示されるユーザーの範囲。有効な値:
[ワークスペース]: API は現在のワークスペースのすべてのメンバーに表示されます。
[プライベート]: API は所有者のみに表示され、API の権限を他のメンバーに付与することはできません。
説明このパラメータを [プライベート] に設定すると、ワークスペース内の他のメンバーは API リストで API を表示できません。
[ラベル]
[ラベル] ドロップダウンリストからタグを選択します。詳細については、「API タグを作成および管理する」をご参照ください。
説明タグは最大 20 文字で、文字、数字、アンダースコア(_) を使用できます。 1 つの API に最大 5 つのタグを追加できます。
[説明]
API の説明。説明は最大 2,000 文字です。
[保存先フォルダ]
API を保存するフォルダ。
[OK] をクリックします。
API を構成する
1. テーブルを選択する
API リストで API をダブルクリックします。表示されたタブで、[データソースタイプ]、[データソース名]、[データソース環境] パラメータを構成します。
構成する必要のあるパラメータは、選択したデータソースタイプによって異なります。コンソールの値が優先されます。
最初に [データソース] ページでデータソースを追加する必要があります。 [テーブル名] フィールドにテーブル名を入力して、使用するテーブルを検索できます。
最初にデータソースを選択する必要があります。テーブル結合クエリは、同じデータソース内でのみサポートされます。
標準モードのワークスペースの場合、[データソース環境] パラメータに [本番] または [環境] を選択できます。詳細については、「基本モードのワークスペースと標準モードのワークスペースの違い」をご参照ください。
API の MaxCompute テーブルを選択する場合、高速化のために、[高速化メソッド] パラメータに [高速化サービス] または [MCQA] を選択できます。高速化サービスは DataWorks が提供する高速化メソッドであり、MCQA は MaxCompute が提供する高速化メソッドです。 [高速化サービス] を選択する場合は、高速化項目が作成されていることを確認する必要があります。詳細については、「API ベースのデータクエリの高速化ソリューション」をご参照ください。
2. データクエリ用の SQL 文を作成する
[クエリ SQL を編集] セクションで、データクエリ用の SQL 文を作成します。
[SQL モード] パラメータを [基本 SQL] に設定した場合、基本的な SQL 文のみを作成できます。
説明SELECT 文は、API が返すパラメータを指定します。 WHERE 句は、API のリクエストパラメータを指定します。リクエストパラメータを挿入するには、${} を使用する必要があります。
SQL 文を作成する際は、次のルールに従ってください。
単一テーブルクエリ、テーブル結合クエリ、およびネストされたクエリは、同じデータソースでサポートされています。
SQL 文は次の要件を満たしている必要があります。
SQL 文は 1 つだけ作成できます。
SQL コメントは使用できません。
SELECT 文のみがサポートされています。 INSERT、UPDATE、DELETE などの他の文はサポートされていません。
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} を含む) はリクエストパラメータと見なされ、置き換えられます。 ${param} の前にエスケープ文字 (\) が配置されている場合、${param} は共通文字列として処理されます。
[SQL モード] パラメータを [高度な SQL] に設定した場合、MyBatis タグ付きの SQL 文を作成できます。
高度な SQL モードでは、if、choose、when、otherwise、trim、foreach、where などの MyBatis タグタイプがサポートされています。 MyBatis タグ付きの SQL 文を使用して、null パラメータチェック、複数値の循環トラバーサル、動的クエリ、動的ソート、集計分析などの複雑なクエリロジックを実装できます。一般的なシナリオのサンプルコードについては、「コードエディタで API を作成するために使用される高度な SQL 構文のサンプルコード」をご参照ください。
記述された MyBatis タグ付き SQL 文に特殊文字が含まれている場合は、特殊文字をエスケープする必要があります。次の表に、一般的な特殊文字に対応するエスケープ文字を示します。
特殊文字
エスケープ文字
説明
>
>
より大きい
>=
>=
以上
<
<
より小さい
<=
<=
以下
&
&
And
'
'
単一引用符
"
"
二重引用符
3. リクエストパラメータを構成する
右側のナビゲーションウィンドウで、[リクエストパラメータ] タブをクリックします。 [リクエストパラメータ] タブで、ビジネス要件に基づいてパラメータを構成します。
[SQL モード] パラメータを [高度な SQL] に設定した場合は、SQL 文で指定されているすべてのリクエストパラメータをパラメータリストに手動で追加する必要があります。これにより、API の詳細に記述されているパラメータと使用されているパラメータの一貫性が確保されます。
結果をプレビューする前に、API の各リクエストパラメータのサンプル値、デフォルト値、説明などの情報を構成する必要があります。
一致効率を向上させるには、インデックス付きフィールドをリクエストパラメータとして指定します。
パラメータ | 説明 |
[パラメータ名] | リクエストパラメータの名前。名前は最大 64 文字で、文字、数字、アンダースコア(_)、ハイフン(-) を使用できます。名前は文字で始める必要があります。 |
[タイプ] | リクエストパラメータのデータ型。有効な値: [STRING]、[INT]、[LONG]、[FLOAT]、[DOUBLE]、[BOOLEAN]。 |
[位置] | リクエストパラメータの位置。有効な値: [QUERY] および [BODY]。 説明 1 つ以上のリクエストパラメータの [位置] パラメータを [BODY] に設定する場合は、[content-type] パラメータを設定して、リクエスト本文のリクエストパラメータの形式を定義する必要があります。 [content-type] の有効な値:
|
[必須] | リクエストパラメータが必須かどうかを指定します。 |
[サンプル値] | リクエストパラメータのサンプル値。 |
[デフォルト値] | リクエストパラメータのデフォルト値。 |
[説明] | リクエストパラメータの説明。 |
4. レスポンスパラメータを構成する
右側のナビゲーションウィンドウで、[レスポンスパラメータ] タブをクリックします。 [レスポンスパラメータ] タブで、パラメータを構成します。
レスポンスパラメータを構成します。
[SQL モード] パラメータを [高度な SQL] に設定した場合は、SQL 文で指定されているすべてのレスポンスパラメータをパラメータリストに手動で追加する必要があります。これにより、API の詳細に記述されているパラメータと使用されているパラメータの一貫性が確保されます。
パラメータ
説明
[パラメータ名]
レスポンスパラメータの名前。名前は最大 64 文字で、文字、数字、アンダースコア(_)、ハイフン(-) を使用できます。名前は文字で始める必要があります。
[タイプ]
リクエストパラメータのデータ型。有効な値: [STRING]、[INT]、[LONG]、[FLOAT]、[DOUBLE]、[BOOLEAN]。
[サンプル値]
レスポンスパラメータのサンプル値。
[説明]
レスポンスパラメータの説明。
[戻り値のページネーション] パラメータを構成します。
[戻り値のページネーション] をオンにしない場合、API はデフォルトで最大 2,000 レコードを返します。
2,000 レコードを超えるレコードが返される可能性がある場合は、[戻り値のページネーション] をオンにすることをお勧めします。 [戻り値のページネーション] をオンにした場合は、[リソースグループ] タブに移動して、選択したリソースグループに基づいて [1 回のリクエストあたりのデータレコードの最大数] パラメータを構成できます。
説明[戻り値のページネーション] をオンにした後、返すレコード数はページネーション設定の影響を受けます。 [クエリ SQL を編集] セクションで SQL 文を作成して返すレコード数に制限を設定した場合、その制限は有効になりません。
[戻り値のページネーション] をオンにすると、次の一般的なパラメータが表示されます。
一般的なリクエストパラメータ
returnTotalNum: 1 回のリクエストの合計エントリ数を返すかどうかを指定します。
pageNum: 返すページ番号。
pageSize: 各ページで返すエントリ数。
一般的なレスポンスパラメータ
pageNum: 返すページ番号。
pageSize: 各ページで返すエントリ数。
totalNum: 返される合計エントリ数。
説明リクエストパラメータは API ではオプションです。 API のリクエストパラメータを指定しない場合は、[戻り値のページネーション] をオンにする必要があります。
5. フィルタを構成する
API のリクエストパラメータを前処理したり、API から返された結果を処理したりする必要がある場合は、次の手順を実行して API のフィルタを構成できます。右側のナビゲーションウィンドウで、[フィルタ] をクリックします。 [フィルタ] パネルで、ビジネス要件に基づいて [プリフィルタを使用] または [ポストフィルタを使用] を選択します。 [関数タイプ] パラメータを構成した後、[プリフィルタを使用] または [ポストフィルタを使用] チェックボックスの横にあるドロップダウンリストから 1 つ以上の関数を選択します。複数の関数を選択した場合、関数は選択された順序に基づいてパラメータの処理に使用されます。次に、[API 操作によって返されたレスポンスをプレビュー] をクリックして、選択した関数の処理結果が期待どおりかどうかを確認できます。フィルタの作成方法と使用方法の詳細については、「Aviator 関数を作成する」および「Python 関数を作成する」をご参照ください。
Python 関数をフィルタとして使用するには、DataWorks Professional Edition 以上をアクティブ化し、DataService Studio の共有リソースグループを使用する必要があります。
Aviator 関数をフィルタとして使用する場合、すべての DataWorks エディションがサポートされていますが、DataService Studio 専用のリソースグループを使用する必要があります。
使用する関数がドロップダウンリストにない場合は、関数が公開されているかどうかを確認してください。関数が公開されていない場合は、関数を公開します。または、新しい関数を作成して公開することもできます。詳細については、「関数のテスト、公開、および使用」をご参照ください。
6. DataService Studio のリソースグループを構成する
右側のナビゲーションウィンドウで、[リソースグループ] タブをクリックします。 [リソースグループタイプ] セクションで、[スキーマ] パラメータを構成します。
[スキーマ] パラメータには、[dataservice Studio 専用リソースグループ] または [dataservice Studio 共有リソースグループ] を選択できます。 [dataservice Studio 専用リソースグループ] を選択した場合は、[DataService Studio 専用リソースグループ] ドロップダウンリストから専用リソースグループを選択します。 [dataservice Studio 共有リソースグループ] を選択した場合は、リソースグループを選択する必要はありません。 DataWorks は、共有リソースグループを自動的に使用して API を生成します。
説明使用するリソースグループがドロップダウンリストに表示されない場合は、リソースグループ ページに移動し、リソースグループを見つけて、[アクション] 列の [ワークスペースを関連付ける] をクリックして、リソースグループをワークスペースに関連付けます。
使用するリソースグループがドロップダウンリストに表示されているが選択できない場合は、リソースグループ ページに移動し、リソースグループを見つけて、[アクション] 列の
> > > [クォータの管理] を選択して、[クォータの管理] ダイアログボックスに移動します。 [クォータの管理] ダイアログボックスで、DataService Studio のリソースグループの アクション[占有 CU] または [最小 CU] パラメータを手動で構成します。リソースグループの課金方法が従量課金制の場合は、[占有 CU] パラメータを構成する必要があります。リソースグループの課金方法がサブスクリプションの場合は、[最小 CU] パラメータを構成する必要があります。
[環境構成] セクションで、[メモリ]、[関数のタイムアウト]、[1 回のリクエストあたりのデータレコードの最大数] パラメータを構成できます。
[関数のタイムアウト] パラメータの最大値は、選択したリソースグループのタイプと使用する API Gateway インスタンスタイプによって異なります。
共有 API Gateway インスタンス: このパラメータの最大値は 30000 です。
専用 API Gateway インスタンス: [DataService Studio 共有リソースグループ] を選択した場合、このパラメータの最大値は 30000 です。 [DataService Studio 専用リソースグループ] を選択した場合、このパラメータの最大値は 90000 です。
説明API 操作の応答時間は、SQL 文の実際の処理時間によって異なります。応答タイムアウトによるリクエストの失敗を防ぐには、SQL 文の実際の処理時間に基づいて タイムアウト期間 を構成します。
[1 回のリクエストあたりのデータレコードの最大数] パラメータの最大値は、選択したリソースグループのタイプによって異なります。
[DataService Studio 共有リソースグループ] を選択した場合、このパラメータの最大値は 2000 です。
[DataService Studio 専用リソースグループ] を選択した場合、このパラメータの最大値は 10000 です。
説明返される結果の総数に制限はありません。返される結果の数は、実際のクエリ結果の数と同じです。
7. API を保存してコミットする
上部のツールバーにある 
アイコンをクリックします。 API が保存されると、選択したリソースグループがテスト中に有効になります。
API を構成した後、API をテストできます。詳細については、「API をテストする」をご参照ください。
テストが成功したら、右上隅にある [送信] をクリックします。
[API 構成] タブの右側のナビゲーションウィンドウで、[バージョン] をクリックします。公開する API バージョンを見つけて、[アクション] 列の [公開申請] をクリックして、申請ページに移動します。デフォルトのアプリケーションタイプ [データサービス API を公開] を使用し、[申請理由] フィールドに申請理由を入力します。次に、[権限を申請] をクリックして申請を送信します。
DataWorks 承認センターで承認ポリシーを定義した場合、API を公開するには、API を承認する必要があります。詳細については、「承認センター」をご参照ください。
API が公開されると、API の呼び出し時に DataService Studio のリソースグループの構成が有効になります。
[サービス開発] タブの左側のナビゲーションウィンドウで、登録済みの API を見つけて管理できます。たとえば、API の複製または削除を実行できます。 [サービス管理] タブで、公開済みの API を見つけて、公開済みの API の詳細を表示できます。詳細については、「API の表示、削除、移動、複製、複数 API に対するバッチ操作の実行、コード検索機能を使用した API の検索」をご参照ください。