DataWorks:コンポーネント管理

ステップ 1：コンポーネントの定義

開発者は、DataStudio の SQL スクリプトテンプレート ページを使用して、プロシージャ本体のコードおよびその入力・出力パラメーターを定義できます。抽象化された SQL 処理を記述することで、入力パラメーターを用いて指定された入力テーブルを処理し、出力パラメーターで表される価値ある出力テーブルを生成できます。コード内における入力および出力パラメーターの書式は、@@{parameter_name} です。

1. ワークスペース固有スクリプトテンプレート管理エリアで をクリックし、SQL スクリプトテンプレートの作成 を選択します。また、先に ディレクトリの作成 を選択してスクリプトテンプレートのフォルダ構成を計画した後、フォルダを右クリックして SQL スクリプトテンプレートの作成 を選択することもできます。

   説明

   • 当該ワークスペースのメンバーが作成したコンポーネントは、ワークスペース SQL スクリプトテンプレート 配下で管理されます。

   • 公開済みのコンポーネントは、公開 SQL スクリプトテンプレート 配下で確認できます。

2. コンポーネント情報を設定できます。

   1. プロシージャ本体の設定

      プロシージャ本体は、スクリプトテンプレートの実装コードです。@@{parameter_name} 書式を用いた抽象化 SQL コードを記述することで、入力および出力パラメーターを含めることができます。これにより、入力パラメーターを用いて指定された入力テーブルを処理し、価値ある出力テーブルを生成できます。その後、スクリプトテンプレートを利用する際に、異なる入力および出力パラメーターを設定するだけで、正しく実行可能な SQL コードを生成できます。

   2. 入力パラメーターの設定

      コンポーネント編集ページの右側で、[パラメーター設定] をクリックします。プロシージャ本文の入力パラメーターを定義するには、[入力パラメーター] の右側にある アイコンをクリックします。入力パラメーターは、[テーブル] または [文字列] として指定できます。

      説明

      また、スクリプトテンプレートエディター画面の上部にある [I/O パラメーターの解析] をクリックすることもできます。この機能により、コードから自動的に入力および出力パラメーターを検出できます。その後、以下の表に従ってパラメーターを構成できます。

      テーブル

      適用シーン

      スクリプトテンプレートがソーステーブルのデータを処理し、単一かつ定数カテゴリの出力結果を生成する場合に使用します。

      構成パラメーターおよび説明

      • 主なパラメーター：　パラメーター定義

      • 構成の説明：　このパラメーターは、フィールド名、データの型、説明を含むテキスト形式で入力テーブルのスキーマを定義します。この定義により、ユーザーはスクリプトテンプレートを利用する際に、設定する入力テーブルがここで定義されたフィールド数および互換性のあるデータの型と一致することを把握できます。これにより、設定された入力テーブルと定義された入力テーブルとの間でフィールド数やデータの型が不一致となることによる実行時エラーを防止できます。

        説明

        この定義は参考用であり、入力パラメーターの構成をヒントするものであり、即時のチェックは実行されません。

      • 例：

        以下の形式でパラメーターを定義することを推奨します：

        Field1_Name Field1_Type Field1_Comment 
        Field2_Name Field2_Type Field2_Comment 
        ...
        Fieldn_Name Fieldn_Type Fieldn_Comment

        サンプル構成：

        area_id STRING 'area ID' 
        city_id STRING 'city ID' 
        order_amt DOUBLE 'Order amount' 

      文字列

      適用シーン

      ソーステーブルのデータを処理する際に、変数を用いて入力パラメーターの値を制御する場合に使用します。

      構成パラメーターおよび説明

      • 主なパラメーター：　デフォルト値

      • 構成の説明：　このパラメーター型に対してデフォルト値を設定できます。デフォルト値が設定されている場合、スクリプトテンプレート実行時にその値が使用されます。

      • 例：

        • シナリオ 1：スクリプトテンプレートの出力テーブルは、各リージョンにおける売上上位 N 都市の情報を表示する必要があります。この場合、N をスクリプトテンプレートの入力パラメーターとして設定し、文字列パラメーターを用いて N の値を制御できます。

        • シナリオ 2：スクリプトテンプレートの出力テーブルは、ある都道府県の総売上を表示する必要があります。この場合、都道府県名を文字列パラメーターとして設定し、スクリプトテンプレートの入力パラメーターとして使用できます。異なる都道府県を指定することで、対応する都道府県の売上データを取得できます。

   3. 出力パラメーターの設定

      プロシージャ本体の出力パラメーターを定義します。これは、スクリプトテンプレートの最終的な出力テーブルを表します。他のユーザーがスクリプトテンプレートをより容易に利用できるよう、出力パラメーター設定内で出力テーブルのスキーマを指定できます。

      コンポーネント編集ページの右側で、[パラメーター設定] をクリックします。[出力パラメーター] の右側にある アイコンをクリックして、プロシージャ本文の出力パラメーターを定義します。

      説明

      また、スクリプトテンプレートエディター画面の上部にある [I/O パラメーターの解析] をクリックすることもできます。この機能により、コードから自動的に入力および出力パラメーターを検出できます。その後、以下の表に従ってパラメーターを構成できます。

      • 主なパラメーター：　パラメーター定義

      • 構成の説明：　このパラメーターは、フィールド名、データの型、説明を含むテキスト形式で出力テーブルのスキーマを定義します。この定義により、ユーザーはスクリプトテンプレートを利用する際に、設定する出力テーブルがここで定義されたフィールド数および互換性のあるデータの型と一致することを把握できます。これにより、設定された出力テーブルと定義された出力テーブルとの間でフィールド数やデータの型が不一致となることによる実行時エラーを防止できます。

        説明

        この定義は参考用であり、出力パラメーターの構成をヒントするものであり、即時のチェックは実行されません。

      • 例：

        以下の形式でパラメーターを定義することを推奨します：

        Field1_Name Field1_Type Field1_Comment 
        Field2_Name Field2_Type Field2_Comment 
        ...
        Fieldn_Name Fieldn_Type Fieldn_Comment

        また、処理ニーズに応じて、順位や総収益などの集計結果用フィールドを出力パラメーター定義に追加できます。例えば：

        area_id STRING 'area ID' 
        city_id STRING 'city ID' 
        order_amt DOUBLE 'Order amount'
        rank BIGINT 'rank'

3. 保存 および コミット をクリックします。

   スクリプトテンプレートが作成された後、SQL スクリプトテンプレートノードでこれを参照して、ビジネス要件に応じたターゲットテーブルを迅速に生成できます。詳細については、「ステップ 2：スクリプトテンプレートの参照」をご参照ください。

4. （任意）SQL スクリプトテンプレートを公開 をクリックして、汎用的なスクリプトテンプレートをテナント全体に公開できます。公開後、公開 SQL スクリプトテンプレート エリアに表示されます。公開されたスクリプトテンプレートは、テナント内のすべてのユーザーが利用できます。

ステップ 2：コンポーネントの参照

以下のようにコンポーネントを参照できます。

アップグレード操作：スクリプトテンプレート開発者

開発者は、必要に応じてスクリプトテンプレートのコードおよびパラメーター設定を編集できます。変更を保存およびコミットすると、スクリプトテンプレートは新バージョンへアップグレードされます。バージョン タブで、各バージョンの詳細を確認できます。

参照バージョンのアップグレード：スクリプトテンプレートユーザー

スクリプトテンプレートがアップグレードされた後、ご利用の SQL スクリプトテンプレートノードがそれを参照している場合、最新バージョンを利用するかどうかを選択できます。

• 新バージョンを利用しない場合は、元のバージョンを引き続き使用できます。

• 新バージョンを利用する場合は、新バージョンのパラメーター設定がご利用の SQL スクリプトテンプレートノードにおいて依然として有効であるかを確認してください。新バージョンの説明に基づいて調整を行い、その後ノードをコミットおよび公開します。コミットおよび公開の手順は、標準の SQL ノードと同一です。

アップグレードのシナリオ例

開発者が SQL スクリプトテンプレートのバージョン V1 を作成し、他のユーザーがこれを利用しています。その後、開発者がスクリプトテンプレートをバージョン V2 にアップグレードしました。テンプレートを利用するユーザーは、新バージョン V2 が利用可能であることに気づきます。ユーザーはスクリプトテンプレートを開き、両方のバージョンの詳細を表示・比較します。新バージョンがより優れたビジネス成果を提供することを確認した後、ノードを最新バージョンに更新します。

コンポーネントのクローン

クローン機能を用いることで、既存のスクリプトテンプレートから新しいスクリプトテンプレートを迅速に作成できます。クローンされる内容には、スクリプトテンプレートのコード、パラメーター構成、および Run Configuration から取得したスクリプトパラメーターが含まれます。

1. 左側の ワークスペース SQL スクリプトテンプレート パネルで、クローンするコンポーネントの名前を右クリックし、ポップアップメニューから クローン を選択します。

2. ダイアログボックスで、名前 および パス を変更するか（またはデフォルト値をそのまま使用し）、OK をクリックしてクローンを開始します。

3. クローンが完了すると、ワークスペース SQL スクリプトテンプレート セクションで新たに生成されたスクリプトテンプレートを確認できます。

バージョン管理

バージョン管理機能を用いることで、スクリプトテンプレートを特定の履歴バージョンに復元できます。また、バージョンの表示および比較も可能であり、差分の分析および調整に役立ちます。

1. 左側の ワークスペース SQL スクリプトテンプレート パネルで、コンポーネントの名前をダブルクリックして編集ページを開き、バージョンの表示および管理を行います。

2. エディター画面の右側で バージョン をクリックします。バージョン ページで、開発履歴 および デプロイメント履歴 を表示および管理できます。

   • バージョンの表示：

     1. 開発履歴 または デプロイメント履歴 タブで、表示したいスクリプトテンプレートのバージョンを見つけます。

     2. 表示 を 操作 列でクリックし、詳細ページに移動してスクリプトテンプレートのコードおよびスケジュール構成を確認します。

   • バージョンの比較：

     開発履歴 または デプロイメント履歴 タブで、スクリプトテンプレートの異なるバージョンを比較できます。以下の例では、開発記録を用いて比較操作を説明します。

     • 開発環境または本番環境におけるバージョンの比較：　開発履歴 タブで、2 つのバージョンを選択し、上部の 比較対象バージョンの選択 ボタンをクリックします。これにより、異なるバージョンのスクリプトテンプレートのコードおよびスケジュール構成を比較できます。

     • 開発環境と本番環境の比較：

       1. 開発履歴 タブで、スクリプトテンプレートの特定のバージョンを特定します。

       2. 比較 ボタンを 操作 列でクリックします。詳細ページで、デプロイメント履歴 から比較対象のバージョンを選択します。

   • [復元] バージョン:

     スクリプトテンプレートを特定の履歴バージョンに復元するには、開発履歴 からのみ可能です。開発履歴 タブで、対象のバージョンを見つけ、復元 ボタンを 操作 列でクリックします。この操作により、スクリプトテンプレートが選択したバージョンに復元されます。