すべてのプロダクト
Search
ドキュメントセンター

DataWorks:スクリプトテンプレートを開発する

最終更新日:Feb 15, 2025

スクリプトテンプレートは、複数の入力パラメーターと出力パラメーターを含む SQL コードプロセスを定義します。 1 つ以上のソーステーブルを SQL コードプロセスに導入し、SQL コードプロセスを使用してソーステーブルデータをフィルタリングし、ソーステーブルを結合し、データを集計して、ビジネスに必要な出力テーブルを生成できます。 このトピックでは、スクリプトテンプレートの概要と、スクリプトテンプレートの定義と使用方法について説明します。

スクリプトテンプレートの 概要

はじめに

実際のビジネス シナリオでは、多数の SQL コード プロセスが類似しています。これらのプロセスの入力テーブルまたは出力テーブルは、同じスキーマまたは互換性のあるデータ型を持つ場合がありますが、テーブル名は異なります。この場合、開発者は SQL コード プロセスに基づいてスクリプト テンプレートを作成して、SQL コードを再利用できます。スクリプト テンプレートは、入力テーブルから入力パラメーターを、出力テーブルから出力パラメーターを抽出します。

SQL スニペット ノードを作成する場合、ビジネス プロセスに基づいてスクリプト テンプレート リストから既存のスクリプト テンプレートを選択し、選択したスクリプト テンプレートのビジネスの入力テーブルと出力テーブルに特定のパラメーターを設定するだけで済みます。この方法では、コードを繰り返し編集する必要はありません。これは、開発中の反復的な操作を防ぎ、開発効率を向上させるのに役立ちます。作成された SQL スニペット ノードは、他の SQL ノードをデプロイおよび実行するのと同じ方法でデプロイおよび実行できます。

権限

スクリプトテンプレートを作成して使用するには、[開発] ロールが割り当てられている必要があります。ロールを割り当てる方法については、「ワークスペースレベルのサービスに対する権限を管理する」トピックのRAM ユーザーをワークスペースにメンバーとして追加し、メンバーにロールを割り当てる」セクションをご参照ください。

制限

  • SQL スニペットノードは、DataWorks Standard Edition 以降のエディションでのみサポートされています。詳細については、「DataWorks エディション間の違い」をご参照ください。

  • 現在のワークスペースのメンバーアカウントで作成されたスクリプトテンプレートは、[ワークスペース固有] タブで使用できます。

  • テナント内で作成されたスクリプトテンプレートは、[パブリック] タブで使用できます。

スクリプトテンプレートの種類

スクリプトテンプレートは、ワークスペースレベルとパブリックスクリプトテンプレートに分類されます。スクリプトテンプレートを作成するときに、スクリプトテンプレートの種類を指定できます。

  • ワークスペースレベルのスクリプトテンプレート: この種類のスクリプトテンプレートがデプロイされると、現在の DataWorks ワークスペースのメンバーのみがこの種類のスクリプトテンプレートを使用できます。この種類のスクリプトテンプレートを使用するには、現在の DataWorks ワークスペースのメンバーである必要があります。詳細については、「ワークスペースレベルのサービスに対する権限の管理」トピックのRAM ユーザーをワークスペースにメンバーとして追加し、メンバーにロールを割り当てる」セクションをご参照ください。

  • パブリックスクリプトテンプレート: この種類のスクリプトテンプレートの開発者は、[公開] タブに移動し、現在のテナント内で汎用スクリプトテンプレートを公開できます。これにより、現在のテナント内のすべてのユーザーがスクリプトテンプレートを使用できます。

スクリプトテンプレートを使用する

[スクリプトテンプレート] は、DataWorks で作成され、[SQL スニペットノード] と連携して動作する必要があります。

  1. スクリプトテンプレートを定義する.

    [スニペット] ペインで、開発者は SQL コードプロセスを抽象化し、入力パラメーターと出力パラメーターを定義できます。このようにして、SQL コードプロセスは入力パラメーターに基づいて特定の入力テーブルを処理し、出力パラメーターに基づいてビジネス価値のある出力テーブルを生成できます。入力パラメーターと出力パラメーターは、@@{パラメーター名} 形式で設定されます。

    • 次のタイプの入力パラメーターがサポートされています。

      • テーブル: 出力結果が単一タイプの値の場合、このタイプの入力パラメーターを使用します。

      • 文字列: 入力パラメーターの値が変数に基づいて制御される場合、このタイプの入力パラメーターを使用します。

    • 出力パラメーターのタイプはテーブルである必要があります。

  2. スクリプトテンプレートを参照する.

    [datastudio] ページで、SQL スニペットノードを作成して目的のスクリプトテンプレートを参照し、スクリプトテンプレートの入力パラメーターと出力パラメーターを置き換えてコードを再利用できます。

スクリプトテンプレートを定義する

スニペットペインに移動する

  1. [datastudio] ページに移動します。

    DataWorks コンソール にログオンします。 上部のナビゲーションバーで、目的のリージョンを選択します。 左側のナビゲーションウィンドウで、[データ開発および O&M] > [データ開発] を選択します。 表示されたページで、ドロップダウンリストから目的のワークスペースを選択し、[データ開発に移動] をクリックします。

  2. [DataStudio] ページの左側のナビゲーションウィンドウで、[スニペット] をクリックします。

    説明

    [スニペット] モジュールが左側のナビゲーションウィンドウに表示されない場合は、左下隅にある 设置 アイコンをクリックし、DataStudio モジュールセクションの設定 に記載されている手順に従ってモジュールを追加します。

スクリプトテンプレートを作成および構成する

このセクションでは、[スニペット] ペインでスクリプトテンプレートを作成する方法について説明します。 ほとんどの場合、スクリプトテンプレートは、入力パラメーター、出力パラメーター、および SQL コードプロセスで構成されます。 SQL コードプロセスは、スクリプトテンプレートの機能を実装するコードを定義します。 SQL コードプロセスでは、可変入力テーブルまたは入力文字列はスクリプトテンプレートの入力パラメーターとして抽象化され、可変出力テーブルはスクリプトテンプレートの出力パラメーターとして抽象化されます。 これにより、SQL コードを再利用できます。 入力パラメーターと出力パラメーターは、@@{変数名} 形式で構成されます。

説明

スクリプトテンプレートには、複数の入力パラメーターと出力パラメーターを含めることができます。 ビジネス要件に基づいてパラメーターを構成できます。

过程体

ステップ 1:スクリプトテンプレートを作成する

[スニペット] ペインで、次の図に示すいずれかの方法を使用して、スクリプトテンプレートを作成し、名前を付けることができます。创建组件

説明
  • 現在のワークスペースのメンバーアカウントを使用して作成されたスクリプトテンプレートは、[ワークスペース固有] タブで使用できます。

  • テナント内で作成されたスクリプトテンプレートは、[パブリック] タブで使用できます。

ステップ 2:スクリプトテンプレートを構成する

  1. SQL コードプロセスを構成する。

    SQL コードプロセスは、スクリプトテンプレートの機能を実装するコードを定義します。 @@{パラメーター名} 形式の入力パラメーターと出力パラメーターをスクリプトテンプレートに導入するために、抽象 SQL コードプロセスを定義できます。 これにより、スクリプトテンプレートは、入力パラメーターに基づいて入力テーブルを制御および処理し、ビジネス価値のある出力テーブルを生成できます。 スクリプトテンプレートを使用する場合、特定の入力パラメーターと出力パラメーターのみを構成する必要があります。 その後、実行可能な SQL コードを生成できます。

  2. 入力パラメーターを構成する。

    このステップでは、入力パラメーターを構成できます。 入力パラメーターのタイプは、[テーブル] または [文字列] です。

    • [テーブル]:出力結果が単一タイプのテーブルの場合、このタイプを使用します。

      次の表に、テーブルタイプの入力パラメーターのパラメーター定義を示します。

      項目

      説明

      [パラメーター定義]

      パラメーター定義は、フィールド名、フィールドタイプ、フィールドの説明を含むテーブルスキーマのテキスト定義です。 後でスクリプトテンプレートを使用する場合、テーブルタイプのパラメーターに定義されているのと同じ数のフィールドと互換性のあるフィールドタイプを含む入力テーブルを指定する必要があります。 テーブルタイプのパラメーターに定義されているのと同じ数のフィールドと互換性のあるフィールドタイプを含む入力テーブルを指定しないと、スクリプトテンプレートの実行時にエラーが返されます。

      説明

      パラメーター定義は参照用であり、即時の強制チェックはトリガーされません。

      次の形式でパラメーターを定義することをお勧めします。

      フィールド 1 の名前 フィールド 1 のタイプ フィールド 1 の説明
      フィールド 2 の名前 フィールド 2 のタイプ フィールド 2 の説明
      …
      フィールド n の名前 フィールド n のタイプ フィールド n の説明

      例:

      area_id string 'リージョン ID'
      city_id string '都市 ID'
      order_amt double '注文金額'
    • [文字列]:入力パラメーターの値が変数に基づいて制御される場合、このタイプを使用します。

      次の表に、文字列タイプの入力パラメーターの構成を示します。

      項目

      説明

      [デフォルト値]

      文字列タイプのパラメーターにデフォルト値を指定できます。 スクリプトテンプレートを使用する場合、デフォルト値がデフォルトで使用されます。

      [サンプルシナリオ]

      • [シナリオ 1]:SQL コードプロセスの出力テーブルに各リージョンの上位 N 都市のみの売上高をエクスポートするには、文字列タイプのパラメーターを使用して N の値を指定します。

      • [シナリオ 2]:SQL コードプロセスの出力テーブルに県の売上高合計をエクスポートするには、文字列タイプのパラメーターを使用して県名を指定し、指定された県の売上データを取得します。

  3. 出力パラメーターを構成する。

    このステップでは、出力パラメーターを構成して、SQL コードプロセスで生成されるテーブルを定義できます。 スクリプトテンプレートの使用を容易にするために、参照用に出力テーブルのスキーマを指定できます。

    次の表に、出力パラメーターのパラメーター定義を示します。

    項目

    説明

    [パラメーター定義]

    パラメーター定義は、フィールド名、フィールドタイプ、フィールドの説明を含むテーブルスキーマのテキスト定義です。 後でスクリプトテンプレートを使用する場合、テーブルタイプのパラメーターに定義されているのと同じ数のフィールドと互換性のあるフィールドタイプを含む出力テーブルを指定する必要があります。 テーブルタイプのパラメーターに定義されているのと同じ数のフィールドと互換性のあるフィールドタイプを含む出力テーブルを指定しないと、エラーが返されます。

    説明

    パラメーター定義は参照用であり、即時の強制チェックはトリガーされません。

    次の形式でパラメーターを定義することをお勧めします。

    フィールド 1 の名前 フィールド 1 のタイプ フィールド 1 の説明
    フィールド 2 の名前 フィールド 2 のタイプ フィールド 2 の説明
    …
    フィールド n の名前 フィールド n のタイプ フィールド n の説明

    さらに、ビジネス要件に基づいて、集計された出力結果を示すフィールドをパラメーター定義に追加できます。 たとえば、ランキングフィールドや収益フィールドを追加できます。

    例:

    area_id string 'リージョン ID'
    city_id string '都市 ID'
    order_amt double '注文金額'
    rank bigint 'ランキング'

ステップ 3:スクリプトテンプレートを保存してコミットする

スクリプトテンプレートの構成タブの上部ツールバーにある 保存 アイコンをクリックして、スクリプトテンプレートを保存します。 次に、提交 アイコンをクリックして、スクリプトテンプレートをコミットします。 スクリプトテンプレートが作成された後、SQL スニペットノードでスクリプトテンプレートを参照できます。 これは、ビジネスに必要なテーブルを生成するのに役立ちます。 詳細については、このトピックの「スクリプトテンプレートを参照する」セクションをご参照ください。

スクリプトテンプレートを参照する

前提条件

スクリプトテンプレートを参照する

SQL スニペットノードの構成タブで、次の図に示されている手順に従って、スクリプトテンプレートを参照します。image.png

  1. 参照するスクリプトテンプレートを選択します。

    使用可能なスクリプトテンプレートがない場合は、スクリプトテンプレートを作成します。詳細については、このトピックの「スクリプトテンプレートを定義する」セクションをご参照ください。

    • 選択したスクリプトテンプレートに最新バージョンがある場合は、ビジネス要件に基づいて、スクリプトテンプレートの最新バージョンを参照するかどうかを決定します。スクリプトテンプレートの最新バージョンを参照するには、[コードの更新] をクリックします。

    • [スニペットの編集] をクリックして、スクリプトテンプレートの詳細を表示します。

  2. ビジネス要件に基づいて、スクリプトテンプレートのパラメーターを構成します。

次の手順

作成したノードを使用してタスクの開発を完了したら、次の操作を実行できます。

  • スケジューリングプロパティの構成: ノードの定期的なスケジューリングのプロパティを構成できます。システムでノード上のタスクを定期的にスケジュールおよび実行する場合は、再実行設定やスケジューリングの依存関係など、ノードの項目を構成する必要があります。詳細については、「概要」をご参照ください。

  • ノードのデバッグ: ノードのコードをデバッグおよびテストして、コードロジックが期待どおりに動作するかどうかを確認できます。詳細については、「デバッグ手順」をご参照ください。

  • ノードのデプロイ: すべての開発操作が完了したら、ノードをデプロイできます。ノードがデプロイされると、システムはノードのスケジューリングプロパティに基づいてノードを定期的にスケジュールします。詳細については、「ノードのデプロイ」をご参照ください。

スクリプトテンプレートの管理

スクリプトテンプレートを共有し、スクリプトテンプレートの参照レコードを表示する

ビジネス要件に基づいて、スクリプトテンプレートを共有したり、スクリプトテンプレートの参照レコードを表示したりできます。分享及查看引用记录

  • スクリプトテンプレートを共有する: スクリプトテンプレートがデプロイされると、スクリプトテンプレートはワークスペースレベルのスクリプトテンプレートになります。 現在のワークスペースのメンバーのみがスクリプトテンプレートを使用できます。 開発した汎用スクリプトテンプレートの構成タブにある上部のツールバーの [Snippet の公開] アイコンをクリックすると、現在のテナント内でスクリプトテンプレートを公開できます。 これにより、現在のテナント内のすべてのユーザーがスクリプトテンプレートを使用できるようになります。 [Snippet の公開] アイコンは、前の図の 1 でマークされています。

  • スクリプトテンプレートの参照レコードを表示する: [Snippet ノード] タブで、現在のスクリプトテンプレートを参照するノードを表示できます。 これにより、行おうとしているスクリプトテンプレートの変更の影響を推定できます。 [Snippet ノード] タブは、前の図の 2 でマークされています。

スクリプトテンプレートをアップグレードする

オペレーター: 開発者

開発したスクリプトテンプレートのコードを編集し、ビジネス要件に基づいてスクリプトテンプレートのパラメーター設定を変更できます。 変更が保存され、スクリプトテンプレートが再コミットされると、スクリプトテンプレートは新しいバージョンにアップグレードされます。 各バージョンの詳細は、スクリプトテンプレートの構成タブにある右側 <ナビゲーションウィンドウ> の [バージョン] タブで表示できます。 [バージョン] タブは、次の図の 3 でマークされています。组件升级

バージョンの変更がスクリプトテンプレートの使用に与える影響

スクリプトテンプレートがアップグレードされ、SQL Snippet ノードでスクリプトテンプレートを参照する場合、スクリプトテンプレートの最新バージョンを使用するかどうかを決定できます。 スクリプトテンプレートの最新バージョンを使用する場合は、スクリプトテンプレートの最新バージョンのパラメーター設定が SQL Snippet ノードに有効かどうかを確認し、テンプレートの説明に基づいて構成を変更します。 次に、SQL Snippet ノードをコミットしてデプロイします。 SQL Snippet ノードは、他の SQL ノードをコミットおよびデプロイするのと同じ方法でコミットおよびデプロイできます。image.png

サンプルシナリオ

開発者 C は V1.0 バージョンのスクリプトテンプレートを作成します。 ユーザー A は V1.0 スクリプトテンプレートを使用します。 次に、開発者 C はスクリプトテンプレートを V1.0 から V2.0 にアップグレードします。 ユーザー A は、スクリプトテンプレートの使用中に、スクリプトテンプレートに最新バージョン V2.0 があることを確認します。 ユーザー A はスクリプトテンプレートを開き、最新バージョンの詳細を表示できます。 スクリプトテンプレートの最新バージョンでより良いビジネス効果が得られる場合、ユーザー A は最新バージョンを使用するように構成を変更できます。

その他の参考資料

スクリプトテンプレートの構成タブの機能

界面

機能

説明

[保存]

現在のスクリプトテンプレートの設定を保存します。

[ロックを解除]

スクリプトテンプレートの所有者でない場合、現在のスクリプトテンプレートのロックを解除して、スクリプトテンプレートを編集できます。

[送信]

現在のスクリプトテンプレートを開発環境にコミットします。

[スニペットを公開]

汎用スクリプトテンプレートを現在のテナントに公開します。これにより、テナント内のすべてのユーザーがスクリプトテンプレートを表示および使用できるようになります。

[I/O パラメーターを解析]

コードから入力パラメーターと出力パラメーターを解析します。

[実行]

開発環境で現在のスクリプトテンプレートを実行します。

[停止]

実行中の現在のスクリプトテンプレートを停止します。

[コードのフォーマット]

キーワードでコードをフォーマットします。

[パラメーター]

現在のスクリプトテンプレートの基本情報を表示し、入力パラメーターと出力パラメーターを構成できます。

[バージョン]

現在のスクリプトテンプレートのデプロイ済みバージョンを表示できます。

[スニペットノード]

現在のスクリプトテンプレートの参照レコードを表示します。

ベスト プラクティス

前提条件

手順 1:スクリプト テンプレートを定義する

get_top_n という名前のスクリプト テンプレートを作成します。詳細については、このトピックの「スクリプト テンプレートを定義する」セクションをご参照ください。次の説明は、スクリプト テンプレートの構成を示しています。image.png

  • パラメーター設定

    カテゴリ

    パラメーター

    タイプ

    説明

    パラメーター定義

    入力パラメーター

    myinputtable

    table

    売上データ テーブルを指定します。

    area_id string
    city_id string
    order_amt double
    rank bigint

    topn

    string

    上位都市の数を指定します。

    該当なし

    出力パラメーター

    myoutput

    table

    各地域の上位都市のランキングを表示する出力テーブルを指定します。

    area_id string
    city_id string
    order_amt double
    rank bigint
  • SQL コード プロセスの定義

    INSERT OVERWRITE TABLE  @@{myoutput}  PARTITION (pt='${bizdate}')
     SELECT r3.area_id,
     r3.city_id,
     r3.order_amt,
     r3.rank
    from (
    SELECT
       area_id,
       city_id,
       rank,
       order_amt_1505468133993_sum as order_amt ,
       order_number_1505468133991_sum,
       profit_amt_1505468134000_sum
    FROM
       (SELECT
       area_id,
       city_id,
       ROW_NUMBER() OVER (PARTITION BY r1.area_id ORDER BY r1.order_amt_1505468133993_sum DESC) AS rank,
       order_amt_1505468133993_sum,
       order_number_1505468133991_sum,
       profit_amt_1505468134000_sum
    FROM
       (SELECT
       area AS area_id,
       city AS city_id,
       SUM(order_amt) AS order_amt_1505468133993_sum,
       SUM(order_number) AS order_number_1505468133991_sum,
       SUM(profit_amt) AS profit_amt_1505468134000_sum
    FROM
      @@{myinputtable}
    WHERE
       SUBSTR(pt, 1, 8) IN ( '${bizdate}' )
    GROUP BY
       area,
       city )
       r1 ) r2
    WHERE
       r2.rank >= 1 AND r2.rank <= @@{topn}
    ORDER BY
       area_id,
       rank limit 10000) r3;

手順 2: スクリプト テンプレートを使用する

xc_Referenced script template_get_top_n という名前の SQL スニペットノードを作成し、手順 1 で作成した get_top_n スクリプト テンプレートを参照してから、パラメーターを構成します。次の図は、パラメーター構成手順を示しています。 SQL スニペットノードを作成してスクリプト テンプレートを参照する方法の詳細については、このトピックの「スクリプト テンプレートを参照する」セクションをご参照ください。 image.png パラメーター設定:

  • 入力パラメーター myinputtablecompany_sales_record という名前の入力テーブルをデータソースとして指定します。入力テーブルのスキーマ:

    company_sales_record

    CREATE TABLE IF NOT EXISTS company_sales_record
    (
        order_id         STRING COMMENT 'Order ID (PK)',
        report_date      STRING COMMENT 'Order generation date',
        customer_name    STRING COMMENT 'Customer name',
        order_level      STRING COMMENT 'Order level',
        order_number     DOUBLE COMMENT 'Number of orders',
        order_amt        DOUBLE COMMENT 'Order amount',
        back_point       DOUBLE COMMENT 'Discount',
        shipping_type    STRING COMMENT 'Transportation method',
        profit_amt       DOUBLE COMMENT 'Amount of profit',
        price            DOUBLE COMMENT 'Unit price',
        shipping_cost    DOUBLE COMMENT 'Cost of transportation',
        area             STRING COMMENT 'Region',
        province         STRING COMMENT 'Province',
        city             STRING COMMENT 'City',
        product_type     STRING COMMENT 'Product type',
        product_sub_type STRING COMMENT 'Product subtype',
        product_name     STRING COMMENT 'Product name',
        product_box      STRING COMMENT 'Product packaging',
        shipping_date    STRING COMMENT 'Date of transportation'
    ) 
    COMMENT 'Detailed sales data'
    PARTITIONED BY
    (
        pt               STRING
    )
    LIFECYCLE 365;
  • 入力パラメーター topn:各地域の都市の売上高合計のランキングに基づいて、昇順で上位都市の数を指定します。この例では、このパラメーターは 10 に設定されています。

  • 出力パラメーター myoutputcompany_sales_top_n という名前の出力テーブルを指定します。出力テーブルには、データ処理結果が含まれています。出力テーブルのスキーマ:

    company_sales_top_n

    CREATE TABLE IF NOT EXISTS company_sales_top_n
    ( 
    area STRING COMMENT 'Region', 
    city STRING COMMENT 'City', 
    sales_amount DOUBLE COMMENT 'Sales amount', 
    rank BIGINT COMMENT 'Ranking'
    )
    COMMENT 'Company sales rankings'
    PARTITIONED BY (pt STRING COMMENT '')
    LIFECYCLE 365;