DataWorks:Function Compute に基づく拡張機能の開発とデプロイ

制限事項

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

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

注意事項

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

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

• ノード制限：機械学習 (PAI) ノード、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 などの高度な機能：拡張機能パラメーターの設定を使用して、特定のワークスペースで拡張機能を無効にします。

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

   説明

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

   処理結果を DataWorks に返す

   結果を ExtensionResponse オブジェクトにカプセル化する際、CheckResult フィールドで処理結果を指定する必要があります。DataWorks は、最終的な CheckResult を自動的に読み取り、操作が失敗したかどうかを判断します。

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

   • FAIL：拡張機能はこの拡張ポイントイベントのチェックに失敗しました。後続のプログラム実行への影響を防ぐために、エラーをタイムリーに確認し、処理する必要があります。

   • WARN：拡張機能はこの拡張ポイントイベントのチェックに合格しましたが、警告があります。

   サンプルコードパッケージ fc_dataworks_demo01-1.0-SNAPSHOT.jar をダウンロードし、検証とテストのために Function Compute にアップロードできます。次のセクションにコードを示します：

   コード詳細

   APP

   このコードは、Function Compute の PojoRequestHandler インターフェイスを使用して handleRequest メソッドを実装します。このメソッドは ExtensionRequest オブジェクトと Context を受け取り、処理ロジックを定義し、結果を ExtensionResponse オブジェクトとして返します。

   このコード例では、AnalyticDB for MySQL (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("Error processing request: " + e.getMessage());
                   return extensionResponse;
               }
           } else {
               extensionResponse.setCheckResult("FAIL");
           }
   
           // フィードバックとしてエラーメッセージを設定します。
           extensionResponse.setErrorMessage("This is a test!");
   
           // レスポンスオブジェクトを返します。
           return extensionResponse;
       }
   }
   
   

   ExtensionRequest

   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

   処理結果をカプセル化するための拡張機能のレスポンス構造を定義します。

   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. コードを開発した後、プログラムを実行可能な .jar または .zip パッケージにパッケージングし、後続の Function Compute での設定に備えます。

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

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

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

   説明

   macOS および Linux オペレーティングシステムの場合、パッケージングする前にコードファイルに読み取りおよび実行権限があることを確認してください。

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

1. Function Compute コンソールにログインします。左側のナビゲーションウィンドウで [タスク] をクリックして、[タスク] ページに移動します。

2. 関数の作成 をクリックして Function Compute サービスと必要な関数を作成し、拡張機能をデプロイします。その後、拡張機能は特定のイベントメッセージを作成されたサービスに直接送信します。詳細については、「サービスの作成」および「関数の作成」をご参照ください。次の図は、関数の設定方法を示しています。

   • コードに基づいてランタイム環境を選択します。ステップ 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. 左側のナビゲーションウィンドウで、拡張機能 をクリックします。

   2. 拡張機能リスト > 拡張機能の登録 をクリックし、Function Compute でデプロイ を選択して、拡張機能を設定します。

   必要に応じてパラメーターを設定できます。次の表にパラメーターを示します。

   パラメーターの説明

   パラメーター	設定方法
   拡張機能名	拡張機能のカスタム名。
   Function Compute サービスと関数	拡張機能がデプロイされている Function Compute サービスと関数。拡張機能は、特定のイベントメッセージをこのサービスに直接送信します。
   処理対象の拡張ポイント	現在、データダウンロードの事前イベント、資産の公開・非公開の事前イベント、およびデータアップロードの事前イベントによってトリガーされるメッセージのみがサポートされています。 説明 選択後、設定インターフェイスは イベント および 適用サービス パラメーターを自動的に照合します。手動での設定は不要です。
   オーナー	拡張機能のオーナー。これにより、ユーザーが問題に遭遇した場合にオーナーに連絡できます。
   テスト用ワークスペース	拡張機能のテストに使用されるワークスペース。拡張機能は、公開されなくてもテスト用ワークスペースで有効になります。 拡張機能が公開される前に、開発者はテスト用ワークスペースでエンドツーエンドテストを実行できます。イベントをトリガーして、DataWorks が EventBridge を使用してメッセージを送信するかどうか、拡張機能がメッセージを受信、レビュー、およびコールバックを送信するかどうかをテストできます。 説明 処理する拡張ポイント でテナントレベルの拡張ポイントイベントを選択した場合、テスト用ワークスペース を設定する必要はありません。
   拡張機能詳細アドレス	拡張機能に関する詳細を提供するページの URL。これにより、ユーザーは拡張機能をよりよく理解し、使用できます。 拡張機能を開発およびデプロイする際に、詳細ページを作成し、その URL をここで設定できます。これにより、拡張機能のチェックがトリガーされたときに、ユーザーはチェックパスやブロック理由などの完全な検証プロセスを表示できます。
   拡張機能ドキュメントアドレス	拡張機能のヘルプドキュメントの URL。これにより、ユーザーはドキュメントを読むことができます。 拡張機能を開発およびデプロイする際に、ヘルプドキュメントページを作成し、その URL をここで設定できます。これにより、ユーザーは拡張機能のチェックロジックとプロパティについて学ぶことができます。
   拡張機能パラメーター設定	DataWorks では、拡張機能の開発中にパラメーターを使用して効率を向上させることができます。使用したいパラメーターをここで拡張機能コードに追加します。 典型的なシナリオ向けに DataWorks が提供する組み込みパラメーターを使用するか、独自のカスタムパラメーターを定義できます。 key=value 形式で複数のパラメーターを追加できます。各パラメーターは別の行に記述する必要があります。これらのパラメーターの使用方法の詳細については、「高度な機能：拡張機能パラメーターの設定」をご参照ください。
   拡張機能オプション設定	拡張機能のユーザー向けの設定項目。これらの項目により、異なるワークスペースで拡張機能のパーソナライズされた管理が可能になります。拡張機能の開発者は、このインターフェイスでオプションを JSON 文字列として定義する必要があります。 例えば、拡張機能の開発者は、このパラメーターに基づいてユーザーが SQL 文の長さを管理できるようにすることができます。JSON フォーマットの詳細については、「高度な機能：拡張機能オプションの設定」をご参照ください。

3. 拡張機能の登録を完了します。

   OK をクリックして拡張機能を登録します。拡張機能は 拡張機能リスト に表示されます。

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

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