DataWorks:拡張機能の開発とデプロイ：Function Compute

制限事項

• DataWorks Enterprise Edition のユーザーのみが拡張モジュールを使用できます。

• 拡張モジュールは、中国 (北京)、中国 (杭州)、中国 (上海)、中国 (張家口)、中国 (深セン)、中国 (成都)、米国 (シリコンバレー)、米国 (バージニア)、ドイツ (フランクフルト)、日本 (東京)、中国 (香港)、シンガポールの各リージョンで利用できます。

注意事項

• [オープンプラットフォーム管理者]、[テナント管理者]、Alibaba Cloud アカウント、および [AliyunDataWorksFullAccess] ポリシーがアタッチされている RAM ユーザーのみが、開発者バックエンドに対する読み取りおよび書き込み権限を持ちます。権限管理の詳細については、「グローバルサービスの権限コントロール」および「サービスおよびコンソールの権限に関する RAM ポリシー」をご参照ください。

• バージョンの制限：DataWorks Enterprise Edition のサブスクリプションが有効期限切れになると、すべての拡張機能が非アクティブになり、イベントチェックのためにトリガーされなくなります。トリガーされたものの、まだ最終状態に達していないチェックはすべて自動的にパスされます。

• ノードの制限：Platform for AI ノード、do-while ノード、for-each ノードなどの内部ノードを含む複合ノードがチェックをトリガーした場合、後続の操作に進む前に、すべての内部ノードがチェックに合格する必要があります。

• トリガー：同じ拡張ポイントイベントに複数の拡張機能を関連付けることができます。つまり、1 つのイベントで複数の拡張機能がトリガーされる可能性があります。

• イベントの制限：Function Compute を使用してデプロイされた拡張機能は、現在、データダウンロードの事前イベント、アセット公開・非公開の事前イベント、およびデータアップロードの事前イベントをサポートしています。

ステップ 1：拡張機能の依存関係の設定

拡張機能を開発する際に、pom.xml ファイルに次の依存関係を追加します。

<dependency>
 <groupId>com.aliyun</groupId>
 <artifactId>dataworks_public20200518</artifactId>
 <version>5.6.0</version>
</dependency>

<!-- https://mvnrepository.com/artifact/com.aliyun.fc.runtime/fc-java-core -->
<dependency>
    <groupId>com.aliyun.fc.runtime</groupId>
    <artifactId>fc-java-core</artifactId>
    <version>1.4.1</version>
</dependency>
<!-- https://mvnrepository.com/artifact/com.aliyun.fc.runtime/fc-java-event -->
<dependency>
    <groupId>com.aliyun.fc.runtime</groupId>
    <artifactId>fc-java-event</artifactId>
    <version>1.2.0</version>
</dependency>

<build>
        <plugins>
              <plugin>
                  <groupId>org.apache.maven.plugins</groupId>
                  <artifactId>maven-shade-plugin</artifactId>
                  <version>3.2.1</version>
                  <executions>
                    <execution>
                      <phase>package</phase>
                      <goals>
                        <goal>shade</goal>
                      </goals>
                      <configuration>
                        <filters>
                          <filter>
                            <artifact>*:*</artifact>
                            <excludes>
                              <exclude>META-INF/*.SF</exclude>
                              <exclude>META-INF/*.DSA</exclude>
                              <exclude>META-INF/*.RSA</exclude>
                            </excludes>
                          </filter>
                        </filters>
                      </configuration>
                    </execution>
                  </executions>
              </plugin>
        </plugins>
</build>

ステップ 2：拡張機能コードの開発

Function Compute で拡張機能を開発するには、PojoRequestHandler インターフェイスを使用して handleRequest メソッドを実装する必要があります。このメソッドは、ExtensionRequest クラスのリクエストと Context を受信します。その後、拡張機能の処理ロジックを定義し、ExtensionResponse クラスを使用して結果を返します。

1. コードを開発する際には、以下の点を考慮してください。

   メッセージ内容の解析

   DataWorks によってプッシュされるイベントメッセージのフォーマットについては、「開発者リファレンス：イベントリストとメッセージフォーマット」をご参照ください。メッセージフォーマットでは、messageBody にメッセージの具体的な内容が含まれます。開発中に、messageBody.eventCode フィールドを使用してメッセージタイプを識別し、messageId フィールドを使用してメッセージの詳細を取得できます。

   処理ロジック

   ビジネス要件に基づいてメッセージ処理ロジックを記述します。開発中に、以下のメソッドを使用して効率と効果を向上させることができます：

   • 高度な機能：拡張機能のパラメーターを設定する を使用します。たとえば、extension.project.disabled パラメーターを使用して、特定のワークスペースで拡張機能を無効にすることができます。

   • DataStudio モジュールに関連する拡張ポイントを処理する場合、GetIDEEventDetail 操作を呼び出し、MessageId を使用して拡張ポイントイベントがトリガーされた時点のデータスナップショットを取得します。

   説明

   MessageId パラメーターは、イベントメッセージの id フィールドに対応します。詳細については、「付録：DataWorks から EventBridge に送信されるメッセージのフォーマット」をご参照ください。

   処理結果

   ExtensionResponse の結果をパッケージングする際には、CheckResult を指定する必要があります。DataWorks は最終的な CheckResult を自動的に読み取り、プロセスが失敗したかどうかを判断します。

   • OK：この拡張ポイントイベントに対する拡張機能のチェックは合格しました。

   • FAIL：この拡張ポイントイベントに対する拡張機能のチェックは失敗しました。後続のプロセスが期待どおりに実行されるように、エラーを調査して解決する必要があります。

   • WARN：この拡張ポイントイベントに対する拡張機能のチェックは合格しましたが、警告が生成されました。

   サンプルコードファイル fc_dataworks_demo01-1.0-SNAPSHOT.jar をダウンロードし、Function Compute にアップロードして検証できます。以下のコードで詳細を説明します：

   コード詳細

   App.java

   このコードは PojoRequestHandler インターフェイスとその handleRequest メソッドを実装し、ExtensionRequest 型のリクエストと Context を受信します。処理ロジックを定義し、ExtensionResponse 型を使用して結果を返します。

   このコードサンプルは、ADS テーブルへの手動でのデータアップロードを禁止します。

   package com.aliyun.example;
   import com.alibaba.fastjson.JSON;
   import com.alibaba.fastjson.JSONObject;
   import com.aliyun.dataworks.ExtensionRequest;
   import com.aliyun.dataworks.ExtensionResponse;
   import com.aliyun.fc.runtime.Context;
   import com.aliyun.fc.runtime.PojoRequestHandler;
   public class App implements PojoRequestHandler<ExtensionRequest, ExtensionResponse> {
       public ExtensionResponse handleRequest(ExtensionRequest extensionRequest, Context context) {
           // デバッグ用にリクエスト内容を出力します。
            System.out.println(JSON.toJSONString(extensionRequest));
           // レスポンスオブジェクトを作成します。
           ExtensionResponse extensionResponse = new ExtensionResponse();
           // eventType が 'upload-data-to-table' であるかを確認します。
           if ("upload-data-to-table".equals(extensionRequest.getEventType())) {
               try {
                   // messageBody を文字列に変換し、JSONObject に解析します。
                   String messageBodyStr = JSON.toJSONString(extensionRequest.getMessageBody());
                   JSONObject messageBody = JSON.parseObject(messageBodyStr);
                   String tableGuid = messageBody.getString("tableGuid");
                   // tableGuid に 'ads' が含まれているかを確認します。
                   if (tableGuid != null && tableGuid.contains("ads")) {
                       extensionResponse.setCheckResult("FAIL");
                   } else {
                       extensionResponse.setCheckResult("OK");
                   }
               } catch (Exception e) {
                   extensionResponse.setCheckResult("FAIL");
                   extensionResponse.setErrorMessage("リクエストの処理中にエラーが発生しました: " + e.getMessage());
                   return extensionResponse;
               }
           } else {
               extensionResponse.setCheckResult("FAIL");
           }
           // フィードバック用のエラーメッセージを設定します。
           extensionResponse.setErrorMessage("これはテストです！");
           // レスポンスオブジェクトを返します。
           return extensionResponse;
       }
   }
   

   ExtensionRequest.java

   拡張機能のリクエスト構造を定義します。これは、DataWorks から送信されるイベントメッセージをカプセル化するために使用されます。

   public class ExtensionRequest {
       private Object messageBody;
       private String messageId;
       private String extensionBizId;
       private String extensionBizName;
       private String eventType;
       private String eventCategoryType;
       private Boolean blockBusiness;
       public ExtensionRequest() {
       }
       public Object getMessageBody() {
           return this.messageBody;
       }
       public void setMessageBody(Object messageBody) {
           this.messageBody = messageBody;
       }
       public String getMessageId() {
           return this.messageId;
       }
       public void setMessageId(String messageId) {
           this.messageId = messageId;
       }
       public String getExtensionBizId() {
           return this.extensionBizId;
       }
       public void setExtensionBizId(String extensionBizId) {
           this.extensionBizId = extensionBizId;
       }
       public String getExtensionBizName() {
           return this.extensionBizName;
       }
       public void setExtensionBizName(String extensionBizName) {
           this.extensionBizName = extensionBizName;
       }
       public String getEventType() {
           return this.eventType;
       }
       public void setEventType(String eventType) {
           this.eventType = eventType;
       }
       public String getEventCategoryType() {
           return this.eventCategoryType;
       }
       public void setEventCategoryType(String eventCategoryType) {
           this.eventCategoryType = eventCategoryType;
       }
       public Boolean getBlockBusiness() {
           return this.blockBusiness;
       }
       public void setBlockBusiness(Boolean blockBusiness) {
           this.blockBusiness = blockBusiness;
       }
   }

   ExtensionResponse.java

   拡張機能のレスポンス構造を定義します。これは、拡張機能の処理結果をカプセル化するために使用されます。

   public class ExtensionResponse {
       private String checkResult;
       private String errorMessage;
       public ExtensionResponse() {
       }
       public String getCheckResult() {
           return this.checkResult;
       }
       public void setCheckResult(String checkResult) {
           this.checkResult = checkResult;
       }
       public String getErrorMessage() {
           return this.errorMessage;
       }
       public void setErrorMessage(String errorMessage) {
           this.errorMessage = errorMessage;
       }
   }

2. コードを開発した後、プログラムを Function Compute で実行可能な .jar または .zip ファイルにパッケージングします。

   コードエディタでコマンドラインウィンドウを開き、ルートディレクトリに移動して、mvn clean package コマンドを実行してコードをパッケージングします。

   • コンパイルが失敗した場合は、出力されたエラーメッセージに基づいてコードを調整してください。

   • コンパイルが成功した場合、コンパイルされた JAR ファイルはプロジェクトの target ディレクトリにあります。ファイル名は、pom.xml ファイルの artifactId および version フィールドに基づいて付けられます (例：java-example-1.0-SNAPSHOT.jar)。

   説明

   macOS および Linux では、パッケージングする前にコードファイルに読み取りおよび実行権限があることを確認してください。

ステップ 1：拡張機能のデプロイ

1. Function Compute コンソール 2.0 にログインし、タスクページに移動します。

2. [関数の作成] をクリックしてサービスと必須の関数を作成し、拡張をデプロイします。開発された拡張からの特定のイベントメッセージは、このサービスに直接送信されます。詳細については、「サービスを作成する」および「関数を作成する」をご参照ください。[関数の作成] パネルで、[組み込みランタイムで作成] を選択し、ハンドラタイプに [イベントリクエストの処理] を選択し、コードのアップロード方法に [JAR パッケージ経由でコードをアップロード] を選択してから、準備したコードパッケージをアップロードします。

   • コードに基づいて実行環境を選択します。 ステップ 1 で提供されているサンプルパッケージ fc_dataworks_demo01-1.0-SNAPSHOT.jar は、Java 8 環境に対応しています。 fc_dataworks_demo01-1.0-SNAPSHOT.jar をローカルコンピューターにダウンロードし、[コードパッケージ] としてアップロードする必要があります。 要件に基づいてその他のパラメーターを設定します。

   • 関数の操作に関する詳細については、「関数の管理」をご参照ください。

3. 関数ハンドラを修正します。

   Function Compute コンソールでハンドラを設定できます。Java 関数の場合、ハンドラのフォーマットは [パッケージ名].[クラス名]::[メソッド名] です。例：

   • パッケージ名：example

   • クラス名：HelloFC

   • メソッド名：handleRequest

   ハンドラは example.HelloFC::handleRequest として設定できます。

   説明

   Function Compute のデフォルトのハンドラは example.App::handleRequest です。実際のコードに基づいてハンドラを修正する必要があります。ハンドラの詳細については、「ハンドラ」をご参照ください。

ステップ 2：関数のテスト

関数を作成したら、関数の詳細ページに移動し、[コード] タブをクリックし、[関数をテスト] をクリックします。メッセージ 実行が成功しました が返された場合は、DataWorks で拡張の登録に進むことができます。

ステップ 1：拡張機能の登録

Function Compute に拡張機能をデプロイした後、DataWorks に登録する必要があります。次の手順に従ってください：

1. DataWorks コンソールにログインします。 対象のリージョンで、左側のナビゲーションウィンドウから さらに表示 > オープンプラットフォーム をクリックします。 入力 オープンプラットフォーム をクリックして、[デベロッパーバックエンド] ページを開きます。

2. 拡張機能を登録します。

   1. 左側のナビゲーションウィンドウで、Extensions をクリックして拡張機能ページに移動します。

   2. List of Extensions > Register Extension をクリックし、Deploy Based on Function Compute を選択して、拡張機能情報を設定します。

      要件に基づいてパラメーターを設定できます。次の表にパラメーターを説明します。

   パラメーター

   パラメーター	説明
   Extension Name	拡張機能を識別するためのカスタム名。
   Function Compute のサービスと関数	拡張機能の Function Compute サービスと関数を選択します。イベントメッセージはこのサービスに送信されます。
   Processed Extension Points	データダウンロードの事前イベント、アセット公開・非公開の事前イベント、およびデータアップロードの事前イベントによってトリガーされたメッセージのみが処理できます。 説明 選択すると、Event および Applicable Service フィールドは自動的に入力されます。手動で設定する必要はありません。
   Owner	拡張機能のオーナー。ユーザーが問題に遭遇した場合に連絡できます。
   Workspace for Testing	拡張機能のテスト用ワークスペースを選択します。拡張機能は公開されずにテスト用ワークスペースでアクティブになります。 拡張機能を公開する前に、開発者はテスト用ワークスペースでエンドツーエンドのテストを実行できます。イベントをトリガーすることで、DataWorks が EventBridge を介してメッセージを送信するかどうか、および拡張機能がメッセージを受信、レビュー、コールバックを提供するかどうかをテストできます。 説明 Processed Extension Points にテナントレベルの拡張ポイントイベントを選択した場合、Workspace for Testing を設定する必要はありません。
   Extension Details Address	拡張機能の詳細を説明するページの URL を入力します。これにより、ユーザーが拡張機能を理解し、使用するのに役立ちます。 開発中に詳細ページを作成し、その URL をここで提供できます。これにより、チェックフローやブロックの理由など、チェックがトリガーされたときに完全な検証プロセスをユーザーが表示できるようになります。
   Extension Documentation Address	拡張機能のヘルプドキュメントの URL を入力します。 開発中にドキュメントページを作成し、その URL をここで提供できます。これにより、ユーザーが拡張機能の検証ロジックとプロパティを理解するのに役立ちます。
   Parameters for Extension	DataWorks では、パラメーターを使用して開発とアプリケーションの効率を向上させることができます。コード開発中に必要なパラメーターをここに追加します。 一般的なユースケースには組み込みパラメーターを使用するか、独自のパラメーターを定義できます。 複数のパラメーターを追加でき、key=value 形式で 1 行に 1 つのパラメーターを記述します。パラメーターの使用方法の詳細については、「高度なアプリケーション：拡張パラメーターの設定」をご参照ください。
   Options for Extension	ユーザーが利用できる設定オプションを入力します。これらのオプションにより、異なるワークスペースで拡張機能のパーソナライズされた制御が可能になります。拡張機能の開発者は、このインターフェイスでこれらのオプションを JSON 文字列として定義する必要があります。 たとえば、オプションを使用してユーザーが最大 SQL 長を制御できるようにすることができます。JSON フォーマットについては、「高度なアプリケーション：拡張オプションの設定」をご参照ください。

3. 登録を完了します。

   OK をクリックします。登録が完了すると、List of Extensions で拡張機能を表示できます。

ステップ 2：拡張機能の公開

DataWorks で拡張機能を開発、デプロイ、登録した後、テスト、承認、公開する必要があります。公開されると、拡張機能のオーナー以外の管理者が管理センターで拡張機能を有効にできます。詳細については、「拡張機能の適用」をご参照ください。